CApaDataRecognizerType Class Reference

#include <apmrec.h>

Link against: apmime.lib

class CApaDataRecognizerType : public CBase

Inherits from

CApaDataRecognizerType

Protected Attributes
TInt	iConfidence
TInt	iCountDataTypes
TDataType	iDataType
const TInt	iPriority
const TUid	iTypeUid

Public Member Enumerations
enum	TRecognitionConfidence { ECertain, EProbable, EPossible, EUnlikely, ENotRecognized }
enum	TRecognizerPriority { EHigh, ENormal, ELow }

Public Member Functions
	~CApaDataRecognizerType()
TInt	Confidence()
IMPORT_C CApaDataRecognizerType *	CreateDataRecognizerL(TUid)
CDataRecognizerExtension *	DataRecognizerExtension()
IMPORT_C void	Lock()
TInt	Locked()
IMPORT_C TDataType	MimeType()
TInt	MimeTypesCount()
virtual IMPORT_C TUint	PreferredBufSize()
TInt	Priority()
IMPORT_C TDataRecognitionResult	RecognizeL(const TDesC &, const TDesC8 &)
TDataRecognitionResult	RecognizeL(TDataToRecognize &)
pure virtual IMPORT_C TDataType	SupportedDataTypeL(TInt)
TUid	TypeUid()
IMPORT_C void	Unlock()
IMPORT_C void	UpdateDataTypesL()

Protected Member Functions
	CApaDataRecognizerType(TUid, TInt)
IMPORT_C RFile *	FilePassedByHandleL()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Abstract base class for a recognizer.

Concrete recognizers need to define and implement a derived class; specifically, they need to provide an implementation of the DoRecognizeL(), SupportedDataTypeL() and PreferredBufSize() functions.

The class is implemented as part of a DLL. The ordinal 1 function of the DLL must construct an instance of, and return a pointer to, a CApaDataRecognizerType derived class.

Member Attribute Documentation

iConfidence

TInt

iConfidence

[protected]

The recognizer's confidence rating of the most recently recognized data.

Users of the derived class use Confidence() to get this value.

iCountDataTypes

TInt

iCountDataTypes

[protected]

The number of data (MIME) types supported by this recognizer. Typically, this is set during construction of an instance of the derived class.

Users of the derived class use MimeTypesCount() to get this value.

iDataType

TDataType

iDataType

[protected]

The data (MIME) type of the most recently recognized data.

Users of the derived class use MimeType() to get this value.

iPriority

const TInt

iPriority

[protected]

iTypeUid

const TUid

iTypeUid

[protected]

Member Enumeration Documentation

Enum TRecognitionConfidence

A set of values describing the probability that the recognizer assigns to its belief that the most recently sampled data is of the type ascribed to it.

Enumerator	Value	Description
ECertain	KMaxTInt	The data is definitely of the data type.
EProbable	100	A level of confidence between ECertain and EPossible.
EPossible	0	The data is possibly of the data type.
EUnlikely	-100	A level of confidence between EPossible and ENotRecognized.
ENotRecognized	KMinTInt	The data is not recognized.

Enum TRecognizerPriority

A set of values used to indicate the probability that the recognizer will successfully identify data. The Application Architecture framework uses this set to determine the order in which recognizers are invoked.

Enumerator	Value	Description
EHigh	100	The highest recognizer priority. Recognizers with this priority are invoked before those with any other priority.
ENormal	0	The normal recognizer priority. Recognizers with this priority are invoked after those with a EHigh priority but before those with a ELow priority.
ELow	-100	The lowest recognizer priority.

Constructor & Destructor Documentation

CApaDataRecognizerType ( TUid, TInt )

IMPORT_C	CApaDataRecognizerType	(	TUid	aUid,
			TInt	aPriority
		)	[protected]

Constructs the recognizer with a UID and a priority.

Typically, a derived class constructor calls this constructor through a constructor initialization list.

The UID is the way that a recognizer is detected by the framework.

Parameter	Description
aUid	A UID that identifies the recognizer.
aPriority	A value that estimates the probability that the recognizer will successfully identify data. This is one of the CApaDataRecognizerType::TRecognizerPriority enumerators.

~CApaDataRecognizerType ( )

IMPORT_C

~CApaDataRecognizerType

(

)

Member Function Documentation

Confidence ( )

TInt

Confidence

(

)

const [inline]

Gets the recognizer's confidence rating for the most recently recognized data.

Returns: The confidence rating. This is one of the TRecognitionConfidence enumeration values.

