CDocumentHandler Class Reference

API published in: S60 1st Ed

Link against: commonui.lib

Capability Information

Required Capabilities

None

#include <documenthandler.h>

Detailed Description

Utility class for opening and saving any supported content.

This class declares an interface for the DocumentHandler, a common component in Series60.

The CDocumentHandler class will not itself implement any content handling routines. It's responsible for finding out which application can handle given data type and constructing a correct handler implementation for that application. If the given data type is supported by the system but no specific handler is found, the CDocDefaltHandler is then constructed. The default handler is an implementation of the CDoCDocHandlerBase class with standard "Epoc-style" content handling.

The handler application can be lauched standalone or embedded. The Embedded launching is preferred way in Series60. Standalone launching means that the application will run in it's own process. Embedded launching means that the UI of an application, which is responsible for handling given data type, is embedded into the parent application. There will be only parent applications icon shown in the fast swap window when an application is embedded.

Link your application against CommonUI.lib.

An example:

 
 include <DocumentHandler.h>

 // Define DocHandler
 CDocumentHandler* iDocHandler;

 // Construct DocHandler
 void ConstructL()
    {
    iDocHandler = CDocumentHandler::NewL();

    // I want to be notified when exit happends. Because I
    // pass "this" pointer, I have to derive from
    // MAknServerAppExitObserver class.
    iDocHandler->SetExitObserver(this)     
    }

 // delete DocHandler
 void ~Myapp()
    {
    delete iDocHandler;
    }

 // and use like this

 void OpenAttachmentL( RFile& aFile,           // A file to be open
                       TDataType& aDataType )  // DataType can be empty
   {
   TInt error = KErrNone;
   TFileName path;

   
   // Leaves on system wide errors like disk full, out of memory etc.
   error = iDocHandler->OpenFileEmbeddedL( aFile, aDataType );
   // The status code can be either KErrNone or KUserCancel


Public Member Functions
virtual IMPORT_C	~CDocumentHandler ()
	Destructor.
IMPORT_C void	OpenTempFileL (const TDesC &aFileName, RFile &aSharableFile)
	Utility method for opening filehandle from existing file for OpenFileL calls.
IMPORT_C void	SaveTempFileL (const TDesC8 &aContent, TDataType &aDataType, const TDesC &aFileName, RFile &aSharableFile)
	Utility method for save aContent with aDataType temporarily for OpenFileL calls.
IMPORT_C CAiwGenericParamList &	InParamListL ()
	Returns an empty instance of CAiwGenericParamList class.
IMPORT_C const CAiwGenericParamList *	OutParamList ()
	Returns a list of possible output parameters handler application may have set after executing the service.
IMPORT_C TInt	OpenFileL (RFile &aSharableFile, TDataType &aDataType)
	Launches an application in standalone capable of handling data in aSharableFile (using aDatatype if available).
IMPORT_C TInt	OpenFileEmbeddedL (RFile &aSharableFile, TDataType &aDataType, const CAiwGenericParamList &aParamList)
	Launches an application in embedded (if possible) capable of handling data in aSharableFile (using aDatatype if available).
IMPORT_C TInt	OpenFileEmbeddedL (RFile &aSharableFile, TDataType &aDataType)
	Launches an application in embedded (if possible) capable of handling data in aSharableFile (using aDatatype if available).
IMPORT_C TInt	OpenFileL (const TDesC &aFileName, TDataType &aDataType)
	Launches an application standalone capable of handling data in aFilename, with aDataType.
IMPORT_C TInt	OpenFileEmbeddedL (const TDesC &aFileName, TDataType &aDataType)
	Launches an application embedded capable of handling data in aFilename with aDataType.
IMPORT_C TInt	SaveL (const TDesC8 &aContent, TDataType &aDataType, const TUint aAttr)
	Save aContent with aDataType using aAttr to a correct directory.
IMPORT_C TInt	SaveL (const TDesC8 &aContent, TDataType &aDataType, const TDesC &aName, const TUint aAttr)
	Save aBuffer with aDataType using aAttr to a correct storage with a supplied name.
IMPORT_C TInt	CopyL (const TDesC &aFileNameOld, const TDesC &aNameNew, TDataType &aDataType, const TUint aAttr)
	Copy a file named aFileNameOld to the correct storage using name aNameNew and aFileAttr.
IMPORT_C TInt	CopyL (const RFile &aFileOld, const TDesC &aNameNew, TDataType &aDataType, const TUint aAttr)
	Copy a file with handle aFileOld to the correct storage using name aNameNew and aFileAttr.
IMPORT_C TInt	MoveL (const TDesC &aFileNameOld, const TDesC &aNameNew, TDataType &aDataType, const TUint aAttr)
	Move a file named aFileNameOld to the correct storage using name aNameNew and aFileAttr.
IMPORT_C TInt	SilentMoveL (const TDesC &aFileNameOld, const TDesC &aNameNew, const TDesC &aRootPath, TDataType &aDataType, const TUint aAttr)
	Move a file named aFileNameOld to the correct storage using name aNameNew and aFileAttr.
IMPORT_C TBool	CanHandleL (const TDataType &aDataType)
	Is the aDataType supported by the system.
IMPORT_C TBool	CanOpenL (const TDataType &aDataType)
	Is opening of aDataType supported by the system.
IMPORT_C TBool	CanSaveL (const TDataType &aDataType)
	Is saving aDataType supported by the system.
IMPORT_C TInt	GetPath (TDes &aPath)
	Get the whole path including filename where the content was saved.
IMPORT_C TInt	HandlerAppUid (TUid &aUid)
	Get the uid of handler application.
IMPORT_C void	SetExitObserver (MAknServerAppExitObserver *aObserver)
	Set an observer for embedded application exit events.
IMPORT_C void	CheckFileNameExtension (TDes &aFileName, const TDataType &aDatatype)
	Utility method for appending a correct file name extension for some content.
RApaLsSession *	ApaLs ()
	Get the RApaLsSession.
MAknServerAppExitObserver *	ServerAppExitObserver () const
	Get the exit observer.
TDocOperation	DocOperation () const
	Get the operation code of the api entry function.
void	CloseSharableFS ()
	Close sharable FileSession.
void	SetTempFile (const TDesC &aTempFile)
	Set temporary file, which will be deleted in destructor.
IMPORT_C TBool	CanHandleProgressivelyL (const TDataType &aDataType, TUid &aUid)
	Utility method to find out if there are any applications that support progressive downloading for a given data type.
IMPORT_C void	GetProgressiveDownloadAppUidsL (RArray< TInt32 > &aUidList)
	Utility method to provide a list of applications that support progressive downloading.
Static Public Member Functions
static IMPORT_C CDocumentHandler *	NewL (CEikProcess *aProcess)
	Two-phased constructor.
static IMPORT_C CDocumentHandler *	NewLC (CEikProcess *aProcess)
	Two-phased constructor.
static IMPORT_C CDocumentHandler *	NewL ()
	Two-phased constructor.
static IMPORT_C CDocumentHandler *	NewLC ()
	Two-phased constructor.

Constructor & Destructor Documentation

virtual IMPORT_C CDocumentHandler::~CDocumentHandler ( ) [virtual]

Destructor.

Member Function Documentation

RApaLsSession* CDocumentHandler::ApaLs

(

)

Get the RApaLsSession.

Returns:: Pointer to RApaLsSession

IMPORT_C TBool CDocumentHandler::CanHandleL

(

const TDataType &

aDataType

)

Is the aDataType supported by the system.

Parameters:

aDataType

Data type for content.

Returns:: True if there is an application capable of handling aDataType. False if no application can handle this mime type.

IMPORT_C TBool CDocumentHandler::CanHandleProgressivelyL	(	const TDataType &	aDataType,
		TUid &	aUid
	)

Utility method to find out if there are any applications that support progressive downloading for a given data type.

The decision is based on configuration made in central repository.

Parameters:

	aDataType	The content type of the file.
	aUid	An Uid of the applications for the given data type.

Returns:: ETrue if progressive download was supported for the given data type. Otherwise EFalse.

IMPORT_C TBool CDocumentHandler::CanOpenL

(

const TDataType &

aDataType

)

Is opening of aDataType supported by the system.

Parameters:

aDataType

Data type for content.

Returns:: True if there is an application capable of handling aDataType. False if no application can handle this mime type.

IMPORT_C TBool CDocumentHandler::CanSaveL

(

const TDataType &

aDataType

)

Is saving aDataType supported by the system.

Parameters:

aDataType

Data type for content.

Returns:: True if there is an application capable of handling aDataType. False if no application can handle this mime type.

IMPORT_C void CDocumentHandler::CheckFileNameExtension	(	TDes &	aFileName,
		const TDataType &	aDatatype
	)

Utility method for appending a correct file name extension for some content.

This method should be called if wanted quarantee that file extension of aFileName is correct with aDataType.

This method uses internal mapping table to find correct file extension to aFileName. Mapping table contains mainly extensions and datatypes, which cannot be recognized based on the data it self (No header information etc.).

This method replaces existing extension with correct one at aFileName if needed. If aDatatype is not found from mapping table or aDatatype is not supported by any application, aFileName will remain unchanged.

Parameters:

	aFileName	Append extension to this filename.
	aDataType	The content type of the file.

void CDocumentHandler::CloseSharableFS

(

)

Close sharable FileSession.

IMPORT_C TInt CDocumentHandler::CopyL	(	const RFile &	aFileOld,
		const TDesC &	aNameNew,
		TDataType &	aDataType,
		const TUint	aAttr
	)

Copy a file with handle aFileOld to the correct storage using name aNameNew and aFileAttr.

If aNameNew is empty, use the old name.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aFileOld	Handle of the file being copied.
	aNameNew	Name of the new file. If null, use the old name.
	aDataType	A data type for the file. If empty the DocumentHandler tries to recognize type.
	aAttr	Use these file attributes for saving. ReadOnly, ReadWrite.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C TInt CDocumentHandler::CopyL	(	const TDesC &	aFileNameOld,
		const TDesC &	aNameNew,
		TDataType &	aDataType,
		const TUint	aAttr
	)

Copy a file named aFileNameOld to the correct storage using name aNameNew and aFileAttr.

If aNameNew is empty, use the old name.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aFileNameOld	Name of the file being copied.
	aNameNew	Name of the new file. If null, use the old name.
	aDataType	A data type for the file. If empty the DocumentHandler tries to recognize type.
	aAttr	Use these file attributes for saving. ReadOnly, ReadWrite.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

TDocOperation CDocumentHandler::DocOperation

(

)

const

Get the operation code of the api entry function.

IMPORT_C TInt CDocumentHandler::GetPath

(

TDes &

aPath

)

Get the whole path including filename where the content was saved.

If the content was not saved to a file, this function returns a name that represents the saved object.

It may not be possible to open the object with the returned value, if it's not a real file in the filesystem. This situation may happen when e.g. the handler application stores it's contents in some weird data structure.

Parameters:

aPath

The path of the saved content.

Returns:: KErrNone if the path was found. KNotInitialised if the handler is not initialised.

IMPORT_C void CDocumentHandler::GetProgressiveDownloadAppUidsL

(

RArray< TInt32 > &

aUidList

)

Utility method to provide a list of applications that support progressive downloading.

The list of applications uids is configured central repository.

Parameters:

aUidList

A list of app Uids

IMPORT_C TInt CDocumentHandler::HandlerAppUid

(

TUid &

aUid

)

Get the uid of handler application.

In case of media files uid is Media Gallery's uid. This method should be called only succesfully completed DocumentHandler operations.

Parameters:

aUid

Uid of the handler application for the content.

Returns:: KErrNone if the uid was found. KNotInitialised if the handler is not initialised.

IMPORT_C CAiwGenericParamList& CDocumentHandler::InParamListL

(

)

Returns an empty instance of CAiwGenericParamList class.

It can be used for example as an input parameter list for API methods. This is just a convinience method and doesn't have to be used. If consumer wants to create input list by itself it is ok. If this method is used, service handler takes care of deleting returned generic parameter list.

Returns:: An empty instance of CAiwGenericParameter list.

IMPORT_C TInt CDocumentHandler::MoveL	(	const TDesC &	aFileNameOld,
		const TDesC &	aNameNew,
		TDataType &	aDataType,
		const TUint	aAttr
	)

Move a file named aFileNameOld to the correct storage using name aNameNew and aFileAttr.

Note that file in the old location (aFileNameOld) will be removed during this operation.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aFileNameOld	Name of the file being copied.
	aNameNew	Name of the new file. If null, use the default name for this mime-type.
	aDataType	A data type for the file. If empty the DocumentHandler tries to recognize type.
	aAttr	Use these file attributes for saving. ReadOnly, ReadWrite.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

static IMPORT_C CDocumentHandler* CDocumentHandler::NewL ( ) [static]

Two-phased constructor.

Leaves on failure.

Returns:: The constructed CDocumentHandler

static IMPORT_C CDocumentHandler* CDocumentHandler::NewL ( CEikProcess * aProcess ) [static]

Two-phased constructor.

Leaves on failure.

Parameters:

aProcess

The host process, which will be used for embedded launching.

Returns:: The constructed CDocumentHandler

Deprecated:: in Series60 3.0, instead use NewL without CEikProcess parameter

static IMPORT_C CDocumentHandler* CDocumentHandler::NewLC ( ) [static]

Two-phased constructor.

Leaves on failure.

Returns:: The constructed CDocumentHandler

static IMPORT_C CDocumentHandler* CDocumentHandler::NewLC ( CEikProcess * aProcess ) [static]

Two-phased constructor.

Leaves on failure.

Parameters:

aProcess

The host process, which will be used for embedded launching.

Returns:: The constructed CDocumentHandler

Deprecated:: in Series60 3.0, instead use NewL without CEikProcess parameter

IMPORT_C TInt CDocumentHandler::OpenFileEmbeddedL	(	const TDesC &	aFileName,
		TDataType &	aDataType
	)

Launches an application embedded capable of handling data in aFilename with aDataType.

Doesn't copy data from the file.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aFileName	Name of the file. Directory path included.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C TInt CDocumentHandler::OpenFileEmbeddedL	(	RFile &	aSharableFile,
		TDataType &	aDataType
	)

