CApaProcess Class Reference

#include <mw/apaproc.h>

class CApaProcess : public CBase

Inherits from

CApaProcess
- CBase

Public Member Functions
	~CApaProcess()
IMPORT_C CApaDocument *	AddNewDocumentL(TApaApplicationFactory)
IMPORT_C void	DestroyDocument(CApaDocument *)
RFs &	FsSession()
IMPORT_C TPtrC	MainDocFileName()
CApaDocument *	MainDocument()
IMPORT_C CApaProcess *	NewL(const RFs &)
IMPORT_C CApaDocument *	OpenNewDocumentL(CFileStore &, CStreamDictionary &, const TDesC &, TUint)
IMPORT_C TApaAppIdentifier	ReadAppIdentifierL(const CStreamStore &, const CStreamDictionary &)
IMPORT_C CStreamDictionary *	ReadRootStreamLC(RFs &, CFileStore *&, const TDesC &, TUint)
IMPORT_C CStreamDictionary *	ReadRootStreamLC(CFileStore *&, const RFile &)
IMPORT_C void	ResetL()
IMPORT_C void	SetMainDocFileName(const TDesC &)
IMPORT_C void	SetMainDocFileNameL(const TDesC &)
IMPORT_C void	SetMainDocument(CApaDocument *)
IMPORT_C void	WriteAppIdentifierL(CStreamStore &, CStreamDictionary &, const TApaAppIdentifier &)
IMPORT_C void	WriteRootStreamL(CPersistentStore &, CStreamDictionary &, const CApaApplication &)
IMPORT_C void	WriteRootStreamL(CPersistentStore &, CStreamDictionary &, const TApaAppIdentifier &)

Protected Member Functions
	CApaProcess()
	CApaProcess(const RFs &)
virtual IMPORT_C void	CApaProcess_Reserved1()
virtual IMPORT_C void	CApaProcess_Reserved2()
IMPORT_C void	ConstructL()
IMPORT_C void	ConstructL(TProcessId)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Maintains a list of documents and all of the potentially shared resources used by documents.

This includes the application DLLs. The class also supplies utility functions that provide the basic structure for persisted document files.

The class deals with the loading of application DLLs and manages the creation and destruction of application (CApaApplication) objects and document (CApaDocument) objects.

The class is derived from by the UI framework and further derivation by the UI application is not necessary unless it needs to add extra utility functions for the use of applications.

Constructor & Destructor Documentation

CApaProcess ( )

IMPORT_C

CApaProcess

(

)

[protected]

Constructor for CApaProcess

CApaProcess ( const RFs & )

IMPORT_C

CApaProcess

(

const RFs &

aFs

)

[protected]

Constructs the application process object with the specified file session handle.

Derived classes must define and implement a constructor through which the file session handle can be specified. A typical implementation calls this constructor through a constructor initialization list.

This constructor is used by the UI framework.

Deprecated

Parameters
aFs	Handle to a file server session

~CApaProcess ( )

IMPORT_C

~CApaProcess

(

)

Frees resources prior to destruction.

Documents must be saved before the application process is deleted, otherwise data may be lost.

In debug mode, the destructor raises an APPARC 6 panic if documents still exist, and an APPARC 5 panic if applications still exist.

Member Function Documentation

AddNewDocumentL ( TApaApplicationFactory )

IMPORT_C CApaDocument *

AddNewDocumentL

(

TApaApplicationFactory

aApplicationFactory

)

Creates and adds a new document using the specified application factory.

The document may be a main document or an embedded document.

Any document created with this function must be destroyed using DestroyDocument().

Parameters
aApplicationFactory	Should be created implicitly by passing a pointer to a factory function, an ECOM plugin UID, or a CImplementationInformation reference.

Return Value: A pointer to the new document.

CApaProcess_Reserved1 ( )

IMPORT_C void

CApaProcess_Reserved1

(

)

[protected, virtual]

Reserved for future use

CApaProcess_Reserved2 ( )

IMPORT_C void

CApaProcess_Reserved2

(

)

[protected, virtual]

Reserved for future use

ConstructL ( )

IMPORT_C void

ConstructL

(

)

[protected]

Completes construction of the application process object.

Implementers of derived classes must call this function as part of the second stage construction of an object. Typically, derived classes implement their own NewL() function and call ConstructL() as part of that implementation.

ConstructL ( TProcessId )

IMPORT_C void

ConstructL

(

TProcessId

aParentProcessId

)

[protected]

Completes construction of the application process object, passing in a Parent Process Identifier.

