epoc32/include/apmrec.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    15 
    16 #if !defined(__APMREC_H__)
    17 #define __APMREC_H__
    18 
    19 #if !defined(__E32BASE_H__)
    20 #include <e32base.h>
    21 #endif
    22 
    23 #if !defined(__APMSTD_H__)
    24 #include <apmstd.h>
    25 #endif
    26 
    27 // classes defined
    28 class CApaDataRecognizerType;
    29 // classes referenced
    30 class RFs;
    31 class RFile;
    32 class TDataToRecognize;
    33 class CDataRecognizerExtension;
    34 
    35 /** Creates an interface object for a abstract base class for a recognizer.
    36 
    37 @publishedAll
    38 @released
    39 */
    40 typedef CApaDataRecognizerType* (*CreateCApaDataRecognizerType)(); 
    41 
    42 class TDataRecognitionResult
    43 /** The result of an attempt to recognize data.
    44 
    45 The class contains a data (MIME) type and a confidence rating.
    46 
    47 An object of this type is passed to the Application Architecture server when 
    48 making a request to recognize data.
    49 
    50 @publishedAll 
    51 @released 
    52 @see RApaLsSession::RecognizeData() */
    53 	{
    54 public:
    55 	IMPORT_C void Reset();
    56 public:
    57 	/** The data type. */
    58 	TDataType iDataType;
    59 	/** The confidence rating associated with the data (EMIME) type. */
    60 	TInt iConfidence;
    61 	};
    62 
    63 /**
    64 @internalComponent
    65 */
    66 const TInt KDataArrayGranularity=5;
    67 
    68 /**
    69 @publishedAll 
    70 @released 
    71 */
    72 typedef CArrayFixFlat<TDataType> CDataTypeArray;
    73 
    74 class CApaDataRecognizer : public CBase
    75 /**
    76 @internalTechnology
    77 */
    78 	{
    79 public:
    80 	IMPORT_C TDataRecognitionResult RecognizeL(const TDesC& aName, const TDesC8& aBuffer);
    81 	IMPORT_C TDataRecognitionResult RecognizeL(RFile& aFile, TInt aPreferredBufSize);
    82 	IMPORT_C TBool RecognizeL(const TDesC& aName, const TDesC8& aBuffer, const TDataType& aDataType);
    83 	IMPORT_C TBool RecognizeL(RFile& aFile, TInt aPreferredBufSize, const TDataType& aDataType);
    84 	IMPORT_C ~CApaDataRecognizer();
    85 	IMPORT_C TInt PreferredBufSize() const;
    86 	IMPORT_C void DataTypeL(CDataTypeArray& aArray);
    87 	IMPORT_C void UpdateDataTypesL();
    88 	IMPORT_C TInt AcceptedConfidence() const;
    89 	IMPORT_C void SetAcceptedConfidence(TInt aConfidence);
    90 	inline void SetFilePassedByHandle(RFile* aFilePassedByHandle) {iFilePassedByHandle=aFilePassedByHandle;}
    91 	inline RFile* FilePassedByHandle() {return iFilePassedByHandle;}
    92 protected:
    93 	IMPORT_C CApaDataRecognizer(RFs& aFs);
    94 	IMPORT_C void AddDataRecognizerTypeL(CApaDataRecognizerType* aDataRecognizerType);
    95 	inline void AddDataRecognizerType(CApaDataRecognizerType* aDataRecognizerType);
    96 	IMPORT_C TInt RemoveDataRecognizerType(const CApaDataRecognizerType* aDataRecognizerType);
    97 	IMPORT_C void DestroyRecognizerList();
    98 private:
    99 	void AddDataTypeL(const TDataType& aDataType);
   100 	TDataRecognitionResult RecognizeL(TDataToRecognize& aDataToRecognize);
   101 	TBool RecognizeL(TDataToRecognize& aDataToRecognize, const TDataType& aDataType);
   102 	TBool DoRecognize(CApaDataRecognizerType* aDataRecognizerType, TDataToRecognize& aDataToRecognize, const TDataType& aDataType, TInt& aError);
   103 protected:
   104 	RFs& iFs;
   105 	// iMaxBufferSize is mutable to allow modification by PreferredBufSize() which is const.
   106 	mutable TInt iMaxBufferSize; 
   107 private:
   108 	IMPORT_C virtual void CApaDataRecognizer_Reserved_1(); // shouldn't be necessary as the class is @internalTechnology
   109 private:
   110 	RPointerArray<CApaDataRecognizerType> iDataRecognizerList;
   111 	RArray<TDataType> iDataArray;
   112 	TInt iAcceptedConfidence;
   113 	TDataRecognitionResult iResult;
   114 	RFile* iFilePassedByHandle;
   115 	};
   116 
   117 class CApaDataRecognizerType : public CBase
   118 /** Abstract base class for a recognizer.
   119 
   120 Concrete recognizers need to define and implement a derived class; specifically, 
   121 they need to provide an implementation of the DoRecognizeL(), SupportedDataTypeL() 
   122 and PreferredBufSize() functions.
   123 
   124 The class is implemented as part of a DLL. The ordinal 1 function of the DLL 
   125 must construct an instance of, and return a pointer to, a CApaDataRecognizerType 
   126 derived class. 
   127 
   128 @publishedAll 
   129 @released */
   130 	{
   131 	friend class TDataToRecognize; // so that it can call the overloads of DoRecognizeL
   132 public:	
   133 	/** A set of values used to indicate the probability that the recognizer will successfully 
   134 	identify data. The Application Architecture framework uses this set to determine 
   135 	the order in which recognizers are invoked.
   136 
   137 	@see CApaDataRecognizerType()
   138 	@see Priority() */
   139 	enum TRecognizerPriority
   140 		{
   141 		/** The highest recognizer priority. Recognizers with this priority are invoked 
   142 		before those with any other priority. */
   143 		EHigh=100,
   144 		/** The normal recognizer priority. Recognizers with this priority are invoked 
   145 		after those with a EHigh priority but before those with a ELow priority. */
   146 		ENormal=0,
   147 		/** The lowest recognizer priority. */
   148 		ELow=-100
   149 		};		
   150 	/** A set of values describing the probability that the recognizer assigns to its 
   151 	belief that the most recently sampled data is of the type ascribed to it. */
   152  	enum TRecognitionConfidence
   153 		{
   154 		/** The data is definitely of the data type. */
   155 		ECertain=KMaxTInt,
   156 		/** A level of confidence between ECertain and EPossible. */
   157 		EProbable=100,
   158 		/** The data is possibly of the data type. */
   159 		EPossible=0,
   160 		/** A level of confidence between EPossible and ENotRecognized. */
   161 		EUnlikely=-100,
   162 		/** The data is not recognized. */
   163 		ENotRecognized=KMinTInt
   164 		};
   165 public:
   166 	inline TInt MimeTypesCount() const;
   167 	inline TUid TypeUid() const;
   168 	inline TInt Priority() const;
   169 	inline TInt Confidence() const;
   170 	inline TInt Locked() const;
   171 	IMPORT_C TDataRecognitionResult RecognizeL(const TDesC& aName, const TDesC8& aBuffer);
   172 	TDataRecognitionResult RecognizeL(TDataToRecognize& aDataToRecognize);
   173 	IMPORT_C TDataType MimeType();
   174 	IMPORT_C void Lock();
   175 	IMPORT_C void Unlock();
   176 	IMPORT_C void UpdateDataTypesL();
   177 	IMPORT_C ~CApaDataRecognizerType();
   178 	IMPORT_C virtual TUint PreferredBufSize();
   179 	/** Gets one of the data (MIME) types that the recognizer can recognize.
   180 	
   181 	@param aIndex An index that identifies the data type. Typically, the minimum 
   182 	value is zero and the maximum value is the value of MimeTypesCount() - 1.
   183 	@return The data (MIME) type. */
   184 	IMPORT_C virtual TDataType SupportedDataTypeL(TInt aIndex) const = 0;
   185 protected:
   186 	IMPORT_C CApaDataRecognizerType(TUid aUid, TInt aPriority);
   187 	IMPORT_C RFile* FilePassedByHandleL();
   188 private: 
   189 	IMPORT_C virtual void DoRecognizeL(const TDesC& aName, const TDesC8& aBuffer);
   190 	// Reserved virtual functions...
   191 	IMPORT_C virtual void Reserved_1();
   192 public:
   193 	IMPORT_C static CApaDataRecognizerType* CreateDataRecognizerL(TUid aImplUid);
   194 	CDataRecognizerExtension* DataRecognizerExtension();
   195 protected:
   196 	const TUid iTypeUid;
   197 	const TInt iPriority;
   198 	/** The number of data (MIME) types supported by this recognizer. Typically, this 
   199 	is set during construction of an instance of the derived class.
   200 	
   201 	Users of the derived class use MimeTypesCount() to get this value. */
   202 	TInt iCountDataTypes;
   203 	/** The recognizer's confidence rating of the most recently recognized data.
   204 	
   205 	Users of the derived class use Confidence() to get this value. */
   206 	TInt iConfidence;
   207 	/** The data (MIME) type of the most recently recognized data.
   208 	
   209 	Users of the derived class use MimeType() to get this value. */
   210 	TDataType iDataType;
   211 private:
   212 	TInt iLock;
   213 	CDataRecognizerExtension* iDataRecognizerExtn;
   214 	};
   215 
   216 #include <apmrec.inl>
   217 
   218 #endif