williamr@2: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@2: // 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 williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: #ifdef _DEBUG williamr@2: #undef _NO_SESSION_LOGGING_ williamr@2: #endif williamr@2: williamr@2: #ifndef __MSVAPI_H__ williamr@2: #define __MSVAPI_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: williamr@2: #ifdef _MSVAPI_DONT_INCLUDE_FLOGGER_ williamr@2: #ifndef _NO_SESSION_LOGGING_ williamr@2: #define _NO_SESSION_LOGGING_ williamr@2: #endif williamr@2: #else williamr@2: #include williamr@2: #endif williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: // Forward declarations williamr@2: class CMsvSession; williamr@2: class CMsvEntry; williamr@2: class CBaseMtm; williamr@2: class CMsvClientEntry; williamr@2: class CMsvEntryArray; williamr@2: class CMsvServer; williamr@2: class CMsvServerEntry; williamr@2: williamr@2: // Remove these to remove client logging williamr@2: //#define _NO_SESSION_LOGGING_ williamr@2: #define _NO_SESSION_LOGGING_SERIAL_ williamr@2: williamr@2: // Single export used to start the message server williamr@2: IMPORT_C TInt StartMessageServer(TAny*); williamr@2: williamr@2: // Create Message Server and return a server entry owned by caller williamr@2: // This is all that is required to test server Mtm's williamr@2: IMPORT_C CServer2* CreateMessageServerL(CMsvServerEntry*& aServerEntry); williamr@2: williamr@2: //********************************** williamr@2: // CMsvOperation williamr@2: //********************************** williamr@2: // williamr@2: // Abstract base class for operations controlling asynchronous functions williamr@2: // williamr@2: williamr@2: class CMsvOperation : public CActive williamr@2: /** Defines an interface for use by objects which control asynchronous commands williamr@2: in the messaging system. williamr@2: williamr@2: Such objects are returned by CMsvEntry and User Interface MTM functions that williamr@2: complete asynchronously. The interface allows clients to: williamr@2: williamr@2: 1. get progress information about the operation williamr@2: williamr@2: 2. cancel the operation williamr@2: williamr@2: 3. be signalled asynchronously when the operation completes; a client passes williamr@2: in a TRequestStatus of a suitable active object for this purpose williamr@2: williamr@2: The client only needs to understand the CMsvOperation interface, not the concrete williamr@2: implementation used. williamr@2: williamr@2: Writing derived classes: williamr@2: williamr@2: As the base class interface for User Interface MTMs, CBaseUiMtm, defines functions williamr@2: that return CMsvOperation objects for control of asynchronous operations, williamr@2: implementers of these MTM components are required to provide suitable derived williamr@2: classes. For example, if CBaseUiMtm::EditL() is implemented to provide message williamr@2: editing, a CMsvOperation -derived class would be provided that completes when williamr@2: the editing operation is complete. williamr@2: williamr@2: Concrete derived classes must provide implementations of the pure virtual williamr@2: DoCancel() and RunL() functions defined by CActive. DoCancel() should be provided williamr@2: in the normal way to cancel the operation. RunL() should, in addition to any williamr@2: other required functionality, always end by signalling the client that the williamr@2: operation is complete with a suitable completion code. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C CMsvOperation(CMsvSession& aMsvSession, TInt aPriority, TRequestStatus& aObserverRequestStatus); williamr@2: IMPORT_C ~CMsvOperation(); williamr@2: /** Gets information on the progress of the operation. williamr@2: williamr@2: All operations on local entries share the same progress information format, williamr@2: which defined by TMsvLocalOperationProgress. williamr@2: williamr@2: For MTM-specific operations, progress information can be extracted by calling williamr@2: CBaseUiMtm::GetProgress() or displayed by CBaseUiMtm::DisplayProgressSummary() williamr@2: on the appropriate User Interface MTM. williamr@2: williamr@2: Requirements: williamr@2: williamr@2: Derived classes should implement this function so that the client can check williamr@2: on the progress of the operation. The function should share an understanding williamr@2: of the format of the buffer with the implementations of CBaseUiMtm::GetProgress() williamr@2: and CBaseUiMtm::DisplayProgressSummary() in the User Interface MTM. The arguments williamr@2: of CBaseUiMtm::GetProgress() show some information that should be included williamr@2: where appropriate. williamr@2: williamr@2: @leave KErrNotReady The operation has not yet been started: it has been queued williamr@2: for execution in the Message Server williamr@2: @return Descriptor holding progress information. The maximum buffer size should williamr@2: be KMsvProgressBufferLength (defined in msvipc.h). */ williamr@2: virtual const TDesC8& ProgressL()=0; williamr@2: IMPORT_C virtual const TDesC8& FinalProgress(); williamr@2: IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg); williamr@2: IMPORT_C virtual TUid Mtm() const; williamr@2: // williamr@2: inline TMsvOp Id() const; williamr@2: inline TMsvId Service() const; williamr@2: // williamr@2: protected: williamr@2: IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1); williamr@2: williamr@2: protected: williamr@2: /** The ID of the service that is associated with this operation. williamr@2: williamr@2: Usually, the derived class constructor will contain a suitable argument to williamr@2: allow the caller to set this. williamr@2: williamr@2: @see Service() */ williamr@2: TMsvId iService; williamr@2: /** The UID of the MTM associated with the operation. williamr@2: williamr@2: The appropriate value should be set by the derived class constructor. williamr@2: williamr@2: @see Mtm() */ williamr@2: TUid iMtm; williamr@2: /** Request status of the operation observer. williamr@2: williamr@2: This is the aObserverRequestStatus passed in the constructor. */ williamr@2: TRequestStatus& iObserverRequestStatus; williamr@2: /** Message Server session used by object. This is set by the constructor. */ williamr@2: CMsvSession& iMsvSession; williamr@2: williamr@2: private: williamr@2: TMsvOp iId; williamr@2: }; williamr@2: williamr@2: williamr@2: //********************************** williamr@2: // CMsvOperationWait williamr@2: //********************************** williamr@2: // williamr@2: // Allows a synchronous wait on a operation williamr@2: // williamr@2: williamr@2: class CMsvOperationWait: public CActive williamr@2: /** Utility class used to wait until an asynchronous messaging operation williamr@2: has completed. williamr@2: williamr@2: Note that CMsvOperationActiveSchedulerWait is simpler to use, and should be used in williamr@2: preference to this class. williamr@2: williamr@2: To use the class: williamr@2: williamr@2: 1. Create a new CMsvOperationWait object williamr@2: williamr@2: 2. Call the messaging function that returns the asynchronous operation. williamr@2: The operation observer parameter should be the iStatus word of the CMsvOperationWait williamr@2: object. This means that the CMsvOperationWait object will be signalled when williamr@2: the operation completes. williamr@2: williamr@2: 3. Call the CMsvOperationWait object's Start() function. This sets the object williamr@2: to be active. williamr@2: williamr@2: 4. Call CActiveScheduler::Start(). This starts a nested active scheduler. The williamr@2: program will then wait until this active scheduler is stopped. The CMsvOperationWait williamr@2: object stops the scheduler when the operation completes, allowing the program to williamr@2: continue. williamr@2: williamr@2: These steps cause the program to wait until the operation completes. williamr@2: williamr@2: @code williamr@2: CMsvOperationWait* waiter=CMsvOperationWait::NewLC(); williamr@2: CMsvOperation* op = function_returning_opLC(waiter->iStatus); williamr@2: waiter->Start(); williamr@2: CActiveScheduler::Start(); williamr@2: CleanupStack::PopAndDestroy(2); // op, waiter williamr@2: @endcode williamr@2: williamr@2: @see CActiveScheduler williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CMsvOperationWait* NewLC(TInt aPriority=EPriorityStandard); williamr@2: IMPORT_C ~CMsvOperationWait(); williamr@2: IMPORT_C void Start(); williamr@2: protected: williamr@2: CMsvOperationWait(TInt aPriority); williamr@2: void RunL(); williamr@2: void DoCancel(); williamr@2: }; williamr@2: williamr@2: williamr@2: //********************************** williamr@2: // CMsvOperationActiveSchedulerWait williamr@2: //********************************** williamr@2: // williamr@2: // Allows a synchronous wait on a operation using CActiveSchedulerWait class williamr@2: // This class should be used in preference to CMsvOperationWait williamr@2: // DOES NOT require an explicit call to CActiveScheduler::Start()--CMsvOperationActiveSchedulerWait::Start() williamr@2: // effectively encapsulates this functionality williamr@2: // williamr@2: williamr@2: class CMsvOperationActiveSchedulerWait: public CActive williamr@2: /** Utility class used to wait until an asynchronous messaging operation williamr@2: has completed. williamr@2: williamr@2: To use the class: williamr@2: williamr@2: 1. Create a new CMsvOperationActiveSchedulerWait object williamr@2: williamr@2: 2. Call the messaging function that returns the asynchronous operation. williamr@2: The operation observer parameter should be the iStatus word of the CMsvOperationActiveSchedulerWait williamr@2: object. This means that the CMsvOperationActiveSchedulerWait object will be signalled when williamr@2: the operation completes. williamr@2: williamr@2: 3. Call the CMsvOperationActiveSchedulerWait object's Start() function. This sets the object williamr@2: to be active. williamr@2: williamr@2: These steps cause the program to wait until the operation completes. williamr@2: williamr@2: @code williamr@2: CMsvOperationActiveSchedulerWait* waiter=CMsvOperationActiveSchedulerWait::NewLC(); williamr@2: CMsvOperation* op = function_returning_opLC(waiter->iStatus); williamr@2: waiter->Start(); williamr@2: williamr@2: CleanupStack::PopAndDestroy(2); // op, waiter williamr@2: @endcode williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CMsvOperationActiveSchedulerWait* NewLC(TInt aPriority=EPriorityStandard); williamr@2: IMPORT_C ~CMsvOperationActiveSchedulerWait(); williamr@2: IMPORT_C void Start(); williamr@2: private: williamr@2: CMsvOperationActiveSchedulerWait(TInt aPriority); williamr@2: void RunL(); williamr@2: void DoCancel(); williamr@2: private: williamr@2: CActiveSchedulerWait iActiveSchedulerWait; williamr@2: }; williamr@2: williamr@2: //********************************** williamr@2: // CMsvCompletedOperation williamr@2: //********************************** williamr@2: // williamr@2: // An operation which is already completed on construction williamr@2: // williamr@2: williamr@2: class CMsvCompletedOperation : public CMsvOperation williamr@2: /** Utility to create a messaging operation object for an operation that has already williamr@2: completed. williamr@2: williamr@2: This utility is useful, for example, for writers of MTMs, where the API requires that an williamr@2: asynchronous operation is returned, but where in reality, the operation has performed williamr@2: synchronously. It allows the program to construct an operation object for which williamr@2: the operation is already completed, with the progress information and error code set. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CMsvCompletedOperation* NewL(CMsvSession& aMsvSession, TUid aMtm, const TDesC8& aProgress, TMsvId aService, TRequestStatus& aObserverRequestStatus, TInt aErr=KErrNone); williamr@2: IMPORT_C ~CMsvCompletedOperation(); williamr@2: // williamr@2: const TDesC8& ProgressL(); williamr@2: const TDesC8& FinalProgress(); williamr@2: private: williamr@2: CMsvCompletedOperation(CMsvSession& aSession, TRequestStatus& aObserverRequestStatus); williamr@2: void ConstructL(TUid aMtm, TInt aError, const TDesC8& aProgress, TMsvId aService); williamr@2: // from CActive williamr@2: void DoCancel(); williamr@2: void RunL(); williamr@2: // williamr@2: private: williamr@2: HBufC8* iProgress; williamr@2: }; williamr@2: williamr@2: //********************************** williamr@2: // CMsvSendOperation williamr@2: //********************************** williamr@2: // williamr@2: // A send operation which returns a standard progress (used by SendAs2) williamr@2: // williamr@2: williamr@2: /** Utility to create an operation containing a sending operation which may be used williamr@2: to retrieve a standard progress structure. williamr@2: williamr@2: This class is intended to be derived from. The derived class must define the TranslateProgress() williamr@2: member function. This function is responsible for translating the native progress of the given williamr@2: mtm into the standard progress structure, CMsvSendOperation::TSendOperationProgress. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CMsvSendOperation : public CMsvOperation williamr@2: { williamr@2: public: williamr@2: /** Send progress state. williamr@2: williamr@2: @see TSendOperationProgress williamr@2: */ williamr@2: enum TSendOperationState williamr@2: { williamr@2: ESendStateInPreparation, williamr@2: ESendStateWaitingToSend, williamr@2: ESendStateConnecting, williamr@2: ESendStateSending, williamr@2: ESendStateDone, williamr@2: ESendStateFailed williamr@2: }; williamr@2: /** Send progress. williamr@2: williamr@2: Structure holding send progress. For mtms unable to provide detailed progress williamr@2: information, iProgressMax and iProgress must be zeroed. This will then allow williamr@2: the client to check for this case and display a busy status dialog as opposed to williamr@2: a progress dialog. If the mtm is capable of detailed progress, iProgressMax williamr@2: should be set to the total number of units to be sent and iProgress the number williamr@2: of units sent. williamr@2: williamr@2: @see TSendOperationState williamr@2: */ williamr@2: class TSendOperationProgress williamr@2: { williamr@2: public: williamr@2: TSendOperationState iState; williamr@2: TInt iError; williamr@2: TInt iProgressMax; williamr@2: TInt iProgress; williamr@2: }; williamr@2: williamr@2: public: williamr@2: IMPORT_C virtual ~CMsvSendOperation(); williamr@2: // methods from CMsvOperation williamr@2: IMPORT_C virtual const TDesC8& ProgressL(); williamr@2: IMPORT_C virtual const TDesC8& FinalProgress(); williamr@2: IMPORT_C void Start(CMsvOperation* aOperation); williamr@2: protected: williamr@2: IMPORT_C CMsvSendOperation(CMsvSession& aMsvSession, TRequestStatus& aObserverRequestStatus); williamr@2: private: // methods from CActive williamr@2: IMPORT_C virtual void DoCancel(); williamr@2: IMPORT_C virtual void RunL(); williamr@2: private: williamr@2: /** Translates the progress from sending operation's progress into TSendOperationProgress. williamr@2: williamr@2: This member function must be defined by derived classes. Must not leave. williamr@2: @see TSendOperationProgress williamr@2: @return Descriptor holding progress information. williamr@2: */ williamr@2: virtual const TDesC8& TranslateProgress(const TDesC8& aProgress)=0; williamr@2: void Complete(TInt anError); williamr@2: protected: williamr@2: /** The progress that is associated with this operation. williamr@2: williamr@2: The TranslateProgress defined by derived classes must populate and return williamr@2: this progress structure. williamr@2: @see TranslateProgress() williamr@2: @see TSendOperationProgress */ williamr@2: TPckgBuf iProgress; williamr@2: /** The sending operation. williamr@2: williamr@2: Assigned when ConstructL is called williamr@2: */ williamr@2: CMsvOperation* iOperation; williamr@2: }; williamr@2: williamr@2: /** Package buffer for a TSendOperationProgress williamr@2: */ williamr@2: typedef TPckgBuf TMsvSendOperationProgress; williamr@2: williamr@2: williamr@2: //********************************** williamr@2: // MMsvSessionObserver williamr@2: //********************************** williamr@2: // williamr@2: // williamr@2: // williamr@2: williamr@2: class MMsvSessionObserver williamr@2: /** Provides the interface for notification of events from a Message Server session. williamr@2: williamr@2: williamr@2: The types of event are given in the enumeration TMsvSessionEvent. Clients williamr@2: must provide an object that implements the interface, and set it to be notified williamr@2: through CMsvSession::OpenSyncL() or CMsvSession::OpenASyncL(). Additional williamr@2: observers can also be added and removed through CMsvSession. williamr@2: williamr@2: @see CMsvSession::AddObserverL() williamr@2: @see CMsvSession::RemoveObserver() williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: /** Session event type. williamr@2: williamr@2: @see EMsvMediaUnavailable williamr@2: @see TDriveNumber williamr@2: */ williamr@2: enum TMsvSessionEvent williamr@2: { williamr@2: /** One or more entries have been created. williamr@2: williamr@2: aArg1 is a CMsvEntrySelection of the new entries. aArg2 is the TMsvId of the williamr@2: parent entry. */ williamr@2: EMsvEntriesCreated, williamr@2: /** One or more index entries have been changed. williamr@2: williamr@2: aArg1 is a CMsvEntrySelection of the index entries. aArg2 is the TMsvId of williamr@2: the parent entry. */ williamr@2: EMsvEntriesChanged, williamr@2: /** One or more entries have been deleted. williamr@2: williamr@2: aArg1 is a CMsvEntrySelection containing the IDs of the deleted entries. aArg2 williamr@2: is the TMsvId of the parent entry. */ williamr@2: EMsvEntriesDeleted, williamr@2: /** One or more entries have been moved. williamr@2: williamr@2: aArg1 is a CMsvEntrySelection containing the IDs of the moved entries. aArg2 williamr@2: is the TMsvId of the new parent. aArg3 is the TMsvId of the old parent entry. */ williamr@2: EMsvEntriesMoved, williamr@2: /** A new MTM has been installed. williamr@2: williamr@2: aArg2 points to a TUid for the new MTM. */ williamr@2: EMsvMtmGroupInstalled, williamr@2: /** A MTM has been uninstalled. williamr@2: williamr@2: aArg2 points to a TUid of the removed MTM. */ williamr@2: EMsvMtmGroupDeInstalled, williamr@2: /** Something has happening in the server, but this client was unable to retrieve williamr@2: the information. williamr@2: williamr@2: aArg1 points to the error code. */ williamr@2: EMsvGeneralError, williamr@2: /** The client should immediately close the session with the Message Server. */ williamr@2: EMsvCloseSession, williamr@2: /** Received after a client has used CMsvSession::OpenAsyncL() to create a session. williamr@2: williamr@2: williamr@2: The session can now be used. */ williamr@2: EMsvServerReady, williamr@2: /** Received after a client has used CMsvSession::OpenAsyncL() to create a session. williamr@2: williamr@2: williamr@2: The server could not be started, and aArg1 points to the error code. */ williamr@2: EMsvServerFailedToStart, williamr@2: /** The Message Server index had been corrupted and had to be rebuilt. williamr@2: williamr@2: All local entries are recovered, but all remote entries have been lost. */ williamr@2: EMsvCorruptedIndexRebuilt, williamr@2: /** The Message Server has been terminated. williamr@2: williamr@2: All clients must close their sessions immediately. */ williamr@2: EMsvServerTerminated, williamr@2: /** The Message Server has automatically changed the index location to use the williamr@2: internal disk. williamr@2: williamr@2: aArg1 is a TDriveNumber value that identifies the drive used by the Message williamr@2: Server to hold the index prior to the change. williamr@2: williamr@2: aArg2 is also a TDriveNumber value; it identifies the new drive that the Message williamr@2: Server is using. williamr@2: williamr@2: CMsvEntry contexts either refresh themselves or mark themselves invalid. williamr@2: williamr@2: @see EMsvMediaUnavailable williamr@2: @see TDriveNumber */ williamr@2: EMsvMediaChanged, // I assume the following four are in sequential order williamr@2: /** The media (disk) containing the Message Server index has been removed. williamr@2: williamr@2: aArg1 is a TDriveNumber value that identifies the drive that is no longer williamr@2: available. williamr@2: williamr@2: Future requests may fail with KMsvMediaUnavailable. A EMsvMediaChanged event williamr@2: may be received in the future, as the Message Server switches back to the williamr@2: internal drive. */ williamr@2: EMsvMediaUnavailable, williamr@2: /** The disk containing the Message Store is available again. williamr@2: williamr@2: aArg1 is a TDriveNumber value that identifies the drive that is being used. williamr@2: williamr@2: The Message Server can now operate as normal. No client action is necessary. */ williamr@2: EMsvMediaAvailable, williamr@2: /** An incorrect disk is inserted. williamr@2: williamr@2: aArg1 is a TDriveNumber value that identifies the drive in which the incorrect williamr@2: disk has been inserted. williamr@2: williamr@2: Some requests may fail with KMsvMediaIncorrect. Clients may get an EMsvMediaChanged williamr@2: event in the future telling them that the Message Server has switched back williamr@2: to the internal drive. */ williamr@2: EMsvMediaIncorrect, williamr@2: /** The Message Server has started to rebuild its index after it has been corrupted. williamr@2: williamr@2: @see EMsvCorruptedIndexRebuilt */ williamr@2: EMsvCorruptedIndexRebuilding williamr@2: }; williamr@2: public: williamr@2: /** Indicates an event has occurred. williamr@2: williamr@2: The type of event is indicated by the value of aEvent. The interpretation williamr@2: of the TAny arguments depends on this type. williamr@2: williamr@2: For most event types, the action that is taken, for example, updating the williamr@2: display, is client-specific. All clients though should respond to EMsvCloseSession williamr@2: and EMsvServerTerminated events. williamr@2: williamr@2: @param aEvent Indicates the event type. williamr@2: @param aArg1 Event type-specific argument value williamr@2: @param aArg2 Event type-specific argument value williamr@2: @param aArg3 Event type-specific argument value */ williamr@2: virtual void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0; williamr@2: }; williamr@2: williamr@2: //********************************** williamr@2: // CMsvSession williamr@2: //********************************** williamr@2: // williamr@2: // williamr@2: // williamr@2: williamr@2: class TCapabilitySet; williamr@2: williamr@2: const TInt KMsvSessionObserverGranularity=4; //??? williamr@2: williamr@2: class CMsvSession: public CActive williamr@2: /** Represents a channel of communication between a client thread (Client-side williamr@2: MTM, User Interface MTM, or message client application) and the Message Server williamr@2: thread. williamr@2: williamr@2: The class provides the means by which clients are notified when important williamr@2: Message Server events occur. williamr@2: williamr@2: Note the following significant groups of functions: williamr@2: williamr@2: Creation functions: a message client application must use OpenSyncL() or OpenASyncL() williamr@2: to create a session object, before it can instantiate any MTM or CMsvEntry williamr@2: object. Only a single session should be created within a thread. As Client-side williamr@2: MTM, User Interface MTM, and CMsvEntry objects are created in the client thread, williamr@2: these use the client session, and do not create their own. Note that to close williamr@2: a session, delete all objects relying on that session, and then the session williamr@2: object itself. williamr@2: williamr@2: Cleanup functions: CMsvSession provides the ability to handle the cleanup williamr@2: of entries in the event of a leave occurring, in a very similar manner to williamr@2: the standard cleanup stack. The difference is that, on a leave, any entries williamr@2: that are on the entry cleanup stack are removed from the Message Server. The williamr@2: implementation uses the standard cleanup stack, so entry push and pop functions williamr@2: should be used in the same order as all other types of push and pop. The functions williamr@2: can be used both by MTM implementations and message client applications. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver); williamr@2: IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver); williamr@2: IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver); williamr@2: williamr@2: IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, RFs& aFs); williamr@2: IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, RFs& aFs); williamr@2: IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, RFs& aFs); williamr@2: williamr@2: IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, TInt aPriority); williamr@2: IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, TInt aPriority); williamr@2: IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, TInt aPriority); williamr@2: williamr@2: IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); williamr@2: IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); williamr@2: IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); williamr@2: williamr@2: ~CMsvSession(); williamr@2: // --- Observer functions --- williamr@2: IMPORT_C void AddObserverL(MMsvSessionObserver& aObserver); williamr@2: IMPORT_C void RemoveObserver(MMsvSessionObserver& aObserver); williamr@2: IMPORT_C TInt SetReceiveEntryEvents(TBool aReceive); williamr@2: // --- Utility functions --- williamr@2: IMPORT_C CMsvEntry* GetEntryL(TMsvId aEntId); williamr@2: IMPORT_C TInt GetEntry(TMsvId aId, TMsvId& aService, TMsvEntry& aEntry); williamr@2: williamr@2: IMPORT_C CMsvOperation* TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TRequestStatus& aStatus); williamr@2: IMPORT_C void TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TDes8& aProgress); williamr@2: IMPORT_C void IncPcSyncCountL(const CMsvEntrySelection& aSelection); williamr@2: IMPORT_C void DecPcSyncCountL(const CMsvEntrySelection& aSelection); williamr@2: IMPORT_C void GetChildIdsL(TMsvId aId, const CMsvEntryFilter& aFilter, CMsvEntrySelection& aSelection); williamr@2: IMPORT_C void ChangeAttributesL(const CMsvEntrySelection& aSelection, TUint aSetAttributes, TUint aClearAttributes); williamr@2: IMPORT_C CMsvOperation* ChangeDriveL(TInt aDrive, TRequestStatus& aStatus); williamr@2: IMPORT_C TInt OutstandingOperationsL(); williamr@2: IMPORT_C CMsvOperation* CopyStoreL(const TDriveUnit& aDrive, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* DeleteStoreL(const TDriveUnit& aDrive, TRequestStatus& aStatus); williamr@2: // --- cleanup functions williamr@2: IMPORT_C static void CleanupEntry(TAny* aPtr); williamr@2: IMPORT_C void CleanupEntryPushL(TMsvId aId); williamr@2: IMPORT_C void CleanupEntryPop(TInt aCount=1); williamr@2: williamr@2: IMPORT_C void RemoveEntry(TMsvId aId); williamr@2: /// MTM functions williamr@2: IMPORT_C TInt InstallMtmGroup(const TDesC& aFullName); williamr@2: IMPORT_C TInt DeInstallMtmGroup(const TDesC& aFullName); williamr@2: williamr@2: IMPORT_C TInt StopService(TMsvId aServiceId); williamr@2: IMPORT_C TBool ServiceActive(TMsvId aServiceId); williamr@2: IMPORT_C TInt ServiceProgress(TMsvId aServiceId, TDes8& aProgress); williamr@2: williamr@2: IMPORT_C void CloseMessageServer(); williamr@2: IMPORT_C RFs& FileSession(); williamr@2: williamr@2: IMPORT_C void GetMtmRequiredCapabilitiesL(TUid aMtmTypeUid, TCapabilitySet& aCapSet) const; williamr@2: MMsvStoreManager& StoreManager(); williamr@2: williamr@2: IMPORT_C TBool GetAndClearIndexCorruptFlagL(); williamr@2: IMPORT_C TDriveUnit CurrentDriveL(); williamr@2: IMPORT_C TBool DriveContainsStoreL(TDriveUnit aDrive); williamr@2: IMPORT_C TBool MessageStoreDrivePresentL(); williamr@2: williamr@2: IMPORT_C TInt ServiceAccessPointId(TMsvId aServiceId, TUint32& aAccessPointId); williamr@2: williamr@2: protected: williamr@2: CMsvSession(MMsvSessionObserver& aObserver); williamr@2: CMsvSession(MMsvSessionObserver& aObserver, RFs& aFs); williamr@2: CMsvSession(MMsvSessionObserver& aObserver, TInt aPriority); williamr@2: CMsvSession(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority); williamr@2: williamr@2: void ConstructL(TBool aSyncOpening); williamr@2: void ConstructAsObserverL(); williamr@2: // williamr@2: IMPORT_C TInt OperationId(); williamr@2: IMPORT_C RMsvServerSession& Session(); williamr@2: williamr@2: void CheckDrive(); williamr@2: // williamr@2: // from CActive williamr@2: void RunL(); williamr@2: void DoCancel(); williamr@2: TInt RunError(TInt aError); williamr@2: // williamr@2: private: williamr@2: void NotifyAllObserversL(MMsvSessionObserver::TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); williamr@2: void CleanupEntryDelete(); williamr@2: void DoRunL(TMsvNotifBuffer& aBuffer); williamr@2: void HandleNotifyL(); williamr@2: void DoHandleNotifyL(TMsvNotifBuffer& aBuffer); williamr@2: void GetMessageFolderL(); williamr@2: // williamr@2: private: williamr@2: TInt iOperationId; williamr@2: RFs iFs; williamr@2: RMsvServerSession iSession; williamr@2: TMsvNotifBuffer iChange; williamr@2: MMsvSessionObserver& iMainObserver; williamr@2: CArrayPtrFlat* iObservers; williamr@2: CMsvEntrySelection* iCleanupList; williamr@2: TInt iSyncStart; williamr@2: HBufC* iMessageFolder; williamr@2: TDriveNumber iDrive; williamr@2: CMsvEntrySelection* iNotifSelection; williamr@2: TPckgBuf iSequenceBuf; williamr@2: TUint32 iNotifySequence; williamr@2: TBool iReceiveEntryEvents; williamr@2: /** Specifies whether to use the shared file server session */ williamr@2: TBool iUseSharedFs; williamr@2: // williamr@2: #ifndef _NO_SESSION_LOGGING_ williamr@2: void CreateSessionLogL(); williamr@2: void Log(TRefByValue aFmt, ...); williamr@2: williamr@2: // must be the last data member in the class to preserve BC. williamr@2: mutable RFileLogger iLog; williamr@2: #endif williamr@2: // williamr@2: friend class CSendAs; williamr@2: friend class CMsvEntry; williamr@2: friend class CMsvOperation; williamr@2: friend class CMsvEntryOperation; williamr@2: friend class CObserverRegistry; williamr@2: // williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: williamr@2: //********************************** williamr@2: // MMsvEntryObserver williamr@2: //********************************** williamr@2: // williamr@2: // williamr@2: // williamr@2: williamr@2: class MMsvEntryObserver williamr@2: /** Provides the interface for notification of events associated with an entry. williamr@2: williamr@2: The types of event are given in the enumeration TMsvEntryEvent. Clients can williamr@2: provide an object that implements the interface, and set it to be notified williamr@2: through CMsvEntry::AddObserverL(). williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: /** Defines entry event types. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TMsvEntryEvent williamr@2: { williamr@2: /** The entry has been changed, either as a result of a CMsvEntry::ChangeL() or williamr@2: by another client. */ williamr@2: EMsvEntryChanged, williamr@2: /** New children have been created. aArg1 points to a CMsvEntrySelection contain williamr@2: the ID of the new children. */ williamr@2: EMsvNewChildren, williamr@2: /** Children have been deleted. aArg1 points to a CMsvEntrySelection contain the williamr@2: ID of the deleted children. */ williamr@2: EMsvDeletedChildren, williamr@2: /** One or more of the children have been changed. aArg1 points to a CMsvEntrySelection williamr@2: containing the IDs of the changed children. */ williamr@2: EMsvChildrenChanged, williamr@2: /** The entry has been deleted by another client. The context is now invalid. */ williamr@2: EMsvEntryDeleted, williamr@2: /** The context has become invalid. The entry has been changed, but the CMsvEntry williamr@2: was unable to update the context. The context will only become valid by a williamr@2: successful CMsvEntry::SetEntryL() call. aArg1 points to a TInt containing williamr@2: the error code for the invalid context. */ williamr@2: EMsvContextInvalid, williamr@2: /** Some new children have been created, but CMsvEntry was unable to retrieve the williamr@2: data from the Message Server. The children will be correct only after a successful williamr@2: call to CMsvEntry::SetEntryL(). */ williamr@2: EMsvChildrenMissing, williamr@2: /** An error has occurred such that the status of the children is unknown and probably williamr@2: invalid. aArg1 points to a TInt containing the error code for the invalid williamr@2: context */ williamr@2: EMsvChildrenInvalid, williamr@2: /** The current entry has been moved by another client. The CMsvEntry has already williamr@2: been updated to reflect the new parent. */ williamr@2: EMsvEntryMoved}; williamr@2: public: williamr@2: /** Indicates when called by a CMsvEntry object that an event has occurred. williamr@2: williamr@2: The type of event is indicated by the value of aEvent. The interpretation of the aArg1-3 values depends on this type. williamr@2: For most event types, the action that is taken, for example, updating the display, is client-specific. Most clients will williamr@2: need to handle events that make the current context invalid: EMsvContextInvalid and EMsvEntryDeleted. williamr@2: williamr@2: An implementation can leave if an error occurs. The leave is not trapped by the framework, so williamr@2: the error code may be displayed to the user. williamr@2: williamr@2: @param aEvent Indicates the event type. williamr@2: @param aArg1 Event-specific argument value williamr@2: @param aArg2 Event-specific argument value williamr@2: @param aArg3 Event-specific argument value williamr@2: */ williamr@2: virtual void HandleEntryEventL(TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: //********************************** williamr@2: // CMsvEntry williamr@2: //********************************** williamr@2: // williamr@2: // williamr@2: // williamr@2: williamr@2: class CMsvEntry: public CBase, public MMsvSessionObserver, public MMsvStoreObserver williamr@2: /** Accesses and acts upon a particular Message Server entry. The current entry williamr@2: that a CMsvEntry object relates is referred to as its context. williamr@2: williamr@2: It may be helpful to consider CMsvEntry functions in two broad groups. The williamr@2: first provides means to access the various types of storage associated with williamr@2: an entry. The second provides a means to discover and access other entries williamr@2: that the entry owns (its children). williamr@2: williamr@2: Message client applications, Client-side MTMs, and User Interface MTMs all williamr@2: commonly use CMsvEntry objects. CMsvEntry objects though represent a lower williamr@2: level of access to an entry than that provided by a Client-side MTM or User williamr@2: Interface MTM. In particular, any MTM-specific functionality, such as address williamr@2: lists or subject fields, must be accessed by a message client application williamr@2: through an MTM inteface. williamr@2: williamr@2: A CMsvEntry object is relatively expensive in RAM usage, as it caches its williamr@2: children, updating them as necessary when notified of changes. They should williamr@2: therefore be created sparingly. williamr@2: williamr@2: Note that Server-side MTMs do not use this class, but a similar one, CMsvServerEntry. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: // Public member functions williamr@2: IMPORT_C static CMsvEntry* NewL(CMsvSession& aMsvSession, TMsvId aMsvId, const TMsvSelectionOrdering& aOrdering); williamr@2: IMPORT_C ~CMsvEntry(); williamr@2: // williamr@2: // --- Observer functions --- williamr@2: IMPORT_C void AddObserverL(MMsvEntryObserver& aObserver); williamr@2: IMPORT_C void RemoveObserver(MMsvEntryObserver& aObserver); williamr@2: // williamr@2: // --- Accessor for associated session --- williamr@2: inline CMsvSession& Session(); williamr@2: // williamr@2: // --- Accessors the associated message store --- williamr@2: IMPORT_C CMsvStore* ReadStoreL(); williamr@2: IMPORT_C CMsvStore* EditStoreL(); williamr@2: // williamr@2: // --- Synchronous Current Entry functions --- williamr@2: inline TMsvId EntryId() const; williamr@2: inline const TMsvEntry& Entry() const; williamr@2: inline const TMsvSelectionOrdering& SortType() const; williamr@2: inline TMsvId OwningService() const; williamr@2: IMPORT_C void SetSortTypeL(const TMsvSelectionOrdering& aOrdering); williamr@2: IMPORT_C void SetMtmListL(const CArrayFix& aMtmList); williamr@2: IMPORT_C void SetEntryL(TMsvId aId); williamr@2: IMPORT_C void ChangeL(const TMsvEntry& aEntry); williamr@2: IMPORT_C void ChangeL(const TMsvEntry& aEntry, TSecureId aOwnerId); williamr@2: williamr@2: williamr@2: // williamr@2: // --- Asynchronous Current Entry functions --- williamr@2: IMPORT_C CMsvOperation* ChangeL(const TMsvEntry& aEntry, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* ChangeL(const TMsvEntry& aEntry, TSecureId aOwnerId, TRequestStatus& aStatus); williamr@2: // williamr@2: // --- Asynchronous Child Entry functions --- williamr@2: IMPORT_C CMsvOperation* CreateL(const TMsvEntry& aEntry, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* CreateL(const TMsvEntry& aEntry, TSecureId aOwnerId, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* DeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* DeleteL(TMsvId aMsvId, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* CopyL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus); williamr@2: IMPORT_C CMsvOperation* MoveL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus); williamr@2: // williamr@2: // --- Synchronous Child Entry functions --- williamr@2: IMPORT_C CMsvEntrySelection* ChildrenL() const; williamr@2: IMPORT_C CMsvEntrySelection* ChildrenWithServiceL(TMsvId aServiceId) const; williamr@2: IMPORT_C CMsvEntrySelection* ChildrenWithMtmL(TUid aMtm) const; williamr@2: IMPORT_C CMsvEntrySelection* ChildrenWithTypeL(TUid aType) const; williamr@2: inline TInt Count() const; williamr@2: IMPORT_C const TMsvEntry& ChildDataL(TMsvId aId) const; williamr@2: IMPORT_C const TMsvEntry& operator[](TInt aIndex) const; williamr@2: IMPORT_C CMsvEntry* ChildEntryL(TMsvId aId) const; williamr@2: IMPORT_C void MoveL(TMsvId aMsvId, TMsvId aTargetId); williamr@2: IMPORT_C void MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TMsvLocalOperationProgress& aProgress); williamr@2: IMPORT_C void CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TMsvLocalOperationProgress& aProgress); williamr@2: IMPORT_C void CopyL(TMsvId aMsvId, TMsvId aTargetId); williamr@2: williamr@2: williamr@2: IMPORT_C void CreateL(TMsvEntry& aEntry); williamr@2: IMPORT_C void CreateL(TMsvEntry& aEntry, TSecureId aOwnerId); williamr@2: IMPORT_C void DeleteL(TMsvId aId); williamr@2: IMPORT_C void DeleteL(const CMsvEntrySelection& aSelection, TMsvLocalOperationProgress& aProgress); williamr@2: IMPORT_C void ChangeAttributesL(const CMsvEntrySelection& aSelection, TUint aSetAttributes, TUint aClearAttributes); williamr@2: // williamr@2: // from MMsvSessionObserver williamr@2: void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); williamr@2: // From MMsvStoreObserver williamr@2: void HandleStoreEvent(TMsvStoreEvent aEvent, TMsvId aId); williamr@2: williamr@2: williamr@2: IMPORT_C TBool HasStoreL() const; williamr@2: // williamr@2: /** @internalTechnology */ williamr@2: IMPORT_C void SetEntryNoCheckL(TMsvId aId); williamr@2: // williamr@2: private: // Private members williamr@2: CMsvEntry(CMsvSession& aMsvSession, const TMsvSelectionOrdering& aOrdering); williamr@2: void ConstructL(TMsvId aMsvId); williamr@2: // williamr@2: void NotifyAllObserversL(MMsvEntryObserver::TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3); williamr@2: void ContextChangedL(MMsvEntryObserver::TMsvEntryEvent aEvent); williamr@2: void NewChildrenL(const CMsvEntrySelection& aSelection); williamr@2: CMsvEntrySelection* DoGetNewChildrenL(const CMsvEntrySelection& aSelection); williamr@2: void DeletedChildrenL(const CMsvEntrySelection& aSelection); williamr@2: void ChildrenChangedL(const CMsvEntrySelection& aSelection); williamr@2: void CheckNewGrandchildrenL(TMsvId aId); williamr@2: void CheckDeletedGrandchildrenL(TMsvId aId); williamr@2: void NotifyChildChangedL(TMsvId aId); williamr@2: CMsvEntrySelection* DoMakeSelectionL(TMsvId aId); williamr@2: void CheckIfContextMovedL(const CMsvEntrySelection& aSelection); williamr@2: // williamr@2: TBool IsAChild(TMsvId aId) const; williamr@2: TBool AreChildren(const CMsvEntrySelection& aSelection) const; williamr@2: // williamr@2: CMsvOperation* DoDeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus); williamr@2: CMsvClientEntry* DoGetEntryLC(TMsvId aId, TMsvId& aOwningService); williamr@2: void DoGetChildrenL(); williamr@2: CMsvEntryArray* GetNewSortedListL(const TMsvSelectionOrdering& aOrdering, const CArrayFix& aMtmList); williamr@2: void DoSortTypeL(CMsvClientEntry* aContext); williamr@2: void ReplaceChildL(TInt pos, const TMsvEntry& aEntry); williamr@2: void DeleteChild(TInt aPosition); williamr@2: void HandleMediaChangeL(); williamr@2: williamr@2: TInt MoveOneL(TMsvId aMsvId, TMsvId aTargetId); williamr@2: TInt CopyOneL(TMsvId aMsvId, TMsvId aTargetId); williamr@2: TInt DeleteOneL(TMsvId aMsvId); williamr@2: // williamr@2: private: williamr@2: enum TEntryState { EValid, williamr@2: EInvalidChangingContext, williamr@2: EInvalidDeletedContext, williamr@2: EInvalidOldContext, williamr@2: EInvalidMissingChildren}; williamr@2: // williamr@2: #ifndef _NO_SESSION_LOGGING_ williamr@2: void Log(TRefByValue aFmt, ...); williamr@2: #endif williamr@2: // williamr@2: private: williamr@2: TBool iOberserverAdded; williamr@2: TEntryState iState; williamr@2: CMsvSession& iMsvSession; williamr@2: TMsvSelectionOrdering iOrdering; williamr@2: const TMsvEntry* iEntryPtr; williamr@2: CArrayPtrFlat* iObservers; williamr@2: CArrayPtrFlat* iEntries; williamr@2: CMsvEntryArray* iSortedChildren; williamr@2: CMsvStore* iStore; williamr@2: CArrayFixFlat* iMtmList; williamr@2: TMsvId iOwningService; williamr@2: TUint32 iNotifySequence; williamr@2: }; williamr@2: williamr@2: //********************************** williamr@2: // MessageServer williamr@2: //********************************** williamr@2: // williamr@2: // williamr@2: // williamr@2: williamr@2: class MessageServer williamr@2: /** Provides various static information functions relating to the Message Server. williamr@2: williamr@2: @see TDriveNumber williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static TVersion Version(); williamr@2: IMPORT_C static TMsvId NullUidValue(); williamr@2: // williamr@2: IMPORT_C static TBool DriveContainsStore(RFs& aFs, TInt aDrive); williamr@2: IMPORT_C static TInt CurrentDriveL(RFs& aFs); williamr@2: IMPORT_C static TBool IsMessageStoreDrivePresentL(RFs& aFs); williamr@2: }; williamr@2: williamr@2: //********************************** williamr@2: // MtmClientUtils williamr@2: //********************************** williamr@2: // williamr@2: // williamr@2: // williamr@2: williamr@2: class McliUtils williamr@2: /** Utility class to simplify getting progress information from a messaging operation object. williamr@2: williamr@2: The functions get and unpack the progress information buffers from an operation object. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: IMPORT_C static TMsvLocalOperationProgress GetLocalProgressL(CMsvOperation& aOperation); williamr@2: IMPORT_C static TMsvLocalOperationProgress GetFinalLocalProgress(CMsvOperation& aOperation); williamr@2: IMPORT_C static TInt GetProgressErrorL(CMsvOperation& aOperation); williamr@2: IMPORT_C static TMsvId GetProgressIdL(CMsvOperation& aOperation); williamr@2: }; williamr@2: williamr@2: #include williamr@2: williamr@2: #endif // __MSVAPI_H__