Launches an application in embedded (if possible) capable of handling data in aSharableFile (using aDatatype if available).

Doesn't save data from the file. In case of DRM protected files with restricted rights, there will be query asking if user want open file.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aSharableFile	A sharable file handle to be passed to the launched application.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C TInt CDocumentHandler::OpenFileEmbeddedL	(	RFile &	aSharableFile,
		TDataType &	aDataType,
		const CAiwGenericParamList &	aParamList
	)

Launches an application in embedded (if possible) capable of handling data in aSharableFile (using aDatatype if available).

Doesn't save data from the file. In case of DRM protected files with restricted rights, there will be query asking if user want open file.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aSharableFile	A sharable file handle to be passed to the launched application.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.
	aParamList	Parameter list to be passed to handler application.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C TInt CDocumentHandler::OpenFileL	(	const TDesC &	aFileName,
		TDataType &	aDataType
	)

Launches an application standalone capable of handling data in aFilename, with aDataType.

Doesn't copy data from the file.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aFileName	Name of the file. Directory path included.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C TInt CDocumentHandler::OpenFileL	(	RFile &	aSharableFile,
		TDataType &	aDataType
	)

Launches an application in standalone capable of handling data in aSharableFile (using aDatatype if available).

Doesn't save data from the file. In case of DRM protected files with restricted rights, there will be query asking if user want open file.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aSharableFile	A sharable file handle to be passed to the launched application
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C void CDocumentHandler::OpenTempFileL	(	const TDesC &	aFileName,
		RFile &	aSharableFile
	)

