// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// 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".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// MSVAPI.H

//

/**

 * @file 

 * @publishedAll

 * @released

 */

#ifdef _DEBUG

#undef _NO_SESSION_LOGGING_

#endif

#ifndef __MSVAPI_H__

#define __MSVAPI_H__

#include <e32base.h>

#include <s32file.h>

#ifdef _MSVAPI_DONT_INCLUDE_FLOGGER_

	#ifndef _NO_SESSION_LOGGING_

		#define _NO_SESSION_LOGGING_

	#endif

#else

	#include <flogger.h>

#endif

#include <msvstd.h>

#include <msvstore.h>

#include <msvarray.h>

#include <mclient.h>

#include <tmsvsystemprogress.h>

// Forward declarations

class CMsvSession;

class CMsvEntry;

class CBaseMtm;

class CMsvClientEntry;

class CMsvEntryArray;

class CMsvServer;

class CMsvServerEntry;

class CMsvSearchSortOperation;

// Remove these to remove client logging

//#define _NO_SESSION_LOGGING_

#define _NO_SESSION_LOGGING_SERIAL_

// Single export used to start the message server

IMPORT_C TInt StartMessageServer(TAny*);

// Create Message Server and return a server entry owned by caller

// This is all that is required to test server Mtm's

IMPORT_C CServer2* CreateMessageServerL(CMsvServerEntry*& aServerEntry);

//**********************************

// CMsvOperation

//**********************************

//

// Abstract base class for operations controlling asynchronous functions

//

class CMsvOperation : public CActive

/** Defines an interface for use by objects which control asynchronous commands 

in the messaging system. 

Such objects are returned by CMsvEntry and User Interface MTM functions that 

complete asynchronously. The interface allows clients to:

1. get progress information about the operation

2. cancel the operation

3. be signalled asynchronously when the operation completes; a client passes 

in a TRequestStatus of a suitable active object for this purpose

The client only needs to understand the CMsvOperation interface, not the concrete 

implementation used. 

Writing derived classes:

As the base class interface for User Interface MTMs, CBaseUiMtm, defines functions 

that return CMsvOperation objects for control of asynchronous operations, 

implementers of these MTM components are required to provide suitable derived 

classes. For example, if CBaseUiMtm::EditL() is implemented to provide message 

editing, a CMsvOperation -derived class would be provided that completes when 

the editing operation is complete.

Concrete derived classes must provide implementations of the pure virtual 

DoCancel() and RunL() functions defined by CActive. DoCancel() should be provided 

in the normal way to cancel the operation. RunL() should, in addition to any 

other required functionality, always end by signalling the client that the 

operation is complete with a suitable completion code. 

@publishedAll

@released

*/

	{

public:

	IMPORT_C CMsvOperation(CMsvSession& aMsvSession, TInt aPriority, TRequestStatus& aObserverRequestStatus);

	IMPORT_C ~CMsvOperation();

	/** Gets information on the progress of the operation. 

	All operations on local entries share the same progress information format, 

	which defined by TMsvLocalOperationProgress. 

	For MTM-specific operations, progress information can be extracted by calling 

	CBaseUiMtm::GetProgress() or displayed by CBaseUiMtm::DisplayProgressSummary() 

	on the appropriate User Interface MTM.

	Requirements:

	Derived classes should implement this function so that the client can check 

	on the progress of the operation. The function should share an understanding 

	of the format of the buffer with the implementations of CBaseUiMtm::GetProgress() 

	and CBaseUiMtm::DisplayProgressSummary() in the User Interface MTM. The arguments 

	of CBaseUiMtm::GetProgress() show some information that should be included 

	where appropriate.

	@leave KErrNotReady The operation has not yet been started: it has been queued 

	for execution in the Message Server 

	@return Descriptor holding progress information. The maximum buffer size should 

	be KMsvProgressBufferLength (defined in msvipc.h). */

	virtual const TDesC8& ProgressL()=0;

	IMPORT_C virtual const TDesC8& FinalProgress();

	IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg);

	IMPORT_C virtual TUid Mtm() const;

	//

	inline TMsvOp Id() const;

	inline TMsvId Service() const;

	//

