Class CApaProcess

CApaProcess

Support

Supported from 5.0

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.

Derivation

CApaProcess Maintains a list of documents and all of the potentially shared resources used by documents CBase Base class for all classes to be instantiated on the heap

Defined in CApaProcess:
AddNewDocumentL(), CApaProcess(), ConstructL(), DestroyDocument(), FsSession(), MainDocFileName(), MainDocument(), NewL(), OpenNewDocumentL(), ReadAppIdentifierL(), ReadRootStreamLC(), ResetL(), SetMainDocFileName(), SetMainDocument(), TempFilePath(), WriteAppIdentifierL(), WriteRootStreamL(), ~CApaProcess()

Inherited from CBase:
operator new()

See also:

• CApaApplication
• CApaDocument

static CApaProcess* NewL(const RFs& aFs,CApaAppFinder& aAppFinder);

Description

Creates and returns a pointer to a new application process.

This function is not used by UI applications.

Parameters

const RFs& aFs Handle to a file server session. CApaAppFinder& aAppFinder An object for finding applications within the file system. This is not part of the public API. The process takes ownership of this object and takes responsibility for deleting it, even if the function leaves.

Return value

CApaProcess* Pointer to the new application process.

protected: CApaProcess(const RFs& aFs,CApaAppFinder& aAppFinder);

Description

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

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

This constructor is used by the UI framework.

Parameters

const RFs& aFs Handle to a file server session CApaAppFinder& aAppFinder An object for finding applications within the file system. This is not part of the public API.

protected: void ConstructL();

Description

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.

void ResetL();

Description

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.

~CApaProcess();

Description

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.

CApaDocument* AddNewDocumentL(const TDesC& aDllFileName,TUid aDllUid=KNullUid);

Description

Creates and adds a new document of the specified application type.

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

The function creates a new application object, a CApaApplication type, if this is the first document of that type to be added.

The search strategy for the application DLL depends on the the specified file name and UID. If the full path name of a DLL is specified, then that DLL is located and loaded. If the full path name is not specified and a UID is specified, then a DLL matching that UID is located and loaded. If the full path name is not specified and the UID is null, then a DLL with matching filename is located and loaded.

The function leaves with KErrNotFound if no suitable application DLL can be found.

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

Parameters

const TDesC& aDllFileName Filename of the application DLL. TUid aDllUid UID of the application. If this is not specified, the default is KNullUid.

Return value

CApaDocument* A pointer to the new document.

See also:

• CApaProcess::DestroyDocument()
• CApaApplication
• KNullUid

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

Description

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

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

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

Parameters

CFileStore*& aStore On return, this contains a pointer to the store object created during the restore. CStreamDictionary*& aStreamDic On return, this contains a pointer to the stream dictionary object created during the restore. const TDesC& aDocFullFileName The name of the file containing the document. TUint aFileMode The mode in which to open the file.

Return value

CApaDocument* A pointer to the restored document.

See also:

• TFileMode
• CApaProcess::DestroyDocument()

void DestroyDocument(CApaDocument* aDoc);

Description

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

CApaDocument* aDoc A pointer to the document to be destroyed.

See also:

• CApaApplication
• CApaProcess

CApaDocument* MainDocument() const;

Description

Returns a pointer to the main document.

Return value

CApaDocument* A pointer to the main document.

void SetMainDocument(CApaDocument* aDocument);

Description

Sets the main document.

Parameters

CApaDocument* 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

See also:

• CApaProcess::AddNewDocumentL()
• CApaProcess::OpenNewDocumentL()

TPtrC MainDocFileName() const;

Description

Returns the filename of the main document.

Return value

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

void SetMainDocFileName(const TDesC& aMainDocFileName);

Description

Sets the filename of the main document.

Parameters

const TDesC& aMainDocFileName The filename to be set. If the length of this descriptor is greater than KMaxFileName, then the function raises an APPARC 7 panic

See also:

• KMaxFileName

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

Description

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, as indicated by the UID value(s), otherwise the function leaves with KErrCorrupt.

Parameters

RFs& aFs Handle to a file server session. CFileStore*& aStore On return, a pointer to the newly created file store object. Const TDesC& aDocFullFileName The full path name of the document file. TUint aFileMode The mode in which to open the file.

Return value

CStreamDictionary* A pointer to the stream dictionary object read from the root stream of the store.

See also:

• TFileMode

static void WriteRootStreamL(CPersistentStore& aStore,CStreamDictionary& aStreamDic,const CApaApplication& aApp);
static void WriteRootStreamL(CPersistentStore& aStore,CStreamDictionary& aStreamDic,const TApaAppIdentifier& aAppId);

Description

Writes the application identifier stream 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

CPersistentStore& 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. CStreamDictionary& aStreamDic The stream dictionary containing the locations and associated UIDs of other streams in the store. const CApaApplication& 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. const TApaAppIdentifier& aAppId The application identifier to be written into the application identifier stream.

static TApaAppIdentifier ReadAppIdentifierL(const CStreamStore& aStore,const CStreamDictionary& aStreamDic);

Description

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

const CStreamStore& aStore The store from which the application identifier should be read. const CStreamDictionary& 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

TApaAppIdentifier The application identifier.

static void WriteAppIdentifierL(CStreamStore& aStore,CStreamDictionary& aStreamDic,const TApaAppIdentifier& aAppId);

Description

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

CStreamStore& aStore The store to which the application identifier should be written. CStreamDictionary& aStreamDic The stream dictionary. const TApaAppIdentifier& aAppId The application identifier to be externalised to a stream.

RFs& FsSession() const;

Description

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

Return value

RFs& The file server session.

TPtrC TempFilePath() const;

Description

Returns the path of the directory in which temporary files should be created.

There is only one path for temporary files in the whole system, and this is just a convenient accessor to return its location.

Return value

TPtrC The pathname of the directory.