// 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" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __APPARC_H__

#define __APPARC_H__

#if !defined(__E32STD_H__)

#include <e32std.h>

#endif

#if !defined(__E32BASE_H__)

#include <e32base.h>

#endif

#if !defined(__F32FILE_H__)

#include <f32file.h>

#endif

#if !defined(__GDI_H__)

#include <gdi.h>

#endif

#if !defined(__APADEF_H__)

#include <apadef.h>

#endif

#if !defined(__APAID_H__)

#include <apaid.h>

#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);