Utility method for opening filehandle from existing file for OpenFileL calls.

The created file handle is meant to be shared across process boundaries.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. These errors are usually trapped by the application framework.

NOTE! Caller is responsible of closing opened file handle.

Parameters:

	aFileName	Name (including directory information) for file. This file should exist allready, otherwise this function leaves with KErrNotFound.
	aSharableFile	Returned file handle that can be shared.

IMPORT_C const CAiwGenericParamList* CDocumentHandler::OutParamList

(

)

Returns a list of possible output parameters handler application may have set after executing the service.

The caller is responsible for deleting the parameter instance if not null.

Returns:: List of output parameters, NULL if nothing set.

Deprecated:

IMPORT_C TInt CDocumentHandler::SaveL	(	const TDesC8 &	aContent,
		TDataType &	aDataType,
		const TDesC &	aName,
		const TUint	aAttr
	)

Save aBuffer with aDataType using aAttr to a correct storage with a supplied name.

The storage is usually a filesystem, but can be anything from application spesific data structures to a database.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aContent	A content data buffer. Narrow descriptor that can contain any kind of data.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.
	aName	Use this name for saving. The name must not contain any directory information.
	aAttr	Use these file attributes for saving. Your can find these attributes from .h header file. If the storage is not a filesystem these attributes are ignored.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C TInt CDocumentHandler::SaveL	(	const TDesC8 &	aContent,
		TDataType &	aDataType,
		const TUint	aAttr
	)