protected:

	IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);

protected:

	/** The ID of the service that is associated with this operation. 

	Usually, the derived class constructor will contain a suitable argument to 

	allow the caller to set this.

	@see Service() */

	TMsvId iService;

	/** The UID of the MTM associated with the operation. 

	The appropriate value should be set by the derived class constructor.

	@see Mtm() */

	TUid iMtm;

	/** Request status of the operation observer. 

	This is the aObserverRequestStatus passed in the constructor. */

	TRequestStatus& iObserverRequestStatus;

	/** Message Server session used by object. This is set by the constructor. */

	CMsvSession& iMsvSession;

private:

	TMsvOp iId;

	};

//**********************************

// CMsvOperationWait

//**********************************

//

// Allows a synchronous wait on a operation

//

class CMsvOperationWait: public CActive

/** Utility class used to wait until an asynchronous messaging operation

has completed. 

Note that CMsvOperationActiveSchedulerWait is simpler to use, and should be used in 

preference to this class.

To use the class:

1. Create a new CMsvOperationWait object

2. Call the messaging function that returns the asynchronous operation. 

The operation observer parameter should be the iStatus word of the CMsvOperationWait 

object. This means that the CMsvOperationWait object will be signalled when

the operation completes.

3. Call the CMsvOperationWait object's Start() function. This sets the object

to be active.

4. Call CActiveScheduler::Start(). This starts a nested active scheduler. The 

program will then wait until this active scheduler is stopped. The CMsvOperationWait 

object stops the scheduler when the operation completes, allowing the program to 

continue. 

These steps cause the program to wait until the operation completes.

@code

     CMsvOperationWait* waiter=CMsvOperationWait::NewLC();

     CMsvOperation* op = function_returning_opLC(waiter->iStatus);

     waiter->Start();

     CActiveScheduler::Start();

     CleanupStack::PopAndDestroy(2); // op, waiter

@endcode

@see CActiveScheduler

@publishedAll

@released

*/

	{

public:

	IMPORT_C static CMsvOperationWait* NewLC(TInt aPriority=EPriorityStandard);

	IMPORT_C ~CMsvOperationWait();

	IMPORT_C void Start();

protected:

	CMsvOperationWait(TInt aPriority);

	void RunL();

	void DoCancel();

	};

//**********************************

// CMsvOperationActiveSchedulerWait

//**********************************

//

// Allows a synchronous wait on a operation using CActiveSchedulerWait class

// This class should be used in preference to CMsvOperationWait

// DOES NOT require an explicit call to CActiveScheduler::Start()--CMsvOperationActiveSchedulerWait::Start()

// effectively encapsulates this functionality

//

class CMsvOperationActiveSchedulerWait: public CActive

/** Utility class used to wait until an asynchronous messaging operation

has completed. 

To use the class:

1. Create a new CMsvOperationActiveSchedulerWait object

2. Call the messaging function that returns the asynchronous operation. 

The operation observer parameter should be the iStatus word of the CMsvOperationActiveSchedulerWait 

object. This means that the CMsvOperationActiveSchedulerWait object will be signalled when

the operation completes.

3. Call the CMsvOperationActiveSchedulerWait object's Start() function. This sets the object

to be active.

These steps cause the program to wait until the operation completes.

@code

     CMsvOperationActiveSchedulerWait* waiter=CMsvOperationActiveSchedulerWait::NewLC();

     CMsvOperation* op = function_returning_opLC(waiter->iStatus);

     waiter->Start();

     CleanupStack::PopAndDestroy(2); // op, waiter

@endcode

@publishedAll

@released

*/

	{

public:

	IMPORT_C static CMsvOperationActiveSchedulerWait* NewLC(TInt aPriority=EPriorityStandard);

	IMPORT_C ~CMsvOperationActiveSchedulerWait();

	IMPORT_C void Start();

private:

	CMsvOperationActiveSchedulerWait(TInt aPriority);

	void RunL();

	void DoCancel();

private:

	CActiveSchedulerWait iActiveSchedulerWait;

	};