CreateDataRecognizerL ( TUid )

IMPORT_C CApaDataRecognizerType *

CreateDataRecognizerL

(

TUid

aImplUid

)

[static]

DataRecognizerExtension ( )

CDataRecognizerExtension *

DataRecognizerExtension

(

)

FilePassedByHandleL ( )

IMPORT_C RFile *

FilePassedByHandleL

(

)

[protected]

Returns the RFile (if any) of file to be recognized.

This function returns the file passed by handle from the client-side (i.e. from calls to the RFile-parameter overloads of RApaLsSession's RecognizeData, RecognizeSpecificData, AppForDocument and StartDocument). The function returns NULL if the file to be recognized was not passed by handle.

It may only be called from implementations of DoRecognizeL - indeed the purpose of this function is logically to provide an extra parameter to the virtual DoRecognizeL function. All references/pointers to the RFile object returned must be discarded when the implementation of DoRecognizeL returns.

The RFile returned (if any) may be used by implementations of DoRecognizeL to retrieve more data than is provided in DoRecognizeL's aBuffer parameter.

The current-position of the returned RFile is the start of the file.

Lock ( )

IMPORT_C void

Lock

(

)

Adds a lock to the recognizer.

This may be called any number of times, but each call to this function must be matched by a corresponding call to Unlock() to completely unlock the recognizer.

This function is used to prevent the recognizer DLL from being unloaded.

Locked ( )

TInt

Locked

(

)

const [inline]

Tests whether the recognizer is locked.

MimeType ( )

IMPORT_C TDataType

MimeType

(

)

Gets the data (MIME) type of the most recently recognized data.

MimeTypesCount ( )

TInt

MimeTypesCount

(

)

const [inline]

Gets the number of data (MIME) types supported by this recognizer.

PreferredBufSize ( )

IMPORT_C TUint

PreferredBufSize

(

)

[virtual]

Gets the size of buffer preferred for the purpose of recognizing the data type.

Regardless of the preferred buffer size returned by an implementation of this function, the actual size used is never greater than a maximum value as set by the client of the Application Architecture server through a call to RApaLsSession::SetMaxDataBufSize().

See also: RApaLsSession::SetMaxDataBufSize()

Returns: The preferred data size. The default implementation returns zero.

Priority ( )

TInt

Priority

(

)

const [inline]

Gets the recognizer's priority.

The priority defines the likelihood that the recognizer will successfully identify data. This is one of the CApaDataRecognizerType::TRecognizerPriority enumerators.

Returns: The priority value.

RecognizeL ( const TDesC &, const TDesC8 & )

IMPORT_C TDataRecognitionResult	RecognizeL	(	const TDesC &	aName,
			const TDesC8 &	aBuffer
		)

Attempts to recognize data.

This function is called by the Application Architecture server as a result of client calls to the server through an instance of RApaLsSession.

The function calls DoRecognizeL() which implements recognition behaviour.

See also: PreferredBufSize() RApaLsSession RApaLsSession::SetMaxDataBufSize()

Parameter	Description
aName	The name of the data; typically this is a file name containing the data to be recognized.
aBuffer	A buffer containing data to be recognized; typically, this is read from the start of the file containing the data. Implement PreferredBufSize() to define the ideal size for this buffer. Note that failure to implement PreferredBufSize() results in a default buffer size of zero.

Returns: The result of the attempt to recognize the data.

RecognizeL ( TDataToRecognize & )

TDataRecognitionResult

RecognizeL

(

TDataToRecognize &

aDataToRecognize

)

SupportedDataTypeL ( TInt )

IMPORT_C TDataType

SupportedDataTypeL

(

TInt

aIndex

)

const [pure virtual]

Gets one of the data (MIME) types that the recognizer can recognize.

Parameter	Description
aIndex	An index that identifies the data type. Typically, the minimum value is zero and the maximum value is the value of MimeTypesCount() - 1.

Returns: The data (MIME) type.

TypeUid ( )

TUid

TypeUid

(

)

const [inline]

Gets the UID that identifies the recognizer.

Returns: The UID.

Unlock ( )

IMPORT_C void

Unlock

(

)

Removes a lock from the recognizer.

All calls to Lock() should be matched by a corresponding call to this function. The recognizer is not unlocked until all calls to Lock() have been matched by corresponding calls to this function.

UpdateDataTypesL ( )

IMPORT_C void

UpdateDataTypesL

(

)

Refreshes the list of data (MIME) types supported by this recognizer.