Save aContent with aDataType using aAttr to a correct directory.

Generates a new name for saving. The storage is usually a filesystem, but can be anything from application spesific data structures to a database.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aContent	A content data buffer. Narrow descriptor that can contain any kind of data.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.
	aAttr	Use these file attributes for saving. Your can find these attributes from .h header file. If the storage is not a filesystem these attributes are ignored.

Returns:: KErrNone if success. KUserCancel if the user cancelled the operation.

IMPORT_C void CDocumentHandler::SaveTempFileL	(	const TDesC8 &	aContent,
		TDataType &	aDataType,
		const TDesC &	aFileName,
		RFile &	aSharableFile
	)

Utility method for save aContent with aDataType temporarily for OpenFileL calls.

The created file handle is meant to be shared across process boundaries.

This temporary file will be saved to process private temp directory. Temporary directory will be created if not existing yet.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. These errors are usually trapped by the application framework.

NOTE! Caller is responsible of closing opened file handle! Created temporary file will be deleted in destructor of DocumentHandler, but caller can delete it self as well.

Parameters:

	aContent	A content data buffer. Narrow descriptor that can contain any kind of data.
	aDataType	A data type for the content of the file. If empty the DocumentHandler tries to recognize the content.
	aFileName	Use this name for saving. The name must not contain any directory information.
	aSharableFile	Returned file handle that can be shared.