Parameters
aParentProcessId	Id of the parent process. This process will terminate when the parent does.

DestroyDocument ( CApaDocument * )

IMPORT_C void

DestroyDocument

(

CApaDocument *

aDoc

)

Destroys the specified document.

All references to the document are removed, and associated resources are freed. Specifically, the function deletes any associated application and unloads the application DLL, provided that no other documents of that application type are still open.

All document objects created through CApaProcess must be deleted using this function.

Parameters
aDoc	A pointer to the document to be destroyed.

FsSession ( )

RFs &

FsSession

(

)

const [inline]

Returns a handle to the file server session used by this application process.

Return Value: The file server session.

MainDocFileName ( )

IMPORT_C TPtrC

MainDocFileName

(

)

const

Returns the filename of the main document.

Return Value: A non-modifiable pointer descriptor to the main document filename. For non file-based applications, the length of this descriptor is zero.

MainDocument ( )

CApaDocument *

MainDocument

(

)

const [inline]

Returns a pointer to the main document.

Return Value: A pointer to the main document.

NewL ( const RFs & )

IMPORT_C CApaProcess *

NewL

(

const RFs &

aFs

)

[static]

Creates and returns a pointer to a new application process.

This function is not used by UI applications.

Parameters
aFs	Handle to a file server session.

Return Value: Pointer to the new application process.

OpenNewDocumentL ( CFileStore &, CStreamDictionary &, const TDesC &, TUint )

IMPORT_C CApaDocument *	OpenNewDocumentL	(	CFileStore *&	aStore,
			CStreamDictionary *&	aStreamDic,
			const TDesC &	aDocFullFileName,
			TUint	aFileMode
		)

Opens the specified file and restores the content as a document.

The created document can be merged into or embedded in another document.

Any document created with this function must be destroyed using DestroyDocument().

See also: TFileMode CApaProcess::DestroyDocument()

Parameters
aStore	On return, this contains a pointer to the store object created during the restore.
aStreamDic	On return, this contains a pointer to the stream dictionary object created during the restore.
aDocFullFileName	The name of the file containing the document.
aFileMode	The mode in which to open the file.

Return Value: A pointer to the restored document.

ReadAppIdentifierL ( const CStreamStore &, const CStreamDictionary & )

IMPORT_C TApaAppIdentifier	ReadAppIdentifierL	(	const CStreamStore &	aStore,
			const CStreamDictionary &	aStreamDic
		)	[static]

Reads the application identifier from its stream in the specified store and returns it.

The location of the stream is found in the specified stream dictionary.

Parameters
aStore	The store from which the application identifier should be read.
aStreamDic	The stream dictionary containing the stream ID of the application identifier stream. The stream dictionary can be found in the root stream of the store.

Return Value: The application identifier.

ReadRootStreamLC ( RFs &, CFileStore *&, const TDesC &, TUint )

IMPORT_C CStreamDictionary *	ReadRootStreamLC	(	RFs &	aFs,
			CFileStore *&	aStore,
			const TDesC &	aDocFullFileName,
			TUint	aFileMode
		)	[static]

Reads the stream dictionary contained as the root stream in the specified document file.

The function constructs, and returns a pointer to the stream dictionary object and puts the pointer to the stream dictionary object onto the cleanup stack. It also returns a pointer to the created file store object through an argument reference.

The file must be a valid document file; otherwise the function leaves with one of the system-wide error codes.

ReadRootStreamLC ( CFileStore *&, const RFile & )

IMPORT_C CStreamDictionary *	ReadRootStreamLC	(	CFileStore *&	aStore,
			const RFile &	aFile
		)	[static]

ResetL ( )

IMPORT_C void

ResetL

(

)

Resets the the application process to its initial state.

Specifically, it saves the main document, deletes the main and all embedded documents from memory, resets the main document filename and deletes all applications except the main application.

The function can leave if saving the main document fails.

SetMainDocFileName ( const TDesC & )

IMPORT_C void

SetMainDocFileName

(

const TDesC &

aMainDocFileName

)

Sets the filename of the main document.

Parameters
aMainDocFileName	The filename to be set.

Panic Codes
APPARC	7 If the length of aMainDocFileName is greater than KMaxFileName or the length of the last filename set by SetMainDocFileNameL if greater

SetMainDocFileNameL ( const TDesC & )

IMPORT_C void

SetMainDocFileNameL

(

const TDesC &

aMainDocFileName

)

Sets the filename of the main document.

Parameters
aMainDocFileName	The filename to be set. There is no restriction on the length of this descriptor.

SetMainDocument ( CApaDocument * )

