williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__CONARC_H__)
williamr@2: #define __CONARC_H__
williamr@2: 
williamr@2: #if !defined(__E32BASE_H__)
williamr@2: #include <e32base.h>
williamr@2: #endif
williamr@2: #if !defined(__APMSTD_H__)
williamr@2: #include <apmstd.h>
williamr@2: #endif
williamr@2: 
williamr@2: //
williamr@2: // base interface for converters
williamr@2: //
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KUidConverterToBase64=0x10000721;
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KUidConverterFromBase64=0x100011C5;
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KUidPlainTextToQuotedPrintableConverter=0x10001826;
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KUidQuotedPrintableToPlainTextConverter=0x10001825;
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KUidETextToPlainTextConverter=
williamr@2: #if defined(ETEXT_CONVERTER_UIDS_CORRECTED)
williamr@2: 	0x100040c8;
williamr@2: #else
williamr@2: 	0x100040c7;
williamr@2: #endif
williamr@2:  
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TInt KUidPlainTextToETextConverter=
williamr@2: #if defined(ETEXT_CONVERTER_UIDS_CORRECTED)
williamr@2: 	0x100040c7;
williamr@2: #else
williamr@2: 	0x100040c8;
williamr@2: #endif
williamr@2:  
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #ifdef _UNICODE
williamr@2: #define KUidConverterDll KUidConverterDll16
williamr@2: #else
williamr@2: #define KUidConverterDll KUidConverterDll8
williamr@2: #endif
williamr@2: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@2: /**
williamr@2: @internalComponent
williamr@2: @deprecated
williamr@2: */
williamr@2: const TInt KUidConverterDllValue8=0x10000C61;
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: @deprecated
williamr@2: */
williamr@2: const TUid KUidConverterDll8={KUidConverterDllValue8};
williamr@2: 
williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: 
williamr@4: //gmahe. This needs to be promoted to publishedAll.
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: const TInt KUidConverterInfoFileValue=0x10000C62;
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUid KUidConverterInfoFile={KUidConverterInfoFileValue};
williamr@2: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: const TInt KUidConverterInfoStreamValue=0x10000CD0;
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: const TUid KUidConverterInfoStream={KUidConverterInfoStreamValue};
williamr@2: 
williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@2: /**
williamr@2: The UID2 of converter-type DLLs.
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUid KUidConverterDll16={0x10003A30};
williamr@2: 
williamr@2: /**
williamr@2: The extension of converter information files.
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: _LIT(KConverterInfoFileExtension,".CNF");
williamr@2: /**
williamr@2: The extension of converter DLLs.
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: _LIT(KConverterDllExtension,".CNV");
williamr@2: 
williamr@2: 
williamr@2: class MConverterUiObserver
williamr@2: /**
williamr@2: Interface implemented by the client of a conversion operation to observe conversion 
williamr@2: progress.
williamr@2: 
williamr@2: @see CConverterBase2
williamr@2: @publishedAll 
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Describes the result of a conversion operation. */
williamr@2: 	enum TResult
williamr@2: 		{
williamr@2: 		/** Conversion succeeded. */
williamr@2: 		ESuccess,
williamr@2: 		/** Conversion partially succeeded. */
williamr@2: 		EPartialSuccess,
williamr@2: 		/** Conversion failed. */
williamr@2: 		EFailure
williamr@2: 		};
williamr@2: 	/** Describes the actions that the converter should take. */
williamr@2: 	enum TAction
williamr@2: 		{
williamr@2: 		/** Keep already converted data. */
williamr@2: 		ERetain,
williamr@2: 		/** Delete converted data. */
williamr@2: 		ERemove,
williamr@2: 		/** Reconvert data. */
williamr@2: 		ERepeat
williamr@2: 		}; 
williamr@2: public:
williamr@2: 	/** Gets the maximum number of steps that the conversion operation can take. 
williamr@2: 	
williamr@2: 	The conversion may complete in less than this number of steps (for example 
williamr@2: 	if an error occurs or the action is cancelled). 
williamr@2: 	
williamr@2: 	Each step is a call to CConverterBase2::DoConvert(), although during synchronous 
williamr@2: 	conversions this is transparent to the client code.
williamr@2: 	
williamr@2: 	@param aMax Maximum number of conversion steps.
williamr@2: 	@param aObject Index that identifies an embedded object when one is being converted. */
williamr@2: 	virtual void MaxSteps(TInt aMax, TInt aObject)=0;
williamr@2: 	/** Alerts the client to an error in conversion.
williamr@2: 	
williamr@2: 	@param aResult A TResult value indicating the conversion state.
williamr@2: 	@param aObject Index that identifies an embedded object when one is being converted.
williamr@2: 	@return A TAction value that indicates what action the converter should take. */
williamr@2: 	virtual TInt Result(TInt aResult, TInt aObject)=0;
williamr@2: 	/** Queries the client for a password in order to access the data.
williamr@2: 	
williamr@2: 	@param aClue Data with a meaning that is specific to each converter: it could for 
williamr@2: 	example indicate where the password is stored.
williamr@2: 	@return The password entered. */
williamr@2: 	virtual HBufC* QueryPasswordL(const TDesC& aClue)=0;
williamr@2: 	IMPORT_C virtual void Reserved1_Conv_Obs();
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CConverterBase : public CBase
williamr@2: /** For Ecom Style Converters i.e.,for v9.1 and above CConverterBase2 should be used.
williamr@2: 
williamr@2: Polymorphic interface for converters from one data format to another.
williamr@2: 
williamr@2: Clients use this interface to access data converters. The implementator of 
williamr@2: a data converter derives a class from this in which to implement the appropriate 
williamr@2: conversion functionality.
williamr@2: 
williamr@2: The interface offers conversions between files, and between objects that support 
williamr@2: the stream interfaces, e.g. stream stores.
williamr@2: 
williamr@2: There are two flavours of conversion methods:
williamr@2: 
williamr@2: the synchronous interfaces, ConvertL() and ConvertObjectL(), which perform 
williamr@2: the specified conversion and then return
williamr@2: 
williamr@2: the asynchronous interfaces, ConvertAL() and ConvertObjectAL(), which initialise 
williamr@2: the converter object, and allow the client code to call DoConvertL() a number 
williamr@2: of times until the conversion is complete or abandoned.
williamr@2: 
williamr@2: @see CConverterBase2
williamr@2: @publishedAll
williamr@2: @released  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Bitmask values that describe the capabilities of the converter. */
williamr@2: 	enum TCapability
williamr@2: 		{
williamr@2: 		/** The converter can convert files. */
williamr@2: 		EConvertsFiles=0x01,
williamr@2: 		/** The converter can convert stream objects. */
williamr@2: 		EConvertsObjects=0x02,
williamr@2: 		/** The converter can extract embedded objects. */
williamr@2: 		EConvertsExtract=0x04
williamr@2: 		};
williamr@2: public:
williamr@2: 	IMPORT_C virtual void ConvertL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // These default to calling the async versions in a loop
williamr@2: 	IMPORT_C virtual void ConvertObjectL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL);
williamr@2: 	IMPORT_C virtual void ConvertAL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
williamr@2: 	IMPORT_C virtual void ConvertObjectAL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
williamr@2: 	IMPORT_C virtual TBool DoConvertL(); // these default to leaving with KErrNotSupported
williamr@2: 	/** Gets the converter's UID.
williamr@2: 	
williamr@2: 	@return Converter's UID */
williamr@2: 	virtual TUid Uid() =0;
williamr@2: 	IMPORT_C virtual TInt Capabilities(); // defaults to "everything"
williamr@2: 	IMPORT_C virtual void CancelConvert(); // for any cleanup
williamr@2: 	IMPORT_C virtual CConverterBase* EmbeddedObjectL(TDataType& aType);
williamr@2: 	IMPORT_C virtual TBool GetEmbeddedFileName(TFileName& aFileName);
williamr@2: 	IMPORT_C virtual void ExtendedInterfaceL(TUid aInterfaceUid, CBase*& aInterface); 
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CConverterLibrary : public CBase
williamr@2: /** A converter DLL's factory for individual CConverterBase-derived objects.
williamr@2: 
williamr@2: The implementor of a converter DLL should implement this class. 
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @deprecated */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Creates and returns an instance of the converter with the specified UID.
williamr@2: 	
williamr@2: 	This class should not allocate any resources that are not returned to the 
williamr@2: 	caller.
williamr@2: 	
williamr@2: 	@param aUid UID of the converter to create
williamr@2: 	@return The specified converter. If the converter does not implement a converter 
williamr@2: 	associated with the UID, then it should return NULL. */
williamr@2: 	virtual CConverterBase* Converter(TUid aUid)=0;	// passes ownership
williamr@2: 	};
williamr@2: 
williamr@2: class CConverterBase2 : public CConverterBase
williamr@2: /** Base Class for Ecom Style Converters
williamr@2: The methods in CConverterBase2 are inherited from CConverterBase
williamr@2: 
williamr@2: There are two flavours of conversion methods:
williamr@2: 
williamr@2: the synchronous interfaces, ConvertL() and ConvertObjectL(), which perform 
williamr@2: the specified conversion and then return
williamr@2: 
williamr@2: the asynchronous interfaces, ConvertAL() and ConvertObjectAL(), which initialise 
williamr@2: the converter object, and allow the client code to call DoConvertL() a number 
williamr@2: of times until the conversion is complete or abandoned.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released  */
williamr@2: 	{
williamr@2: public:
williamr@2: 	static CConverterBase2* CreateConverterL(TUid aImplUid);
williamr@2: 	IMPORT_C virtual ~CConverterBase2(); 
williamr@2: 	IMPORT_C virtual void ConvertL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // These default to calling the async versions in a loop
williamr@2: 	IMPORT_C virtual void ConvertObjectL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL);
williamr@2: 	IMPORT_C virtual void ConvertAL(const TFileName& aSourceFile, const TFileName& aTargetFile, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
williamr@2: 	IMPORT_C virtual void ConvertObjectAL(RReadStream& aReadStream, RWriteStream& aWriteStream, MConverterUiObserver* aObserver=NULL); // these default to leaving with KErrNotSupported
williamr@2: 	IMPORT_C virtual TBool DoConvertL(); // these default to leaving with KErrNotSupported
williamr@2: 	virtual  TUid Uid()=0;
williamr@2: 	IMPORT_C virtual TInt Capabilities(); // defaults to "everything"
williamr@2: 	IMPORT_C virtual void CancelConvert(); // for any cleanup
williamr@2: 	IMPORT_C virtual CConverterBase* EmbeddedObjectL(TDataType& aType);
williamr@2: 	IMPORT_C virtual TBool GetEmbeddedFileName(TFileName& aFileName);
williamr@2: 	IMPORT_C virtual void ExtendedInterfaceL(TUid aInterfaceUid, CBase*& aInterface);
williamr@2: 	IMPORT_C virtual void Reserved_1();
williamr@2: 	IMPORT_C virtual void Reserved_2();
williamr@2: private:
williamr@2: 	TUid iDestructionKey;
williamr@2: 	TInt iSpare;
williamr@2: 	};
williamr@2: #endif