diff -r e8c1ea2c6496 -r 8758140453c0 localisation/apparchitecture/inc/APPARC.H --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/localisation/apparchitecture/inc/APPARC.H Thu Jan 21 12:53:44 2010 +0000 @@ -0,0 +1,608 @@ +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Symbian Foundation License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#ifndef __APPARC_H__ +#define __APPARC_H__ + +#if !defined(__E32STD_H__) +#include +#endif +#if !defined(__E32BASE_H__) +#include +#endif +#if !defined(__F32FILE_H__) +#include +#endif +#if !defined(__GDI_H__) +#include +#endif +#if !defined(__APADEF_H__) +#include +#endif +#if !defined(__APAID_H__) +#include +#endif + +// classes defined: +class CApaApplication; +class CApaDocument; +class CApaProcess; +class MApaEmbeddedDocObserver; +// +// classes referenced: +class CApaDll; +class CApaExe; +class RFile; +class RReadStream; +class RWriteStream; +class CFileStore; +class CPersistentStore; +class CStreamDictionary; +class CDictionaryStore; +class TApaAppHolderInfo; +class CImplementationInformation; +class TApaApplicationFactory; +class CApaAppHolder; +class CApaAppServer; + +/** Creates an application interface object. + +Provides the basic roles of an application class as a factory that +creates concrete document objects, and supplies utility functions +not specific to any particular instance of a document. + +@publishedAll +@released +*/ +typedef CApaApplication* (*CreateCApaApplication)(); + + +// CApaApplication + +class CApaApplication : public CBase +// base class for applications; allows creation of documents & file stores + display of app icon and name. +/** Defines the basic behaviour for applications. + +The class defines the basic twin roles of an application class as a factory +that creates concrete document objects, and as a supplier of utility functions +not specific to any particular instance of a document. For example, returning +an application's caption, or accessing its .ini file. + +The class is derived from by the UI framework and is further derived from +by the UI application. + +@publishedAll +@released +@see CEikApplication */ + { +public: + /** Completes construction of this application object. + + The function is called after an instance of a derived class has been successfully + created using the ordinal 1 function of the application DLL. + + After calling this function, an application can create document objects. + + An implementation of this function is supplied by the UI framework. + + @see CEikApplication */ + virtual void PreDocConstructL()=0; // call once before creating document + + /** Creates a document object. + + The function is called by the application process when a new document is required. + The application process adds the new document to its list of documents. + + An implementation of this function is supplied by the UI framework. + + @param aProcess A pointer to the process associated with the application. + @return A pointer to the newly created document. + @see CApaProcess::AddNewDocumentL() */ + virtual CApaDocument* CreateDocumentL(CApaProcess* aProcess)=0; + + /** Gets the application specific UID. + + The UID is used to differentiate between UI applications. + + An implementation of this function must be supplied by the UI application. + + @return The application specific UID. */ + virtual TUid AppDllUid()const=0; + + // + // utility functions + IMPORT_C static TInt GenerateFileName(RFs& aFs,TFileName& aRootName); + IMPORT_C CDictionaryStore* OpenIniFileL(RFs& aFs)const; + + /** Opens the .ini file associated with the application, constructs the dictionary + store object, returns a pointer to it and puts the pointer onto the cleanupstack. + + The .ini file must be created, if it does not already exist. + + An implementation of this function is supplied by the UI framework. + + @param aFs Handle to a file server session + @return A pointer to the dictionary store object that represents the application's + .ini file. + @see CEikApplication */ + virtual CDictionaryStore* OpenIniFileLC(RFs& aFs)const=0; + // + // enquiry functions + IMPORT_C virtual TFileName AppFullName()const; // returns the full path and name of the app + /** Returns the capabilities of the application. + + Application capability information is represented by an instance of a TApaAppCapability + object wrapped in a packaged modifiable buffer descriptor. + + The function is called from a number of places within the application framework. + + An implementation of this function is supplied by the UI framework. + + @param aInfo A packaged modifiable buffer descriptor (a TPckgBuf), encapsulating + a TApaAppCapability object. + @see CEikApplication + @see TApaAppCapability + @see TPckgBuf */ + virtual void Capability(TDes8& aInfo)const=0; + // + // accessor function + IMPORT_C TFileName DllName()const; + + IMPORT_C ~CApaApplication(); + + // formerly a reserved virtual, Reserved_1() + IMPORT_C virtual void NewAppServerL(CApaAppServer*& aAppServer); +protected: + IMPORT_C CApaApplication(); + + IMPORT_C virtual void CApaApplication_Reserved1(); + IMPORT_C virtual void CApaApplication_Reserved2(); + +private: + CApaAppHolder* iAppHolder; // the CApaAppHolder that owns me + TUid iDtorKey; // TInt iSpare; + friend class CApaAppHolder; + friend class CApaProcess; + friend class TApaApplicationFactory; // so that it can access iDtorKey + +private: + TInt iCApaApplication_Reserved1; + }; + +class CApaDocument : public CBase +// base class for documents; allows insertion of glass doors. +/** Defines basic behaviour for documents. + +This is the base class for all documents. A document contains the data associated +with the application's content. + +The class is derived from by the UI framework and is further derived from +by the UI application. + +@publishedAll +@released +@see CEikDocument */ + { +public: + class TCapability + /** CApaDocument capabilities.*/ + { + public: + IMPORT_C TCapability(); + // + inline TBool CanDrawGlass()const; + inline TBool CanPrint()const; + inline void SetCanDrawGlass(); + inline void SetCanPrint(); + // + private: + enum { + ECanDrawGlass =0x01, + ECanPrint =0x02 + }; + private: + TUint iCapability; + TInt TCapability_Reserved1; + }; + // +public: + // document instantiation functions + /** Initialises a new, empty, document with a default setup. + + This can be the main document or an embedded document. The function is called + by the UI framework when it creates a default document file. + + An implementation of this function must be supplied by the UI application. + + If initialisation fails, the document must be left in the same state as it + was before the function was called. */ + virtual void NewDocumentL()=0; // builds a new embedded or main document without loading from a store (may create the content from eg code or a template file). + + /** Creates and fully initialises a new filestore and stores the document into it, + replacing any existing file of the same name. + + The function should put the pointer to the filestore object onto the cleanup + stack. + + An implementation of this function is supplied by the UI framework. + + @param aFs Handle to a file server session. + @param aFileName The full path name of the file to be created. + @return A pointer to the newly constructed file store. + @see CEikDocument */ + virtual CFileStore* CreateFileStoreLC(RFs& aFs,const TDesC& aFileName)=0; // creates a file for a document and stores itself to that store (store should be put on cleanup stack). + // + // interaction functions + IMPORT_C virtual CPicture* GlassPictureL(); // Does nothing by default, override to return handle to glass picture. + + /** Starts an editing session on an embedded document. + + The function should cause the application's UI to be created and the document + to be fully restored for editing. + + An implementation of this function is supplied by the UI framework. + + @param aContainer This document's observer. + @param aReadOnly True, the document should be opened in read-only mode and + should not persist any changes made to the content. False, the document can + be opened in read/write mode; this is the default. + @see CEikDocument */ + virtual void EditL(MApaEmbeddedDocObserver* aContainer,TBool aReadOnly=EFalse)=0; // Edit the document in the context of the container's environment. If aContainer is null, edit as the main document + + /** Prints the document without a need for it to be open for editing. + + Typically, this is called from a shell or a file manager type application + that wants to print the document without opening it fully. + + An empty implementation of this function is supplied by the UI framework. + + The UI application can provide its own implementation. + + @param aSourceStore A reference to the store containing the document. + @see CEikDocument */ + virtual void PrintL(const CStreamStore& aSourceStore)=0; // default print parameters, assume print context supplied by environment + // + // persistence functions + + /** Stores the document to the current file, commits the changes, and marks the + document status as unchanged. + + Typically, the function is called by the application when it implements a + "Save" type menu option in its User Interface. + + An implementation of this function is supplied by the UI framework. This is + adequate for direct file store applications. Applications using a permanent + file store model, need to provide their own implementation. + + If the function leaves, an implementation should ensure that any changes made + to the file are rolled back, leaving the file in the state it was in before + the function was called. + + @see CEikDocument */ + virtual void SaveL()=0; // save the doc to the file in the custody of iAppProcess. This fn should be called by any "Save" menu option. store->Commit() should be called within it. + /** Stores the document's content and state to the specified store, recording the + identity of any headstreams created in the specified stream dictionary. + + The store must be fully constructed before this function is called. + + An empty implementation of this function is supplied by the UI framework. + UI applications that need to persist any data must provide their own implementation. + + If the function leaves, an implementation should ensure that the store and + the stream dictionary are returned to the state they were in before the function + was called. + + @param aStore The store into which document data is to be stored. + @param aStreamDic The stream dictionary into which stream IDs and associated + UIDs are to be recorded. + @see CEikDocument */ + virtual void StoreL(CStreamStore& aStore,CStreamDictionary& aStreamDic) const=0; // store to aStore, lodging the headstream in aStreamDic + + /** Restores the document's content and state from data persisted in the specified + store. + + An empty implementation of this function is supplied by the UI framework. + UI applications that need to restore data must provide their own implementation. + + If the function leaves, an implementation should ensure that the store and + the stream dictionary are returned to the state they were in before the function + was called. + + @param aStore The store from which document data is to be restored. + @param aStreamDic The stream dictionary containing stream IDs and associated + UIDs. + @see CEikDocument */ + virtual void RestoreL(const CStreamStore& aStore,const CStreamDictionary& aStreamDic)=0; // restore from aStore using aStreamDic + + /** Restores the document to the extent that it does not need the store + further. + + A document only keeps a pointer to a store if it implements deferred + loading. This also tells the document that any store pointer that it + might have is just about to become invalid. + + An empty implementation of this function is supplied by the UI framework. + UI applications that support deferred loading or embedding should provide an + implementation. + + If a document supports embedding, then it should + propagate the DetachFromStoreL() call on to all embedded objects that + it contains. + + If the function leaves, the operation should be aborted + because the document has not successfully detached from the store. + Continuing with the operation may leave the document in an unsafe + state or cause user data to be lost. + + @param aDegree The degree of detachment required. */ + virtual void DetachFromStoreL(CPicture::TDetach /*aDegree*/=CPicture::EDetachFull) {} // supply an implementation if you support deferred loading or embedding + + IMPORT_C virtual void ExternalizeL(RWriteStream& aStream)const; + // + // enquiry functions + + /** Tests whether the document is empty. + + The UI framework provides a default implementation which always returns a + true value. + + The UI application can provide its own implementation. Typically, any application + that has editable content should supply an implementation that acts according + to the state of that content. Applications without associated document data + need not supply an implementation. + + @return True if the document is empty, false otherwise. + @see CEikDocument */ + virtual TBool IsEmpty()const=0; // return ETrue if the document is empty + IMPORT_C virtual void ValidatePasswordL()const; // return EFalse if there *is* a password *and* the user doesn't get it right, ETrue otherwise (ie they get it right or there isn't one). Returns ETrue by default + + IMPORT_C virtual TCapability Capability()const; // returns "cant do anything" by default + inline CApaApplication* Application()const; + inline CApaProcess* Process()const; + + /** Tests whether the document has changed since it was last persisted. + + An implementation of this function is supplied by the UI framework and need + not be changed by the UI application. + + @return True, if the document has changed since the last time that it was + persisted, false, otherwise. + @see CEikDocument */ + virtual TBool HasChanged()const =0; + // + IMPORT_C virtual ~CApaDocument(); +protected: + IMPORT_C CApaDocument(); + IMPORT_C CApaDocument(CApaApplication& aApp,CApaProcess& aProcess); +private: + IMPORT_C virtual void OpenFileL(CFileStore*& aFileStore, RFile& aFile); // was previously Reserved_1 + // Reserved virtual functions... + IMPORT_C virtual void Reserved_2(); +protected: + MApaEmbeddedDocObserver* iContainer; // null unless this is an embedded object currently being edited +private: + CApaApplication* iApplication; // the doc's associated application + CApaProcess* iApaProcess; + TInt iSpare; + }; + + + +class TApaApplicationFactory +/** Encapsulates the functionality of creating an application, whether it be via a factory function +or an ECOM plugin. Instances of this class can usually be created implicitly when required as +function parameters - just specify the function pointer, ECOM plugin UID or CImplementationInformation +reference. + +@publishedAll +@released +@see CApaProcess +@see EikStart */ + { +public: + typedef CApaApplication* (*TFunction)(); +public: + IMPORT_C TApaApplicationFactory(); + IMPORT_C TApaApplicationFactory(TFunction aFunction); + IMPORT_C TApaApplicationFactory(const CImplementationInformation& aEmbeddedApplicationInformation); + IMPORT_C TApaApplicationFactory(TUid aEmbeddedApplicationUid); + CApaApplication* CreateApplicationL() const; + HBufC* AppFileNameL() const; + TUid AppFileUid() const; +private: + enum TType + { + ETypeFunction, // if iType is this, iData is a TFunction + ETypeEmbeddedApplicationInformation, // if iType is this, iData is an ECOM CImplementationInformation + ETypeEmbeddedApplicationUid // if iType is this, iData is an ECOM implementation TUid + }; +private: + static CApaApplication* CreateEmbeddedApplicationL(TUid aUid); + static HBufC* EmbeddedApplicationDisplayNameLC(TUid aUid); + static HBufC* FullAppFileNameL(const TDesC& aAppName); + static void CleanupImplementationArray(TAny* aImplementationArray); +private: + TType iType; + TUint iData; + mutable CApaApplication* iApplication; // used to be iSpare1 + TInt iSpare2; + }; + +class CApaParentProcessMonitor; + +class CApaProcess : public CBase +/** 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. + +@publishedAll +@released +@see CApaApplication +@see CApaDocument */ + { +public: + IMPORT_C static CApaProcess* NewL(const RFs& aFs); + IMPORT_C void ResetL(); + // + // static utility functions + IMPORT_C static CStreamDictionary* ReadRootStreamLC(RFs& aFs,CFileStore*& aStore,const TDesC& aDocFullFileName,TUint aFileMode); // opens aDocFileName as aStore and returns the stream dictionary contained in its root stream on the cleanup stack + IMPORT_C static CStreamDictionary* ReadRootStreamLC(CFileStore*& aStore, const RFile& aFile); + IMPORT_C static void WriteRootStreamL(CPersistentStore& aStore,CStreamDictionary& aStreamDic,const CApaApplication& aApp); + IMPORT_C static void WriteRootStreamL(CPersistentStore& aStore,CStreamDictionary& aStreamDic,const TApaAppIdentifier& aAppId); + IMPORT_C static TApaAppIdentifier ReadAppIdentifierL(const CStreamStore& aStore,const CStreamDictionary& aStreamDic); + IMPORT_C static void WriteAppIdentifierL(CStreamStore& aStore,CStreamDictionary& aStreamDic,const TApaAppIdentifier& aAppId); + // + // document management + IMPORT_C CApaDocument* AddNewDocumentL(TApaApplicationFactory aApplicationFactory); + IMPORT_C CApaDocument* OpenNewDocumentL(CFileStore*& aStore,CStreamDictionary*& aStreamDic,const TDesC& aDocFullFileName,TUint aFileMode); // Open a file and restore the contained document + IMPORT_C void DestroyDocument(CApaDocument* aDoc); // Removes a doc (identified by the object) from the list and destroys it. Also removes the app and closes the AppDll if appropriate. + // + // setter functions + IMPORT_C void SetMainDocument(CApaDocument* aDocument); + IMPORT_C void SetMainDocFileName(const TDesC& aMainDocFileName); // panics if the descriptor is too long + IMPORT_C void SetMainDocFileNameL(const TDesC& aMainDocFileName); + // + // accessor functions + IMPORT_C TPtrC MainDocFileName()const; + inline RFs& FsSession()const; + inline CApaDocument* MainDocument()const; + // + IMPORT_C ~CApaProcess(); +protected: + IMPORT_C CApaProcess(); + IMPORT_C CApaProcess(const RFs& aFs); + IMPORT_C void ConstructL(); + IMPORT_C void ConstructL(TProcessId aParentProcessId); + + IMPORT_C virtual void CApaProcess_Reserved1(); + IMPORT_C virtual void CApaProcess_Reserved2(); +public: + static TInt IdleRemoveApplications(TAny* aThis); + void RemoveMarkedApplications(); +private: + CApaDll* AddAppDllL(const TDesC& aDllFullPath); + CApaExe* AddAppExeL(TApaApplicationFactory aApplicationFactory); + void RemoveApp(CApaAppHolder* aAppHolder); + CApaDocument* CreateDocL(CApaApplication* aApp); + CApaAppHolder* FindAppInListL(const TDesC& aAppFileName,TUid aUid)const; // returns NULL if not in list + void DeleteAllDocs(); + void MarkApplicationForRemoval(const CApaApplication* aApp); + static void DoReadRootStreamL(CStreamDictionary& aStreamDictionary, const CFileStore& aStore); +private: + CArrayFixFlat* iAppList; // array of apps in use + CArrayFixFlat* iDocList; // array of documents (1 main + n embedded) + CApaDocument* iMainDoc; + HBufC* iMainDocFileName; + RFs iFsSession; // file server session for doc store + CIdle* iApplicationRemover; + CApaParentProcessMonitor* iMonitor; + TInt iCApaProcess_Reserved1; + }; + + +class MApaEmbeddedDocObserver +/** An interface class for handling the completion of the editing of an embedded +document. + +@publishedAll +@released +@see CApaDocument::EditL() */ + { +public: + /** Defines the state of the embedded document on completion of editing. */ + enum TExitMode { + /** Changes to the embedded document must be saved. */ + EKeepChanges, + /** Reverts back to the saved version of the embedded document, i.e. reloads the + whole document. */ + ERevertToSaved, + /** No changes have been made to the embedded document. */ + ENoChanges, + /** The embedded document is empty. */ + EEmpty + }; +public: + /** Implements the required behaviour when the editing of an embedded document completes. + + @param aMode Indicates the state of the document. */ + virtual void NotifyExit(TExitMode aMode)=0; // called on completion of editing of an embedded document +protected: + IMPORT_C MApaEmbeddedDocObserver(); +private: + IMPORT_C virtual void MApaEmbeddedDocObserver_Reserved1(); + IMPORT_C virtual void MApaEmbeddedDocObserver_Reserved2(); +private: + TInt iMApaEmbeddedDocObserver_Reserved1; + }; + + +//// inlines //// +inline CApaApplication* CApaDocument::Application()const +/** Returns a pointer to the application that created the document. + +@return A pointer to the document's associated application. */ + { return iApplication; } + +inline CApaProcess* CApaDocument::Process()const +/** Returns a pointer to the application process associated with this document. + +@return A pointer to the application process associated with this document. */ + { return iApaProcess; } + +inline TBool CApaDocument::TCapability::CanDrawGlass()const +/** Tests whether the document supports being embedded as a glass door. + +@return True if embedding as a glass door is supported; false otherwise. */ + { return iCapability&ECanDrawGlass; } + +inline TBool CApaDocument::TCapability::CanPrint()const +/** Tests whether the document supports being printed without using the full application +UI. + +@return True, if printing is supported; false, otherwise. */ + { return iCapability&ECanPrint; } + +inline void CApaDocument::TCapability::SetCanDrawGlass() +/** Sets the document as being capable of being embedded as a glass door. */ + { iCapability = iCapability|ECanDrawGlass; } + +inline void CApaDocument::TCapability::SetCanPrint() +/** Sets the document as being capable of being printed without using the full application +UI. */ + { iCapability = iCapability|ECanPrint; } + +inline RFs& CApaProcess::FsSession()const +/** Returns a handle to the file server session used by this application process. + +@return The file server session. */ + { return (RFs&)iFsSession; } //lint !e1536 Exposing low access member - Kept for backward BC + +inline CApaDocument* CApaProcess::MainDocument()const +/** Returns a pointer to the main document. + +@return A pointer to the main document. */ + { return iMainDoc; } + +#endif