1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 

    20 /** 

    21 @file

    22 

    23 @publishedPartner

    24 @released

    25 */

    26 

    27 

    28 #ifndef __IMPORTFILE_H__

    29 #define __IMPORTFILE_H__

    30 

    31 #include <e32base.h>

    32 #include <f32file.h>

    33 #include <caf/caftypes.h>

    34 

    35 namespace ContentAccess

    36 	{

    37 	class CAgentFactory;

    38 	class CSupplierOutputFile;

    39 	class CMetaDataArray;

    40 	class CAgentSupplier;

    41 	class CAgentImportFile;

    42 	class CSupplier;

    43 	class CAgentInfo;

    44 	class CAgentFactory;

    45 

    46 	/**

    47 	Created by the CSupplier to import a file. 

    48 	

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

    50 	Applications should check using CSupplier::IsImportSupported().

    51 	

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

    53 	content access agent who supports the given mime type.

    54 	

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

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

    57 	

    58 	@publishedPartner

    59 	@released	

    60 	*/

    61 	class CImportFile: public CBase

    62 		{

    63 		friend class CSupplier;

    64 

    65 	public:

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

    67 		*/

    68 		virtual ~CImportFile();

    69 

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

    71 		

    72 		@param aData The block of data.

    73 		@return	The result of the write operation.

    74 		@return KErrNone if the data was written successfully.

    75 		@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().

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

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

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

    79 				other system-wide error codes for any other errors.

    80 		*/

    81 		IMPORT_C TInt WriteData(const TDesC8& aData);

    82 

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

    84 		Notifies the client when the write operation is complete.

    85 		NB: It is important that the descriptor passed to 

    86 		aData remains in scope until the request has completed.	

    87 		

    88 		@param aData 	The block of data.	

    89 		@param aStatus 	Asynchronous request status. On completion this will 

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

    91 						KErrCANewFileHandleRequired if the agent requires a new 

    92 						file handle before proceeding - the agent must save its 

    93 						state and continue processing when the new handle 

    94 						is supplied by ContinueWithNewOutputFile(). KErrCorrupt 

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

    96 						KErrNotReady if the agent was not expecting WriteDataComplete() 

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

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

    99 						error codes for any other errors.

   100 		*/

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

   102 

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

   104 		

   105 		@return The result of the write operation. 

   106 		@return KErrNone if the data was written successfully.

   107 		@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().

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

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

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

   111 				other system-wide error codes for any other errors.		

   112 		*/

   113 		IMPORT_C TInt WriteDataComplete();

   114 

   115 

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

   117 		

   118 		Notifies the client when any final processing operation is complete.

   119 		

   120 		@param aStatus 	Asynchronous request status. On completion this will 

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

   122 						KErrCANewFileHandleRequired if the agent requires a new 

   123 						file handle before proceeding - the agent must save its 

   124 						state and continue processing when the new handle 

   125 						is supplied by ContinueWithNewOutputFile(). KErrCorrupt 

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

   127 						KErrNotReady if the agent was not expecting WriteDataComplete() 

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

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

   130 						error codes for any other errors.

   131 		*/

   132 		IMPORT_C void WriteDataComplete(TRequestStatus& aStatus);

   133 

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

   135 		@return The number of output files.

   136 		*/

   137 		IMPORT_C TInt OutputFileCountL() const;

   138 

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

   140 		

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

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

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

   144 

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

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

   147 		server directory.

   148 

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

   150 		function has been called. 

   151 

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

   153 		@return The CSupplierOutputFile for this object.

   154 		*/

   155 		IMPORT_C CSupplierOutputFile& OutputFileL(TInt aIndex) const;

   156 

   157 		/** Retrieve the import status

   158 

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

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

   161 

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

   163 		 

   164 		@return	The state of the import operation.

   165 		*/

   166 		IMPORT_C TImportStatus GetImportStatus() const;

   167 

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

   169 

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

   171 		WriteData() or WriteDataComplete().

   172 

   173 		The extension must include the dot '.' character.

   174 

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

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

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

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

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

   180 		*/

   181 		IMPORT_C TInt GetSuggestedOutputFileExtension(TDes& aFileExtension);

   182 

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

   184 

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

   186 		WriteData() or WriteDataComplete().

   187 

   188 		The file name is of the form filename.extension.

   189 

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

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

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

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

   194 		*/

   195 		IMPORT_C TInt GetSuggestedOutputFileName(TDes& aFileName);

   196 

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

   198 		

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

   200 		@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.

   201 		@return The result of the continuing write operation.

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

   203 		@return KErrCANewFileHandleRequired if the agent requires a new 

   204 						file handle before proceeding - the agent must save its 

   205 						state and continue processing when the new handle 

   206 						is supplied by ContinueWithNewOutputFile().

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

   208 				other system-wide error codes for any other errors.		

   209 		*/

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

   211 

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

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

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

   215 

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

   217 		@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		

   218 		@param aStatus 	 Asynchronous request status. On completion this will 

   219 						 contain one of the following error codes: KErrNone if the 

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

   221 					 	 KErrCANewFileHandleRequired if the agent requires a new 

   222 						 file handle before proceeding - the agent must save its 

   223 						 state and continue processing when the new handle 

   224 						 is supplied by ContinueWithNewOutputFile(). Otherwise one of the 

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

   226 						 other system-wide error codes for any other errors.		

   227 		*/

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

   229 

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

   231 		*/

   232 		IMPORT_C void Cancel();

   233 		

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

   235 

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

   237 		WriteData() .

   238 		Example of use:

   239 		@code

   240 		while(!endofsource) 

   241 			{

   242 			source.read(data); 

   243 			err = import->WriteData(data); 

   244 

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

   246 			// the agent needs a new file handle 

   247 			while(err == KErrCANewFileHandleRequired) 

   248 				{               

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

   250 				TBuf<KMaxDataTypeLength> contentMime;

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

   252 					{

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

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

   255 					

   256 					

   257 					}

   258 				else

   259 					{

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

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

   262 

   263 					}

   264 				        

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

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

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

   268 				}

   269 			}

   270 

   271 		@endcode

   272 

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

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

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

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

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

   278 		*/

   279 		IMPORT_C TBool ContentMimeTypeL(TDes8& aContentMime); 

   280 		

   281 	private:

   282 		CImportFile();

   283 

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

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

   286 		

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

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

   289 

   290 	private:

   291 		// Agent within CAF used to import the file

   292 		CAgentImportFile* iAgentImportFile;

   293 

   294 		// Agent factory, de-facto ECOM session handle

   295 		CAgentFactory* iAgentFactory;

   296 		};

   297 	}

   298 #endif