IMPORT_C void

SetMainDocument

(

CApaDocument *

aDocument

)

Sets the main document.

Parameters
aDocument	A pointer to the document to be set as the main document of the application process. This must be a an object created by the AddNewDocumentL() or OpenNewDocumentL() functions

WriteAppIdentifierL ( CStreamStore &, CStreamDictionary &, const TApaAppIdentifier & )

IMPORT_C void	WriteAppIdentifierL	(	CStreamStore &	aStore,
			CStreamDictionary &	aStreamDic,
			const TApaAppIdentifier &	aAppId
		)	[static]

Writes the application identifier to a new stream in the specified store and records the location of this stream in the specified stream dictionary.

Parameters
aStore	The store to which the application identifier should be written.
aStreamDic	The stream dictionary.
aAppId	The application identifier to be externalised to a stream.

WriteRootStreamL ( CPersistentStore &, CStreamDictionary &, const CApaApplication & )

IMPORT_C void	WriteRootStreamL	(	CPersistentStore &	aStore,
			CStreamDictionary &	aStreamDic,
			const CApaApplication &	aApp
		)	[static]

Writes the application identifier (derived from the application object CApaApplication) followed by the stream dictionary to the store and makes the stream dictionary the root stream of the store.

Typically, the function is called by the application when it implements a file create or file save type operation. It is called after all model and UI data has been persisted. The IDs of the streams containing the model and UI data should have been lodged in the stream dictionary.

In effect, the function finishes off the file save or file create type operation, leaving the file containing the store in a valid state with the standard interface.

Parameters
aStore	The store to which the root stream is to be written. Before calling this function, a reference to the store must be saved by putting a pointer onto the cleanup stack or by making it member data of a class. This ensures that it is not orphaned in the event of this function leaving.
aStreamDic	The stream dictionary containing the locations and associated UIDs of other streams in the store.
aApp	The application used to create the main document in the file being written. The application identifier to be written is constructed from this application object.

WriteRootStreamL ( CPersistentStore &, CStreamDictionary &, const TApaAppIdentifier & )

IMPORT_C void	WriteRootStreamL	(	CPersistentStore &	aStore,
			CStreamDictionary &	aStreamDic,
			const TApaAppIdentifier &	aAppId
		)	[static]

Writes the application identifier followed by the stream dictionary to the store and makes the stream dictionary the root stream of the store.

In effect, the function finishes off the file save or file create type operation, leaving the file containing the store in a valid state with the standard interface.

Parameters
aStore	The store to which the root stream is to be written. Before calling this function, a reference to the store must be saved by putting a pointer onto the cleanup stack or by making it member data of a class. This ensures that it is not orphaned in the event of this function leaving.
aStreamDic	The stream dictionary containing the locations and associated UIDs of other streams in the store.
aAppId	The application identifier to be written into the application identifier stream.

Parameters
aFs	Handle to a file server session.
aStore	On return, a pointer to the newly created file store object.
aDocFullFileName	The full path name of the document file.
aFileMode	The mode in which to open the file.

CApaProcess Class Reference

Inherits from

Detailed Description

Constructor & Destructor Documentation

CApaProcess ( )

CApaProcess ( const RFs & )

~CApaProcess ( )

Member Function Documentation

AddNewDocumentL ( TApaApplicationFactory )

CApaProcess_Reserved1 ( )

CApaProcess_Reserved2 ( )

ConstructL ( )

ConstructL ( TProcessId )

DestroyDocument ( CApaDocument * )

FsSession ( )

MainDocFileName ( )

MainDocument ( )

NewL ( const RFs & )

OpenNewDocumentL ( CFileStore *&, CStreamDictionary *&, const TDesC &, TUint )

ReadAppIdentifierL ( const CStreamStore &, const CStreamDictionary & )

ReadRootStreamLC ( RFs &, CFileStore *&, const TDesC &, TUint )

ReadRootStreamLC ( CFileStore *&, const RFile & )

ResetL ( )

SetMainDocFileName ( const TDesC & )

SetMainDocFileNameL ( const TDesC & )

SetMainDocument ( CApaDocument * )

WriteAppIdentifierL ( CStreamStore &, CStreamDictionary &, const TApaAppIdentifier & )

WriteRootStreamL ( CPersistentStore &, CStreamDictionary &, const CApaApplication & )

WriteRootStreamL ( CPersistentStore &, CStreamDictionary &, const TApaAppIdentifier & )

OpenNewDocumentL ( CFileStore &, CStreamDictionary &, const TDesC &, TUint )