MAknServerAppExitObserver* CDocumentHandler::ServerAppExitObserver

(

)

const

Get the exit observer.

Returns:: Pointer to exit observer

IMPORT_C void CDocumentHandler::SetExitObserver

(

MAknServerAppExitObserver *

aObserver

)

Set an observer for embedded application exit events.

DocumentHandler will delegate embedding applications exit events to aObserver if it's not NULL:

Parameters:

aObserver

Exit observer

void CDocumentHandler::SetTempFile

(

const TDesC &

aTempFile

)

Set temporary file, which will be deleted in destructor.

IMPORT_C TInt CDocumentHandler::SilentMoveL	(	const TDesC &	aFileNameOld,
		const TDesC &	aNameNew,
		const TDesC &	aRootPath,
		TDataType &	aDataType,
		const TUint	aAttr
	)

Move a file named aFileNameOld to the correct storage using name aNameNew and aFileAttr.

This method operates silently, so nothing will be asked from user. Caller should give root path of the selected memory. Unique file name will be created automatically without user interaction. Note that file in the old location (aFileNameOld) will be removed during this operation.

This function can leave in some system wide error situation. E.g. out of memory, not enough space in filesystem etc. See also possible error codes from documenthandler.h header file.

Parameters:

	aFileNameOld	Name of the file being copied.
	aNameNew	Name of the new file. If null, use the default name for this mime-type.
	aRootPath	Root path of the selected memory where file should be moved.
	aDataType	A data type for the file. If empty the DocumentHandler tries to recognize type.
	aAttr	Use these file attributes for saving. ReadOnly, ReadWrite.

Returns:: KErrNone if success.

The documentation for this class was generated from the following file:

documenthandler.h

CDocumentHandler Class Reference

Capability Information

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation