sl@0: /* sl@0: * Copyright (c) 2003-2008 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 the License "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: sl@0: sl@0: sl@0: /** sl@0: @file sl@0: sl@0: @publishedPartner sl@0: @released sl@0: */ sl@0: sl@0: sl@0: #ifndef __IMPORTFILE_H__ sl@0: #define __IMPORTFILE_H__ sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: namespace ContentAccess sl@0: { sl@0: class CAgentFactory; sl@0: class CSupplierOutputFile; sl@0: class CMetaDataArray; sl@0: class CAgentSupplier; sl@0: class CAgentImportFile; sl@0: class CSupplier; sl@0: class CAgentInfo; sl@0: class CAgentFactory; sl@0: sl@0: /** sl@0: Created by the CSupplier to import a file. sl@0: sl@0: The mime type of the file must be one of the CAF supplier mime types. sl@0: Applications should check using CSupplier::IsImportSupported(). sl@0: sl@0: This class creates a CAgentSupplier and uses it to import the file into the sl@0: content access agent who supports the given mime type. sl@0: sl@0: This class is single use only and cannot be used to import multiple files. sl@0: The import process may result in one or more output files. sl@0: sl@0: @publishedPartner sl@0: @released sl@0: */ sl@0: class CImportFile: public CBase sl@0: { sl@0: friend class CSupplier; sl@0: sl@0: public: sl@0: /** Destructor - deleting the CImportFile instance before calling WriteComplete() aborts the import operation sl@0: */ sl@0: virtual ~CImportFile(); sl@0: sl@0: /** Write a block of data from a file to an agent. sl@0: sl@0: @param aData The block of data. sl@0: @return The result of the write operation. sl@0: @return KErrNone if the data was written successfully. sl@0: @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(). sl@0: @return KErrCorrupt if the file does not match the format the agent is expecting. sl@0: @return KErrNotReady if the agent was not expecting WriteData() to be called at this point. sl@0: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the sl@0: other system-wide error codes for any other errors. sl@0: */ sl@0: IMPORT_C TInt WriteData(const TDesC8& aData); sl@0: sl@0: /** Asynchronously write a block of data from a file to an agent. sl@0: Notifies the client when the write operation is complete. sl@0: NB: It is important that the descriptor passed to sl@0: aData remains in scope until the request has completed. sl@0: sl@0: @param aData The block of data. sl@0: @param aStatus Asynchronous request status. On completion this will sl@0: contain one of the following error codes: KErrNone if the data was written successfully. sl@0: KErrCANewFileHandleRequired if the agent requires a new sl@0: file handle before proceeding - the agent must save its sl@0: state and continue processing when the new handle sl@0: is supplied by ContinueWithNewOutputFile(). KErrCorrupt sl@0: if the file does not match the format the agent is expecting. sl@0: KErrNotReady if the agent was not expecting WriteDataComplete() sl@0: to be called at this point. Otherwise one of the other CAF error codes sl@0: defined in \c caferr.h or one of the other standard system-wide sl@0: error codes for any other errors. sl@0: */ sl@0: IMPORT_C void WriteData(const TDesC8& aData, TRequestStatus& aStatus); sl@0: sl@0: /** Signals to the agent that the entire file has now been transferred to the agent. sl@0: sl@0: @return The result of the write operation. sl@0: @return KErrNone if the data was written successfully. sl@0: @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(). sl@0: @return KErrCorrupt if the file does not match the format the agent is expecting. sl@0: @return KErrNotReady if the agent was not expecting WriteDataComplete() to be called at this point. sl@0: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the sl@0: other system-wide error codes for any other errors. sl@0: */ sl@0: IMPORT_C TInt WriteDataComplete(); sl@0: sl@0: sl@0: /** Signals to the agent that the entire file has now been transferred to the agent sl@0: sl@0: Notifies the client when any final processing operation is complete. sl@0: sl@0: @param aStatus Asynchronous request status. On completion this will sl@0: contain one of the following error codes: KErrNone if the data was written successfully. sl@0: KErrCANewFileHandleRequired if the agent requires a new sl@0: file handle before proceeding - the agent must save its sl@0: state and continue processing when the new handle sl@0: is supplied by ContinueWithNewOutputFile(). KErrCorrupt sl@0: if the file does not match the format the agent is expecting. sl@0: KErrNotReady if the agent was not expecting WriteDataComplete() sl@0: to be called at this point. Otherwise one of the other CAF error codes sl@0: defined in \c caferr.h or one of the other standard system-wide sl@0: error codes for any other errors. sl@0: */ sl@0: IMPORT_C void WriteDataComplete(TRequestStatus& aStatus); sl@0: sl@0: /** Gets the number of output files produced so far. sl@0: @return The number of output files. sl@0: */ sl@0: IMPORT_C TInt OutputFileCountL() const; sl@0: sl@0: /** Return information about an output file generated by the import operation. sl@0: sl@0: It is possible that the output file does not have the same name sl@0: as the one suggested at the beginning of the import. An agent may sl@0: need to use a particular file extension or a particular name. sl@0: sl@0: The agent may decide not to store the output file in the output directory sl@0: suggested at the start of the import. eg. it may store the file in its private sl@0: server directory. sl@0: sl@0: The output files may only appear in this array after the WriteDataComplete() sl@0: function has been called. sl@0: sl@0: @param aIndex The zero-based index of the file (must be less than the value returned by OutputFileCountL(). sl@0: @return The CSupplierOutputFile for this object. sl@0: */ sl@0: IMPORT_C CSupplierOutputFile& OutputFileL(TInt aIndex) const; sl@0: sl@0: /** Retrieve the import status sl@0: sl@0: Used to indicate non fatal problems encountered during the import operation. sl@0: Provides feedback to the client in case any problems are encountered. sl@0: sl@0: The client can then decide whether or not to continue the import. sl@0: sl@0: @return The state of the import operation. sl@0: */ sl@0: IMPORT_C TImportStatus GetImportStatus() const; sl@0: sl@0: /** Get the agents suggestion for the file extension of the output file required by the agent sl@0: sl@0: This function should only be called when the agent has returned KErrCANewFileHandleRequired from sl@0: WriteData() or WriteDataComplete(). sl@0: sl@0: The extension must include the dot '.' character. sl@0: sl@0: @param aFileExtension On completion this will contain the appropriate file extension. sl@0: @return The result of the request for a file extension. sl@0: @return KErrNone if the agent populated aFileExtension with the correct file extension. sl@0: @return KErrNotReady if the agent is not waiting for another file handle to be provided. sl@0: @return KErrUnknown if the agent does not know what extension should be used. sl@0: */ sl@0: IMPORT_C TInt GetSuggestedOutputFileExtension(TDes& aFileExtension); sl@0: sl@0: /** Get the agents suggestion for the file name (with extension) of the output file required by the agent sl@0: sl@0: This function should only be called when the agent has returned KErrCANewFileHandleRequired from sl@0: WriteData() or WriteDataComplete(). sl@0: sl@0: The file name is of the form filename.extension. sl@0: sl@0: @param aFileName On completion this will contain the appropriate file name. sl@0: @return KErrNone if the agent populated aFileName with the correct file name. sl@0: @return KErrNotReady if the agent is not waiting for another file handle to be provided. sl@0: @return KErrUnknown if the agent does not know what file name should be used. sl@0: */ sl@0: IMPORT_C TInt GetSuggestedOutputFileName(TDes& aFileName); sl@0: sl@0: /** Continue the last write operation with a new file handle as requested by the agent sl@0: sl@0: @param aFile A new file handle opened with write permission. sl@0: @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. sl@0: @return The result of the continuing write operation. sl@0: @return KErrNone if the WriteData() or WriteDataComplete() operation is now complete. sl@0: @return KErrCANewFileHandleRequired if the agent requires a new sl@0: file handle before proceeding - the agent must save its sl@0: state and continue processing when the new handle sl@0: is supplied by ContinueWithNewOutputFile(). sl@0: @return Otherwise one of the other CAF error codes defined in \c caferr.h or one of the sl@0: other system-wide error codes for any other errors. sl@0: */ sl@0: IMPORT_C TInt ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName); sl@0: sl@0: /** Continue the last write operation with a new file handle and return the result asynchronously. sl@0: NB: It is important that the handle passed to aFile and the sl@0: descriptor passed to aFileName remain in scope until the request has completed. sl@0: sl@0: @param aFile A new file handle opened with write permission. sl@0: @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 sl@0: @param aStatus Asynchronous request status. On completion this will sl@0: contain one of the following error codes: KErrNone if the sl@0: WriteData() or WriteDataComplete() operation is now complete. sl@0: KErrCANewFileHandleRequired if the agent requires a new sl@0: file handle before proceeding - the agent must save its sl@0: state and continue processing when the new handle sl@0: is supplied by ContinueWithNewOutputFile(). Otherwise one of the sl@0: other CAF error codes defined in \c caferr.h or one of the sl@0: other system-wide error codes for any other errors. sl@0: */ sl@0: IMPORT_C void ContinueWithNewOutputFile(RFile& aFile, const TDesC& aFileName, TRequestStatus& aStatus); sl@0: sl@0: /** Cancel an outstanding asynchronous request to WriteData() or WriteDataComplete(). sl@0: */ sl@0: IMPORT_C void Cancel(); sl@0: sl@0: /** Retrieve the content MIME type based on available data sl@0: sl@0: This function should only be called when the agent has returned KErrCANewFileHandleRequired from sl@0: WriteData() . sl@0: Example of use: sl@0: @code sl@0: while(!endofsource) sl@0: { sl@0: source.read(data); sl@0: err = import->WriteData(data); sl@0: sl@0: // When application supplies file handles it must always check to see if sl@0: // the agent needs a new file handle sl@0: while(err == KErrCANewFileHandleRequired) sl@0: { sl@0: //We need to find out the content MIME type based on available data sl@0: TBuf contentMime; sl@0: if(import->ContentMimeTypeL(contentMime) == KErrNone) sl@0: { sl@0: //content MIME type is discovered. Now client code could do something sl@0: //to determine the output location and supply the appropriate file handle sl@0: sl@0: sl@0: } sl@0: else sl@0: { sl@0: //content MIME type can't be determined yet. Client should decide the location for sl@0: //output file now,e.g. a default location sl@0: sl@0: } sl@0: sl@0: err = import->ContinueWithNewOutputFile(outputFileHandle, outputFileName); sl@0: // It is possible that the agent needs yet another file handle sl@0: outputFileHandle.Close(); // agent makes a copy so we don't need to keep our file handle sl@0: } sl@0: } sl@0: sl@0: @endcode sl@0: sl@0: @param aContentMime On return this will contain the appropriate content MIME type. sl@0: @return The result of the request for a content MIME type. sl@0: @return ETrue if the agent populated aContentMime with the correct content MIME type. sl@0: @return EFalse if the agent cannot return the content MIME type (for example, there sl@0: is not enough data, or the content is multi-part) sl@0: */ sl@0: IMPORT_C TBool ContentMimeTypeL(TDes8& aContentMime); sl@0: sl@0: private: sl@0: CImportFile(); sl@0: sl@0: static CImportFile* NewL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData, const TDesC& aOutputDirectory, const TDesC& aSuggestedFileName); sl@0: void ConstructL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData, const TDesC& aOutputDirectory, const TDesC& aSuggestedFileName); sl@0: sl@0: static CImportFile* NewL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData); sl@0: void ConstructL(TUid aAgentUid, const TDesC8& aMimeType, const CMetaDataArray& aImportMetaData); sl@0: sl@0: private: sl@0: // Agent within CAF used to import the file sl@0: CAgentImportFile* iAgentImportFile; sl@0: sl@0: // Agent factory, de-facto ECOM session handle sl@0: CAgentFactory* iAgentFactory; sl@0: }; sl@0: } sl@0: #endif