diff -r aa99f2208aad -r b8d18c84f71c localisation/apparchitecture/inc/APPARC.H --- a/localisation/apparchitecture/inc/APPARC.H Wed Jul 28 16:03:37 2010 +0100 +++ b/localisation/apparchitecture/inc/APPARC.H Tue Aug 03 10:20:34 2010 +0100 @@ -1,7 +1,7 @@ // 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 "Eclipse Public License v1.0" +// under the terms of "Eclipse Public License v1.0" // which accompanies this distribution, and is available // at the URL "http://www.eclipse.org/legal/epl-v10.html". // @@ -16,593 +16,17 @@ #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. +// The content of this file has been split into: +#include +#include +#include -@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 +#endif // __APPARC_H__