/*

* Copyright (c) 2003-2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/** 

@file

@publishedPartner

@released

*/

#ifndef __IMPORTFILE_H__

#define __IMPORTFILE_H__

#include <e32base.h>

#include <f32file.h>

#include <caf/caftypes.h>

namespace ContentAccess

	{

	class CAgentFactory;

	class CSupplierOutputFile;

	class CMetaDataArray;

	class CAgentSupplier;

	class CAgentImportFile;

	class CSupplier;

	class CAgentInfo;

	class CAgentFactory;

	/**

	Created by the CSupplier to import a file. 

	The mime type of the file must be one of the CAF supplier mime types. 

	Applications should check using CSupplier::IsImportSupported().

	This class creates a CAgentSupplier and uses it to import the file into the 

	content access agent who supports the given mime type.

	This class is single use only and cannot be used to import multiple files. 

	The import process may result in one or more output files.

	@publishedPartner

	@released	

	*/

	class CImportFile: public CBase

		{

		friend class CSupplier;

	public:

		/** Destructor - deleting the CImportFile instance before calling WriteComplete() aborts the import operation 

		*/

		virtual ~CImportFile();

		/** Write a block of data from a file to an agent.

		@param aData The block of data.

		@return	The result of the write operation.

		@return KErrNone if the data was written successfully.

		@return	KErrCANewFileHandleRequired if the agent requires the client to provide a new file handle before proceeding. The agent must save its state and continue processing when the new handle is supplied by ContinueWithNewOutputFile().

		@return KErrCorrupt if the file does not match the format the agent is expecting.

		@return KErrNotReady if the agent was not expecting WriteData() to be called at this point.

		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

				other system-wide error codes for any other errors.

		*/

		IMPORT_C TInt WriteData(const TDesC8& aData);

		/** Asynchronously write a block of data from a file to an agent.		 

		Notifies the client when the write operation is complete.

		NB: It is important that the descriptor passed to 

		aData remains in scope until the request has completed.	

		@param aData 	The block of data.	

		@param aStatus 	Asynchronous request status. On completion this will 

						contain one of the following error codes: KErrNone if the data was written successfully. 

						KErrCANewFileHandleRequired if the agent requires a new 

						file handle before proceeding - the agent must save its 

						state and continue processing when the new handle 

						is supplied by ContinueWithNewOutputFile(). KErrCorrupt 

						if the file does not match the format the agent is expecting.

						KErrNotReady if the agent was not expecting WriteDataComplete() 

						to be called at this point. Otherwise one of the other CAF error codes 

						defined in \c caferr.h  or one of the other standard system-wide 

						error codes for any other errors.

		*/

		IMPORT_C void WriteData(const TDesC8& aData, TRequestStatus& aStatus);

		/** Signals to the agent that the entire file has now been transferred to the agent.

		@return The result of the write operation. 

		@return KErrNone if the data was written successfully.

		@return	KErrCANewFileHandleRequired if the agent requires the client to provide a new file handle before proceeding. The agent must save its state and continue processing when the new handle is supplied by ContinueWithNewOutputFile().

		@return KErrCorrupt if the file does not match the format the agent is expecting.

		@return KErrNotReady if the agent was not expecting WriteDataComplete() to be called at this point.

		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

				other system-wide error codes for any other errors.		

		*/

		IMPORT_C TInt WriteDataComplete();

		/** Signals to the agent that the entire file has now been transferred to the agent

		Notifies the client when any final processing operation is complete.

		@param aStatus 	Asynchronous request status. On completion this will 

						contain one of the following error codes: KErrNone if the data was written successfully. 

						KErrCANewFileHandleRequired if the agent requires a new 

						file handle before proceeding - the agent must save its 

						state and continue processing when the new handle 

						is supplied by ContinueWithNewOutputFile(). KErrCorrupt 

						if the file does not match the format the agent is expecting.

						KErrNotReady if the agent was not expecting WriteDataComplete() 

						to be called at this point. Otherwise one of the other CAF error codes 

						defined in \c caferr.h  or one of the other standard system-wide 

						error codes for any other errors.

		*/

		IMPORT_C void WriteDataComplete(TRequestStatus& aStatus);

		/** Gets the number of output files produced so far. 

		@return The number of output files.

		*/

		IMPORT_C TInt OutputFileCountL() const;

		/** Return information about an output file generated by the import operation. 

		 It is possible that the output file does not have the same name 

		 as the one suggested at the beginning of the import. An agent may

		 need to use a particular file extension or a particular name.

		The agent may decide not to store the output file in the output directory 

		suggested at the start of the import. eg. it may store the file in its private 

		server directory.

		The output files may only appear in this array after the WriteDataComplete() 

		function has been called. 

		@param aIndex The zero-based index of the file (must be less than the value returned by OutputFileCountL().

		@return The CSupplierOutputFile for this object.

		*/

		IMPORT_C CSupplierOutputFile& OutputFileL(TInt aIndex) const;

		/** Retrieve the import status

		Used to indicate non fatal problems encountered during the import operation.

		Provides feedback to the client in case any problems are encountered.

		The client can then decide whether or not to continue the import.

		@return	The state of the import operation.

		*/

		IMPORT_C TImportStatus GetImportStatus() const;

		/** Get the agents suggestion for the file extension of the output file required by the agent

		This function should only be called when the agent has returned KErrCANewFileHandleRequired from

		WriteData() or WriteDataComplete().

		The extension must include the dot '.' character.

		@param aFileExtension On completion this will contain the appropriate file extension.

		@return The result of the request for a file extension.

		@return KErrNone if the agent populated aFileExtension with the correct file extension.

		@return KErrNotReady if the agent is not waiting for another file handle to be provided.

		@return KErrUnknown if the agent does not know what extension should be used.

		*/

		IMPORT_C TInt GetSuggestedOutputFileExtension(TDes& aFileExtension);

		/** Get the agents suggestion for the file name (with extension) of the output file required by the agent

		This function should only be called when the agent has returned KErrCANewFileHandleRequired from

		WriteData() or WriteDataComplete().

		The file name is of the form filename.extension.

		@param aFileName On completion this will contain the appropriate file name.

		@return KErrNone if the agent populated aFileName with the correct file name.

		@return KErrNotReady if the agent is not waiting for another file handle to be provided.

		@return KErrUnknown if the agent does not know what file name should be used.

		*/

		IMPORT_C TInt GetSuggestedOutputFileName(TDes& aFileName);

		/** Continue the last write operation with a new file handle as requested by the agent

		@param aFile A new file handle opened with write permission.

		@param aFileName The name of the file handle that has  been supplied. This is used by the agent when creating CSupplierOutputFile objects. It should include the full path and filename in order to be consistent with files generated by the agent.

		@return The result of the continuing write operation.

		@return KErrNone if the WriteData() or WriteDataComplete() operation is now complete.

		@return KErrCANewFileHandleRequired if the agent requires a new 

						file handle before proceeding - the agent must save its 

						state and continue processing when the new handle 

						is supplied by ContinueWithNewOutputFile().

		@return Otherwise one of the other CAF error codes defined in \c caferr.h  or one of the 

				other system-wide error codes for any other errors.		

		*/

		IMPORT_C TInt ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName);

		/** Continue the last write operation with a new file handle and return the result asynchronously.

		NB: It is important that the handle passed to aFile and the

		descriptor passed to aFileName remain in scope until the request has completed.	

		@param aFile  	 A new file handle opened with write permission.

		@param aFileName The name of the file handle that has  been supplied. This is used by the agent when creating CSupplierOutputFile objects. It should include the full path and filename in order to be consistent with files generated by the agent		

		@param aStatus 	 Asynchronous request status. On completion this will 

						 contain one of the following error codes: KErrNone if the 

					 	 WriteData() or WriteDataComplete() operation is now complete.

					 	 KErrCANewFileHandleRequired if the agent requires a new 

						 file handle before proceeding - the agent must save its 

						 state and continue processing when the new handle 

						 is supplied by ContinueWithNewOutputFile(). Otherwise one of the 

						 other CAF error codes defined in \c caferr.h  or one of the 

						 other system-wide error codes for any other errors.		

		*/

		IMPORT_C void ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName, TRequestStatus& aStatus);

		/** Cancel an outstanding asynchronous request to WriteData() or WriteDataComplete().

		*/

		IMPORT_C void Cancel();

		/** Retrieve the content MIME type based on available data

		This function should only be called when the agent has returned KErrCANewFileHandleRequired from

		WriteData() .

		Example of use:

		@code

		while(!endofsource) 

			{

			source.read(data); 

			err = import->WriteData(data); 

			// When application supplies file handles it must always check to see if 

			// the agent needs a new file handle 

			while(err == KErrCANewFileHandleRequired) 

				{               

				//We need to find out the content MIME type based on available data

				TBuf<KMaxDataTypeLength> contentMime;

				if(import->ContentMimeTypeL(contentMime) == KErrNone)

					{

					//content MIME type is discovered. Now client code could do something

					//to determine the output location and supply the appropriate file handle

					}

				else

					{

					//content MIME type can't be determined yet. Client should decide the location for

					//output file now,e.g. a default location

					}

				err = import->ContinueWithNewOutputFile(outputFileHandle, outputFileName); 

				// It is possible that the agent needs yet another file handle 

				outputFileHandle.Close(); // agent makes a copy so we don't need to keep our file handle 

				}

			}

		@endcode

		@param aContentMime On return this will contain the appropriate content MIME type.

		@return The result of the request for a content MIME type.

		@return ETrue if the agent populated aContentMime with the correct content MIME type.

		@return EFalse if the agent cannot return the content MIME type (for example, there 

					is not enough data, or the content is multi-part)

		*/

		IMPORT_C TBool ContentMimeTypeL(TDes8& aContentMime); 

	private:

		CImportFile();

		static CImportFile* NewL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData, const TDesC& aOutputDirectory, const TDesC& aSuggestedFileName);

		void ConstructL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData, const TDesC& aOutputDirectory, const TDesC& aSuggestedFileName);

		static CImportFile* NewL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData);

		void ConstructL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData);

	private:

		// Agent within CAF used to import the file

		CAgentImportFile* iAgentImportFile;

		// Agent factory, de-facto ECOM session handle

		CAgentFactory* iAgentFactory;

		};

	}

#endif