//**********************************

// CMsvCompletedOperation

//**********************************

//

// An operation which is already completed on construction

//

class CMsvCompletedOperation : public CMsvOperation

/** Utility to create a messaging operation object for an operation that has already 

completed. 

This utility is useful, for example, for writers of MTMs, where the API requires that an 

asynchronous operation is returned, but where in reality, the operation has performed

synchronously. It allows the program to construct an operation object for which 

the operation is already completed, with the progress information and error code set.   

@publishedAll

@released

*/

	{

public:

	IMPORT_C static CMsvCompletedOperation* NewL(CMsvSession& aMsvSession, TUid aMtm, const TDesC8& aProgress, TMsvId aService, TRequestStatus& aObserverRequestStatus, TInt aErr=KErrNone);

	IMPORT_C ~CMsvCompletedOperation();

	//

	const TDesC8& ProgressL();

	const TDesC8& FinalProgress();

private:

	CMsvCompletedOperation(CMsvSession& aSession, TRequestStatus& aObserverRequestStatus);

	void ConstructL(TUid aMtm, TInt aError, const TDesC8& aProgress, TMsvId aService);

	// from CActive

	void DoCancel();

	void RunL();

	//

private:

	HBufC8* iProgress;

	};

//**********************************

// CMsvSendOperation

//**********************************

//

// A send operation which returns a standard progress (used by SendAs2)

//

/** Utility to create an operation containing a sending operation which may be used

to retrieve a standard progress structure.

This class is intended to be derived from. The derived class must define the TranslateProgress()

member function. This function is responsible for translating the native progress of the given

mtm into the standard progress structure, CMsvSendOperation::TSendOperationProgress.

@publishedAll

@released

*/

class CMsvSendOperation : public CMsvOperation

	{

public:

	/** Send progress state.

	@see TSendOperationProgress

	*/

	enum TSendOperationState

		{

		ESendStateInPreparation,

		ESendStateWaitingToSend,

		ESendStateConnecting,

		ESendStateSending,

		ESendStateDone,

		ESendStateFailed

		};

	/** Send progress.

	Structure holding send progress. For mtms unable to provide detailed progress 

	information, iProgressMax and iProgress must be zeroed. This will then allow

	the client to check for this case and display a busy status dialog as opposed to

	a progress dialog. If the mtm is capable of detailed progress, iProgressMax 

	should be set to the total number of units to be sent and iProgress the number

	of units sent.

	@see TSendOperationState

	*/

	class TSendOperationProgress

		{

	public:

		TSendOperationState iState;

		TInt 				iError;

		TInt 				iProgressMax;

		TInt 				iProgress;	

		};

public:

	IMPORT_C virtual ~CMsvSendOperation();

	// methods from CMsvOperation

	IMPORT_C virtual const TDesC8& ProgressL();

	IMPORT_C virtual const TDesC8& FinalProgress();

	IMPORT_C void Start(CMsvOperation* aOperation);

protected:

	IMPORT_C CMsvSendOperation(CMsvSession& aMsvSession, TRequestStatus& aObserverRequestStatus);

private:	// methods from CActive

	IMPORT_C virtual void DoCancel();

	IMPORT_C virtual void RunL();

private:

	/** Translates the progress from sending operation's progress into TSendOperationProgress. 

	This member function must be defined by derived classes. Must not leave.

	@see TSendOperationProgress 

	@return Descriptor holding progress information.

	*/

	virtual const TDesC8& TranslateProgress(const TDesC8& aProgress)=0;

	void Complete(TInt anError);

protected:

	/** The progress that is associated with this operation. 

	The TranslateProgress defined by derived classes must populate and return

	this progress structure.

	@see TranslateProgress() 

	@see TSendOperationProgress */

	TPckgBuf<TSendOperationProgress> iProgress;

	/** The sending operation. 

	Assigned when ConstructL is called

	*/

	CMsvOperation* iOperation;

	};

/** Package buffer for a TSendOperationProgress

*/

