sl@0: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #if !defined(__APMREC_H__)
sl@0: #define __APMREC_H__
sl@0: 
sl@0: #if !defined(__E32BASE_H__)
sl@0: #include <e32base.h>
sl@0: #endif
sl@0: 
sl@0: #if !defined(__APMSTD_H__)
sl@0: #include <apmstd.h>
sl@0: #endif
sl@0: 
sl@0: // classes defined
sl@0: class CApaDataRecognizerType;
sl@0: // classes referenced
sl@0: class RFs;
sl@0: class RFile;
sl@0: class TDataToRecognize;
sl@0: class CDataRecognizerExtension;
sl@0: 
sl@0: /** Creates an interface object for a abstract base class for a recognizer.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: typedef CApaDataRecognizerType* (*CreateCApaDataRecognizerType)(); 
sl@0: 
sl@0: class TDataRecognitionResult
sl@0: /** The result of an attempt to recognize data.
sl@0: 
sl@0: The class contains a data (MIME) type and a confidence rating.
sl@0: 
sl@0: An object of this type is passed to the Application Architecture server when 
sl@0: making a request to recognize data.
sl@0: 
sl@0: @publishedAll 
sl@0: @released 
sl@0: @see RApaLsSession::RecognizeData() */
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C void Reset();
sl@0: public:
sl@0: 	/** The data type. */
sl@0: 	TDataType iDataType;
sl@0: 	/** The confidence rating associated with the data (EMIME) type. */
sl@0: 	TInt iConfidence;
sl@0: 	};
sl@0: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: /**
sl@0: @internalComponent
sl@0: */
sl@0: const TInt KDataArrayGranularity=5;
sl@0: 
sl@0: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: /**
sl@0: @publishedAll 
sl@0: @released 
sl@0: */
sl@0: typedef CArrayFixFlat<TDataType> CDataTypeArray;
sl@0: 
sl@0: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: 
sl@0: class CApaDataRecognizer : public CBase
sl@0: /**
sl@0: @internalTechnology
sl@0: */
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C TDataRecognitionResult RecognizeL(const TDesC& aName, const TDesC8& aBuffer);
sl@0: 	IMPORT_C TDataRecognitionResult RecognizeL(RFile& aFile, TInt aPreferredBufSize);
sl@0: 	IMPORT_C TBool RecognizeL(const TDesC& aName, const TDesC8& aBuffer, const TDataType& aDataType);
sl@0: 	IMPORT_C TBool RecognizeL(RFile& aFile, TInt aPreferredBufSize, const TDataType& aDataType);
sl@0: 	IMPORT_C ~CApaDataRecognizer();
sl@0: 	IMPORT_C TInt PreferredBufSize() const;
sl@0: 	IMPORT_C void DataTypeL(CDataTypeArray& aArray);
sl@0: 	IMPORT_C void UpdateDataTypesL();
sl@0: 	IMPORT_C TInt AcceptedConfidence() const;
sl@0: 	IMPORT_C void SetAcceptedConfidence(TInt aConfidence);
sl@0: 	inline void SetFilePassedByHandle(RFile* aFilePassedByHandle) {iFilePassedByHandle=aFilePassedByHandle;}
sl@0: 	inline RFile* FilePassedByHandle() {return iFilePassedByHandle;}
sl@0: protected:
sl@0: 	IMPORT_C CApaDataRecognizer(RFs& aFs);
sl@0: 	IMPORT_C void AddDataRecognizerTypeL(CApaDataRecognizerType* aDataRecognizerType);
sl@0: 	inline void AddDataRecognizerType(CApaDataRecognizerType* aDataRecognizerType);
sl@0: 	IMPORT_C TInt RemoveDataRecognizerType(const CApaDataRecognizerType* aDataRecognizerType);
sl@0: 	IMPORT_C void DestroyRecognizerList();
sl@0: private:
sl@0: 	void AddDataTypeL(const TDataType& aDataType);
sl@0: 	TDataRecognitionResult RecognizeL(TDataToRecognize& aDataToRecognize);
sl@0: 	TBool RecognizeL(TDataToRecognize& aDataToRecognize, const TDataType& aDataType);
sl@0: 	TBool DoRecognize(CApaDataRecognizerType* aDataRecognizerType, TDataToRecognize& aDataToRecognize, const TDataType& aDataType, TInt& aError);
sl@0: protected:
sl@0: 	RFs& iFs;
sl@0: 	// iMaxBufferSize is mutable to allow modification by PreferredBufSize() which is const.
sl@0: 	mutable TInt iMaxBufferSize; 
sl@0: private:
sl@0: 	IMPORT_C virtual void CApaDataRecognizer_Reserved_1(); // shouldn't be necessary as the class is @internalTechnology
sl@0: private:
sl@0: 	RPointerArray<CApaDataRecognizerType> iDataRecognizerList;
sl@0: 	RArray<TDataType> iDataArray;
sl@0: 	TInt iAcceptedConfidence;
sl@0: 	TDataRecognitionResult iResult;
sl@0: 	RFile* iFilePassedByHandle;
sl@0: 	};
sl@0: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: 
sl@0: class CApaDataRecognizerType : public CBase
sl@0: /** Abstract base class for a recognizer.
sl@0: 
sl@0: Concrete recognizers need to define and implement a derived class; specifically, 
sl@0: they need to provide an implementation of the DoRecognizeL(), SupportedDataTypeL() 
sl@0: and PreferredBufSize() functions.
sl@0: 
sl@0: The class is implemented as part of a DLL. The ordinal 1 function of the DLL 
sl@0: must construct an instance of, and return a pointer to, a CApaDataRecognizerType 
sl@0: derived class. 
sl@0: 
sl@0: @publishedAll 
sl@0: @released */
sl@0: 	{
sl@0: 	friend class TDataToRecognize; // so that it can call the overloads of DoRecognizeL
sl@0: public:	
sl@0: 	/** A set of values used to indicate the probability that the recognizer will successfully 
sl@0: 	identify data. The Application Architecture framework uses this set to determine 
sl@0: 	the order in which recognizers are invoked.
sl@0: 
sl@0: 	@see CApaDataRecognizerType()
sl@0: 	@see Priority() */
sl@0: 	enum TRecognizerPriority
sl@0: 		{
sl@0: 		/** The highest recognizer priority. Recognizers with this priority are invoked 
sl@0: 		before those with any other priority. */
sl@0: 		EHigh=100,
sl@0: 		/** The normal recognizer priority. Recognizers with this priority are invoked 
sl@0: 		after those with a EHigh priority but before those with a ELow priority. */
sl@0: 		ENormal=0,
sl@0: 		/** The lowest recognizer priority. */
sl@0: 		ELow=-100
sl@0: 		};		
sl@0: 	/** A set of values describing the probability that the recognizer assigns to its 
sl@0: 	belief that the most recently sampled data is of the type ascribed to it. */
sl@0:  	enum TRecognitionConfidence
sl@0: 		{
sl@0: 		/** The data is definitely of the data type. */
sl@0: 		ECertain=KMaxTInt,
sl@0: 		/** A level of confidence between ECertain and EPossible. */
sl@0: 		EProbable=100,
sl@0: 		/** The data is possibly of the data type. */
sl@0: 		EPossible=0,
sl@0: 		/** A level of confidence between EPossible and ENotRecognized. */
sl@0: 		EUnlikely=-100,
sl@0: 		/** The data is not recognized. */
sl@0: 		ENotRecognized=KMinTInt
sl@0: 		};
sl@0: public:
sl@0: 	inline TInt MimeTypesCount() const;
sl@0: 	inline TUid TypeUid() const;
sl@0: 	inline TInt Priority() const;
sl@0: 	inline TInt Confidence() const;
sl@0: 	inline TInt Locked() const;
sl@0: 	IMPORT_C TDataRecognitionResult RecognizeL(const TDesC& aName, const TDesC8& aBuffer);
sl@0: 	TDataRecognitionResult RecognizeL(TDataToRecognize& aDataToRecognize);
sl@0: 	IMPORT_C TDataType MimeType();
sl@0: 	IMPORT_C void Lock();
sl@0: 	IMPORT_C void Unlock();
sl@0: 	IMPORT_C void UpdateDataTypesL();
sl@0: 	IMPORT_C ~CApaDataRecognizerType();
sl@0: 	IMPORT_C virtual TUint PreferredBufSize();
sl@0: 	/** Gets one of the data (MIME) types that the recognizer can recognize.
sl@0: 	
sl@0: 	@param aIndex An index that identifies the data type. Typically, the minimum 
sl@0: 	value is zero and the maximum value is the value of MimeTypesCount() - 1.
sl@0: 	@return The data (MIME) type. */
sl@0: 	IMPORT_C virtual TDataType SupportedDataTypeL(TInt aIndex) const = 0;
sl@0: protected:
sl@0: 	IMPORT_C CApaDataRecognizerType(TUid aUid, TInt aPriority);
sl@0: 	IMPORT_C RFile* FilePassedByHandleL();
sl@0: private: 
sl@0: 	IMPORT_C virtual void DoRecognizeL(const TDesC& aName, const TDesC8& aBuffer);
sl@0: 	// Reserved virtual functions...
sl@0: 	IMPORT_C virtual void Reserved_1();
sl@0: public:
sl@0: 	IMPORT_C static CApaDataRecognizerType* CreateDataRecognizerL(TUid aImplUid);
sl@0: 	CDataRecognizerExtension* DataRecognizerExtension();
sl@0: protected:
sl@0: 	const TUid iTypeUid;
sl@0: 	const TInt iPriority;
sl@0: 	/** The number of data (MIME) types supported by this recognizer. Typically, this 
sl@0: 	is set during construction of an instance of the derived class.
sl@0: 	
sl@0: 	Users of the derived class use MimeTypesCount() to get this value. */
sl@0: 	TInt iCountDataTypes;
sl@0: 	/** The recognizer's confidence rating of the most recently recognized data.
sl@0: 	
sl@0: 	Users of the derived class use Confidence() to get this value. */
sl@0: 	TInt iConfidence;
sl@0: 	/** The data (MIME) type of the most recently recognized data.
sl@0: 	
sl@0: 	Users of the derived class use MimeType() to get this value. */
sl@0: 	TDataType iDataType;
sl@0: private:
sl@0: 	TInt iLock;
sl@0: 	CDataRecognizerExtension* iDataRecognizerExtn;
sl@0: 	};
sl@0: 
sl@0: #include <apmrec.inl>
sl@0: 
sl@0: #endif