ContentAccess::CImportFile Class Reference

class ContentAccess::CImportFile : public CBase

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.

Inherits from

  • ContentAccess::CImportFile

Constructor & Destructor Documentation

CImportFile()

CImportFile()[private]

~CImportFile()

~CImportFile()[virtual]

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

Member Functions Documentation

Cancel()

IMPORT_C voidCancel()

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

ConstructL(TUid, const TDesC8 &, const CMetaDataArray &, const TDesC &, const TDesC &)

voidConstructL(TUidaAgentUid,
const TDesC8 &aMimeType,
const CMetaDataArray &aImportMetaData,
const TDesC &aOutputDirectory,
const TDesC &aSuggestedFileName
)[private]

Parameters

TUid aAgentUid
const TDesC8 & aMimeType
const CMetaDataArray & aImportMetaData
const TDesC & aOutputDirectory
const TDesC & aSuggestedFileName

ConstructL(TUid, const TDesC8 &, const CMetaDataArray &)

voidConstructL(TUidaAgentUid,
const TDesC8 &aMimeType,
const CMetaDataArray &aImportMetaData
)[private]

Parameters

TUid aAgentUid
const TDesC8 & aMimeType
const CMetaDataArray & aImportMetaData

ContentMimeTypeL(TDes8 &)

IMPORT_C TBoolContentMimeTypeL(TDes8 &aContentMime)

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:
		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 
				}
			}

Parameters

TDes8 & aContentMimeOn return this will contain the appropriate content MIME type.

ContinueWithNewOutputFile(RFile &, const TDesC &)

IMPORT_C TIntContinueWithNewOutputFile(RFile &aFile,
const TDesC &aFileName
)

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

Parameters

RFile & aFileA new file handle opened with write permission.
const TDesC & aFileNameThe 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.

ContinueWithNewOutputFile(RFile &, const TDesC &, TRequestStatus &)

IMPORT_C voidContinueWithNewOutputFile(RFile &aFile,
const TDesC &aFileName,
TRequestStatus &aStatus
)

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.

Parameters

RFile & aFileA new file handle opened with write permission.
const TDesC & aFileNameThe 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
TRequestStatus & aStatusAsynchronous 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 caferr.h or one of the other system-wide error codes for any other errors.

GetImportStatus()

IMPORT_C TImportStatusGetImportStatus()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.

GetSuggestedOutputFileExtension(TDes &)

IMPORT_C TIntGetSuggestedOutputFileExtension(TDes &aFileExtension)

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.

Parameters

TDes & aFileExtensionOn completion this will contain the appropriate file extension.

GetSuggestedOutputFileName(TDes &)

IMPORT_C TIntGetSuggestedOutputFileName(TDes &aFileName)

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.

Parameters

TDes & aFileNameOn completion this will contain the appropriate file name.

NewL(TUid, const TDesC8 &, const CMetaDataArray &, const TDesC &, const TDesC &)

CImportFile *NewL(TUidaAgentUid,
const TDesC8 &aMimeType,
const CMetaDataArray &aImportMetaData,
const TDesC &aOutputDirectory,
const TDesC &aSuggestedFileName
)[private, static]

Parameters

TUid aAgentUid
const TDesC8 & aMimeType
const CMetaDataArray & aImportMetaData
const TDesC & aOutputDirectory
const TDesC & aSuggestedFileName

NewL(TUid, const TDesC8 &, const CMetaDataArray &)

CImportFile *NewL(TUidaAgentUid,
const TDesC8 &aMimeType,
const CMetaDataArray &aImportMetaData
)[private, static]

Parameters

TUid aAgentUid
const TDesC8 & aMimeType
const CMetaDataArray & aImportMetaData

OutputFileCountL()

IMPORT_C TIntOutputFileCountL()const

Gets the number of output files produced so far.

OutputFileL(TInt)

IMPORT_C CSupplierOutputFile &OutputFileL(TIntaIndex)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.

Parameters

TInt aIndexThe zero-based index of the file (must be less than the value returned by OutputFileCountL().

WriteData(const TDesC8 &)

IMPORT_C TIntWriteData(const TDesC8 &aData)

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

Parameters

const TDesC8 & aDataThe block of data.

WriteData(const TDesC8 &, TRequestStatus &)

IMPORT_C voidWriteData(const TDesC8 &aData,
TRequestStatus &aStatus
)

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.

Parameters

const TDesC8 & aDataThe block of data.
TRequestStatus & aStatusAsynchronous 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 caferr.h or one of the other standard system-wide error codes for any other errors.

WriteDataComplete()

IMPORT_C TIntWriteDataComplete()

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

WriteDataComplete(TRequestStatus &)

IMPORT_C voidWriteDataComplete(TRequestStatus &aStatus)

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.

Parameters

TRequestStatus & aStatusAsynchronous 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 caferr.h or one of the other standard system-wide error codes for any other errors.

Member Data Documentation

CAgentFactory * iAgentFactory

CAgentFactory *iAgentFactory[private]

CAgentImportFile * iAgentImportFile

CAgentImportFile *iAgentImportFile[private]