typedef TPckgBuf<CMsvSendOperation::TSendOperationProgress> TMsvSendOperationProgress;

//**********************************

// MMsvSessionObserver

//**********************************

//

// 

//

class MMsvSessionObserver

/** Provides the interface for notification of events from a Message Server session. 

The types of event are given in the enumeration TMsvSessionEvent. Clients 

must provide an object that implements the interface, and set it to be notified 

through CMsvSession::OpenSyncL() or CMsvSession::OpenASyncL(). Additional 

observers can also be added and removed through CMsvSession.

@see CMsvSession::AddObserverL()

@see CMsvSession::RemoveObserver() 

@publishedAll

@released

*/

	{

public:

	/** Session event type.

	@see EMsvMediaUnavailable

	@see TDriveNumber 

	*/

	enum TMsvSessionEvent 

							{ 

	/** One or more entries have been created.

	aArg1 is a CMsvEntrySelection of the new entries. aArg2 is the TMsvId of the 

	parent entry. */

							EMsvEntriesCreated,

	/** One or more index entries have been changed. 

	aArg1 is a CMsvEntrySelection of the index entries. aArg2 is the TMsvId of 

	the parent entry. */

							EMsvEntriesChanged,

	/** One or more entries have been deleted.

	aArg1 is a CMsvEntrySelection containing the IDs of the deleted entries. aArg2 

	is the TMsvId of the parent entry. */

							EMsvEntriesDeleted,

	/** One or more entries have been moved.

	aArg1 is a CMsvEntrySelection containing the IDs of the moved entries. aArg2 

	is the TMsvId of the new parent. aArg3 is the TMsvId of the old parent entry. */

							EMsvEntriesMoved,

	/** A new MTM has been installed. 

	aArg2 points to a TUid for the new MTM. */

							EMsvMtmGroupInstalled,

	/** A MTM has been uninstalled. 

	aArg2 points to a TUid of the removed MTM. */

							EMsvMtmGroupDeInstalled,

	/** Something has happening in the server, but this client was unable to retrieve 

	the information.

	aArg1 points to the error code. */

							EMsvGeneralError,

	/** The client should immediately close the session with the Message Server. */

							EMsvCloseSession,

	/** Received after a client has used CMsvSession::OpenAsyncL() to create a session. 

	The session can now be used. */

							EMsvServerReady,

	/** Received after a client has used CMsvSession::OpenAsyncL() to create a session. 

	The server could not be started, and aArg1 points to the error code. */

							EMsvServerFailedToStart,

	/** The Message Server index had been corrupted and had to be rebuilt. 

	All local entries are recovered, but all remote entries have been lost. */

							EMsvCorruptedIndexRebuilt,

	/** The Message Server has been terminated. 

	All clients must close their sessions immediately. */

							EMsvServerTerminated,

	/** This notification is sent whenever Message Server current drive is changed.

	Upon receiving this event, the client should delete the current context of operations 

	and refresh its view of messaging.

	aArg1 is a TDriveNumber value that identifies the drive used by the Message 

	Server to hold the index prior to the change. 

	aArg2 is also a TDriveNumber value; it identifies the new drive that the Message 

	Server is using.

	CMsvEntry contexts either refresh themselves or mark themselves invalid.

	@see EMsvMediaUnavailable

	@see TDriveNumber */

							EMsvMediaChanged, // I assume the following four are in sequential order

	/** The media (disk) containing the Message Server index has been removed. 

	aArg1 is a TDriveNumber value that identifies the drive that is no longer 

	available.

	Future requests may fail with KMsvMediaUnavailable. A EMsvMediaChanged event 

	may be received in the future, as the Message Server switches back to the 

	internal drive. */

							EMsvMediaUnavailable,

	/** The disk containing the Message Store is available again.

	aArg1 is a TDriveNumber value that identifies the drive that is being used.

	The Message Server can now operate as normal. No client action is necessary. */

							EMsvMediaAvailable,

	/** An incorrect disk is inserted. 

	aArg1 is a TDriveNumber value that identifies the drive in which the incorrect