epoc32/include/conarc.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
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(__CONARC_H__)
    17 #define __CONARC_H__
    18 
    19 #if !defined(__E32BASE_H__)
    20 #include <e32base.h>
    21 #endif
    22 #if !defined(__APMSTD_H__)
    23 #include <apmstd.h>
    24 #endif
    25 
    26 //
    27 // base interface for converters
    28 //
    29 
    30 /**
    31 @publishedAll
    32 @released
    33 */
    34 const TInt KUidConverterToBase64=0x10000721;
    35 /**
    36 @publishedAll
    37 @released
    38 */
    39 const TInt KUidConverterFromBase64=0x100011C5;
    40 /**
    41 @publishedAll
    42 @released
    43 */
    44 const TInt KUidPlainTextToQuotedPrintableConverter=0x10001826;
    45 /**
    46 @publishedAll
    47 @released
    48 */
    49 const TInt KUidQuotedPrintableToPlainTextConverter=0x10001825;
    50 /**
    51 @publishedAll
    52 @released
    53 */
    54 const TInt KUidETextToPlainTextConverter=
    55 #if defined(ETEXT_CONVERTER_UIDS_CORRECTED)
    56 	0x100040c8;
    57 #else
    58 	0x100040c7;
    59 #endif
    60  
    61 /**
    62 @publishedAll
    63 @released
    64 */
    65 const TInt KUidPlainTextToETextConverter=
    66 #if defined(ETEXT_CONVERTER_UIDS_CORRECTED)
    67 	0x100040c7;
    68 #else
    69 	0x100040c8;
    70 #endif
    71  
    72 /**
    73 @publishedAll
    74 @released
    75 */
    76 #ifdef _UNICODE
    77 #define KUidConverterDll KUidConverterDll16
    78 #else
    79 #define KUidConverterDll KUidConverterDll8
    80 #endif
    81 
    82 /**
    83 @internalComponent
    84 @deprecated
    85 */
    86 const TInt KUidConverterDllValue8=0x10000C61;
    87 
    88 /**
    89 @internalComponent
    90 @deprecated
    91 */
    92 const TUid KUidConverterDll8={KUidConverterDllValue8};
    93 
    94 /**
    95 @internalComponent
    96 */
    97 const TInt KUidConverterInfoFileValue=0x10000C62;
    98 
    99 /**
   100 @publishedAll
   101 @released
   102 */
   103 const TUid KUidConverterInfoFile={KUidConverterInfoFileValue};
   104 
   105 /**
   106 @internalComponent
   107 */
   108 const TInt KUidConverterInfoStreamValue=0x10000CD0;
   109 
   110 /**
   111 @internalComponent
   112 */
   113 const TUid KUidConverterInfoStream={KUidConverterInfoStreamValue};
   114 
   115 /**
   116 The UID2 of converter-type DLLs.
   117 @publishedAll
   118 @released
   119 */
   120 const TUid KUidConverterDll16={0x10003A30};
   121 
   122 /**
   123 The extension of converter information files.
   124 @publishedAll
   125 @released
   126 */
   127 _LIT(KConverterInfoFileExtension,".CNF");
   128 /**
   129 The extension of converter DLLs.
   130 @publishedAll
   131 @released
   132 */
   133 _LIT(KConverterDllExtension,".CNV");
   134 
   135 
   136 class MConverterUiObserver
   137 /**
   138 Interface implemented by the client of a conversion operation to observe conversion 
   139 progress.
   140 
   141 @see CConverterBase2
   142 @publishedAll 
   143 @released
   144 */
   145 	{
   146 public:
   147 	/** Describes the result of a conversion operation. */
   148 	enum TResult
   149 		{
   150 		/** Conversion succeeded. */
   151 		ESuccess,
   152 		/** Conversion partially succeeded. */
   153 		EPartialSuccess,
   154 		/** Conversion failed. */
   155 		EFailure
   156 		};
   157 	/** Describes the actions that the converter should take. */
   158 	enum TAction
   159 		{
   160 		/** Keep already converted data. */
   161 		ERetain,
   162 		/** Delete converted data. */
   163 		ERemove,
   164 		/** Reconvert data. */
   165 		ERepeat
   166 		}; 
   167 public:
   168 	/** Gets the maximum number of steps that the conversion operation can take. 
   169 	
   170 	The conversion may complete in less than this number of steps (for example 
   171 	if an error occurs or the action is cancelled). 
   172 	
   173 	Each step is a call to CConverterBase2::DoConvert(), although during synchronous 
   174 	conversions this is transparent to the client code.
   175 	
   176 	@param aMax Maximum number of conversion steps.
   177 	@param aObject Index that identifies an embedded object when one is being converted. */
   178 	virtual void MaxSteps(TInt aMax, TInt aObject)=0;
   179 	/** Alerts the client to an error in conversion.
   180 	
   181 	@param aResult A TResult value indicating the conversion state.
   182 	@param aObject Index that identifies an embedded object when one is being converted.
   183 	@return A TAction value that indicates what action the converter should take. */
   184 	virtual TInt Result(TInt aResult, TInt aObject)=0;
   185 	/** Queries the client for a password in order to access the data.
   186 	
   187 	@param aClue Data with a meaning that is specific to each converter: it could for 
   188 	example indicate where the password is stored.
   189 	@return The password entered. */
   190 	virtual HBufC* QueryPasswordL(const TDesC& aClue)=0;
   191 	IMPORT_C virtual void Reserved1_Conv_Obs();
   192 	};
   193 
   194 
   195 class CConverterBase : public CBase
   196 /** For Ecom Style Converters i.e.,for v9.1 and above CConverterBase2 should be used.
   197 
   198 Polymorphic interface for converters from one data format to another.
   199 
   200 Clients use this interface to access data converters. The implementator of 
   201 a data converter derives a class from this in which to implement the appropriate 
   202 conversion functionality.
   203 
   204 The interface offers conversions between files, and between objects that support 
   205 the stream interfaces, e.g. stream stores.
   206 
   207 There are two flavours of conversion methods:
   208 
   209 the synchronous interfaces, ConvertL() and ConvertObjectL(), which perform 
   210 the specified conversion and then return
   211 
   212 the asynchronous interfaces, ConvertAL() and ConvertObjectAL(), which initialise 
   213 the converter object, and allow the client code to call DoConvertL() a number 
   214 of times until the conversion is complete or abandoned.
   215 
   216 @see CConverterBase2
   217 @publishedAll
   218 @released  */
   219 	{
   220 public:
   221 	/** Bitmask values that describe the capabilities of the converter. */
   222 	enum TCapability
   223 		{
   224 		/** The converter can convert files. */
   225 		EConvertsFiles=0x01,
   226 		/** The converter can convert stream objects. */
   227 		EConvertsObjects=0x02,
   228 		/** The converter can extract embedded objects. */
   229 		EConvertsExtract=0x04
   230 		};
   231 public:
   232 	IMPORT_C virtual void ConvertL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // These default to calling the async versions in a loop
   233 	IMPORT_C virtual void ConvertObjectL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL);
   234 	IMPORT_C virtual void ConvertAL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
   235 	IMPORT_C virtual void ConvertObjectAL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
   236 	IMPORT_C virtual TBool DoConvertL(); // these default to leaving with KErrNotSupported
   237 	/** Gets the converter's UID.
   238 	
   239 	@return Converter's UID */
   240 	virtual TUid Uid() =0;
   241 	IMPORT_C virtual TInt Capabilities(); // defaults to "everything"
   242 	IMPORT_C virtual void CancelConvert(); // for any cleanup
   243 	IMPORT_C virtual CConverterBase* EmbeddedObjectL(TDataType& aType);
   244 	IMPORT_C virtual TBool GetEmbeddedFileName(TFileName& aFileName);
   245 	IMPORT_C virtual void ExtendedInterfaceL(TUid aInterfaceUid, CBase*& aInterface); 
   246 	};
   247 
   248 
   249 class CConverterLibrary : public CBase
   250 /** A converter DLL's factory for individual CConverterBase-derived objects.
   251 
   252 The implementor of a converter DLL should implement this class. 
   253 
   254 @publishedAll 
   255 @deprecated */
   256 	{
   257 public:
   258 	/** Creates and returns an instance of the converter with the specified UID.
   259 	
   260 	This class should not allocate any resources that are not returned to the 
   261 	caller.
   262 	
   263 	@param aUid UID of the converter to create
   264 	@return The specified converter. If the converter does not implement a converter 
   265 	associated with the UID, then it should return NULL. */
   266 	virtual CConverterBase* Converter(TUid aUid)=0;	// passes ownership
   267 	};
   268 
   269 class CConverterBase2 : public CConverterBase
   270 /** Base Class for Ecom Style Converters
   271 The methods in CConverterBase2 are inherited from CConverterBase
   272 
   273 There are two flavours of conversion methods:
   274 
   275 the synchronous interfaces, ConvertL() and ConvertObjectL(), which perform 
   276 the specified conversion and then return
   277 
   278 the asynchronous interfaces, ConvertAL() and ConvertObjectAL(), which initialise 
   279 the converter object, and allow the client code to call DoConvertL() a number 
   280 of times until the conversion is complete or abandoned.
   281 
   282 @publishedAll
   283 @released  */
   284 	{
   285 public:
   286 	static CConverterBase2* CreateConverterL(TUid aImplUid);
   287 	IMPORT_C virtual ~CConverterBase2(); 
   288 	IMPORT_C virtual void ConvertL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // These default to calling the async versions in a loop
   289 	IMPORT_C virtual void ConvertObjectL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL);
   290 	IMPORT_C virtual void ConvertAL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
   291 	IMPORT_C virtual void ConvertObjectAL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
   292 	IMPORT_C virtual TBool DoConvertL(); // these default to leaving with KErrNotSupported
   293 	virtual  TUid Uid()=0;
   294 	IMPORT_C virtual TInt Capabilities(); // defaults to "everything"
   295 	IMPORT_C virtual void CancelConvert(); // for any cleanup
   296 	IMPORT_C virtual CConverterBase* EmbeddedObjectL(TDataType& aType);
   297 	IMPORT_C virtual TBool GetEmbeddedFileName(TFileName& aFileName);
   298 	IMPORT_C virtual void ExtendedInterfaceL(TUid aInterfaceUid, CBase*& aInterface);
   299 	IMPORT_C virtual void Reserved_1();
   300 	IMPORT_C virtual void Reserved_2();
   301 private:
   302 	TUid iDestructionKey;
   303 	TInt iSpare;
   304 	};
   305 #endif