1.1 --- a/epoc32/include/msvapi.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/msvapi.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1002 @@
1.4 -msvapi.h
1.5 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifdef _DEBUG
1.21 +#undef _NO_SESSION_LOGGING_
1.22 +#endif
1.23 +
1.24 +#ifndef __MSVAPI_H__
1.25 +#define __MSVAPI_H__
1.26 +
1.27 +#include <e32base.h>
1.28 +#include <s32file.h>
1.29 +
1.30 +#ifdef _MSVAPI_DONT_INCLUDE_FLOGGER_
1.31 + #ifndef _NO_SESSION_LOGGING_
1.32 + #define _NO_SESSION_LOGGING_
1.33 + #endif
1.34 +#else
1.35 + #include <flogger.h>
1.36 +#endif
1.37 +
1.38 +#include <msvstd.h>
1.39 +#include <msvstore.h>
1.40 +#include <msvipc.h>
1.41 +#include <msvarray.h>
1.42 +#include <mclient.h>
1.43 +
1.44 +// Forward declarations
1.45 +class CMsvSession;
1.46 +class CMsvEntry;
1.47 +class CBaseMtm;
1.48 +class CMsvClientEntry;
1.49 +class CMsvEntryArray;
1.50 +class CMsvServer;
1.51 +class CMsvServerEntry;
1.52 +
1.53 +// Remove these to remove client logging
1.54 +//#define _NO_SESSION_LOGGING_
1.55 +#define _NO_SESSION_LOGGING_SERIAL_
1.56 +
1.57 +// Single export used to start the message server
1.58 +IMPORT_C TInt StartMessageServer(TAny*);
1.59 +
1.60 +// Create Message Server and return a server entry owned by caller
1.61 +// This is all that is required to test server Mtm's
1.62 +IMPORT_C CServer2* CreateMessageServerL(CMsvServerEntry*& aServerEntry);
1.63 +
1.64 +//**********************************
1.65 +// CMsvOperation
1.66 +//**********************************
1.67 +//
1.68 +// Abstract base class for operations controlling asynchronous functions
1.69 +//
1.70 +
1.71 +class CMsvOperation : public CActive
1.72 +/** Defines an interface for use by objects which control asynchronous commands
1.73 +in the messaging system.
1.74 +
1.75 +Such objects are returned by CMsvEntry and User Interface MTM functions that
1.76 +complete asynchronously. The interface allows clients to:
1.77 +
1.78 +1. get progress information about the operation
1.79 +
1.80 +2. cancel the operation
1.81 +
1.82 +3. be signalled asynchronously when the operation completes; a client passes
1.83 +in a TRequestStatus of a suitable active object for this purpose
1.84 +
1.85 +The client only needs to understand the CMsvOperation interface, not the concrete
1.86 +implementation used.
1.87 +
1.88 +Writing derived classes:
1.89 +
1.90 +As the base class interface for User Interface MTMs, CBaseUiMtm, defines functions
1.91 +that return CMsvOperation objects for control of asynchronous operations,
1.92 +implementers of these MTM components are required to provide suitable derived
1.93 +classes. For example, if CBaseUiMtm::EditL() is implemented to provide message
1.94 +editing, a CMsvOperation -derived class would be provided that completes when
1.95 +the editing operation is complete.
1.96 +
1.97 +Concrete derived classes must provide implementations of the pure virtual
1.98 +DoCancel() and RunL() functions defined by CActive. DoCancel() should be provided
1.99 +in the normal way to cancel the operation. RunL() should, in addition to any
1.100 +other required functionality, always end by signalling the client that the
1.101 +operation is complete with a suitable completion code.
1.102 +
1.103 +@publishedAll
1.104 +@released
1.105 +*/
1.106 + {
1.107 +public:
1.108 + IMPORT_C CMsvOperation(CMsvSession& aMsvSession, TInt aPriority, TRequestStatus& aObserverRequestStatus);
1.109 + IMPORT_C ~CMsvOperation();
1.110 + /** Gets information on the progress of the operation.
1.111 +
1.112 + All operations on local entries share the same progress information format,
1.113 + which defined by TMsvLocalOperationProgress.
1.114 +
1.115 + For MTM-specific operations, progress information can be extracted by calling
1.116 + CBaseUiMtm::GetProgress() or displayed by CBaseUiMtm::DisplayProgressSummary()
1.117 + on the appropriate User Interface MTM.
1.118 +
1.119 + Requirements:
1.120 +
1.121 + Derived classes should implement this function so that the client can check
1.122 + on the progress of the operation. The function should share an understanding
1.123 + of the format of the buffer with the implementations of CBaseUiMtm::GetProgress()
1.124 + and CBaseUiMtm::DisplayProgressSummary() in the User Interface MTM. The arguments
1.125 + of CBaseUiMtm::GetProgress() show some information that should be included
1.126 + where appropriate.
1.127 +
1.128 + @leave KErrNotReady The operation has not yet been started: it has been queued
1.129 + for execution in the Message Server
1.130 + @return Descriptor holding progress information. The maximum buffer size should
1.131 + be KMsvProgressBufferLength (defined in msvipc.h). */
1.132 + virtual const TDesC8& ProgressL()=0;
1.133 + IMPORT_C virtual const TDesC8& FinalProgress();
1.134 + IMPORT_C TInt SystemProgress(TMsvSystemProgress& aOutSysProg);
1.135 + IMPORT_C virtual TUid Mtm() const;
1.136 + //
1.137 + inline TMsvOp Id() const;
1.138 + inline TMsvId Service() const;
1.139 + //
1.140 +protected:
1.141 + IMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);
1.142 +
1.143 +protected:
1.144 + /** The ID of the service that is associated with this operation.
1.145 +
1.146 + Usually, the derived class constructor will contain a suitable argument to
1.147 + allow the caller to set this.
1.148 +
1.149 + @see Service() */
1.150 + TMsvId iService;
1.151 + /** The UID of the MTM associated with the operation.
1.152 +
1.153 + The appropriate value should be set by the derived class constructor.
1.154 +
1.155 + @see Mtm() */
1.156 + TUid iMtm;
1.157 + /** Request status of the operation observer.
1.158 +
1.159 + This is the aObserverRequestStatus passed in the constructor. */
1.160 + TRequestStatus& iObserverRequestStatus;
1.161 + /** Message Server session used by object. This is set by the constructor. */
1.162 + CMsvSession& iMsvSession;
1.163 +
1.164 +private:
1.165 + TMsvOp iId;
1.166 + };
1.167 +
1.168 +
1.169 +//**********************************
1.170 +// CMsvOperationWait
1.171 +//**********************************
1.172 +//
1.173 +// Allows a synchronous wait on a operation
1.174 +//
1.175 +
1.176 +class CMsvOperationWait: public CActive
1.177 +/** Utility class used to wait until an asynchronous messaging operation
1.178 +has completed.
1.179 +
1.180 +Note that CMsvOperationActiveSchedulerWait is simpler to use, and should be used in
1.181 +preference to this class.
1.182 +
1.183 +To use the class:
1.184 +
1.185 +1. Create a new CMsvOperationWait object
1.186 +
1.187 +2. Call the messaging function that returns the asynchronous operation.
1.188 +The operation observer parameter should be the iStatus word of the CMsvOperationWait
1.189 +object. This means that the CMsvOperationWait object will be signalled when
1.190 +the operation completes.
1.191 +
1.192 +3. Call the CMsvOperationWait object's Start() function. This sets the object
1.193 +to be active.
1.194 +
1.195 +4. Call CActiveScheduler::Start(). This starts a nested active scheduler. The
1.196 +program will then wait until this active scheduler is stopped. The CMsvOperationWait
1.197 +object stops the scheduler when the operation completes, allowing the program to
1.198 +continue.
1.199 +
1.200 +These steps cause the program to wait until the operation completes.
1.201 +
1.202 +@code
1.203 + CMsvOperationWait* waiter=CMsvOperationWait::NewLC();
1.204 + CMsvOperation* op = function_returning_opLC(waiter->iStatus);
1.205 + waiter->Start();
1.206 + CActiveScheduler::Start();
1.207 + CleanupStack::PopAndDestroy(2); // op, waiter
1.208 +@endcode
1.209 +
1.210 +@see CActiveScheduler
1.211 +@publishedAll
1.212 +@released
1.213 +*/
1.214 + {
1.215 +public:
1.216 + IMPORT_C static CMsvOperationWait* NewLC(TInt aPriority=EPriorityStandard);
1.217 + IMPORT_C ~CMsvOperationWait();
1.218 + IMPORT_C void Start();
1.219 +protected:
1.220 + CMsvOperationWait(TInt aPriority);
1.221 + void RunL();
1.222 + void DoCancel();
1.223 + };
1.224 +
1.225 +
1.226 +//**********************************
1.227 +// CMsvOperationActiveSchedulerWait
1.228 +//**********************************
1.229 +//
1.230 +// Allows a synchronous wait on a operation using CActiveSchedulerWait class
1.231 +// This class should be used in preference to CMsvOperationWait
1.232 +// DOES NOT require an explicit call to CActiveScheduler::Start()--CMsvOperationActiveSchedulerWait::Start()
1.233 +// effectively encapsulates this functionality
1.234 +//
1.235 +
1.236 +class CMsvOperationActiveSchedulerWait: public CActive
1.237 +/** Utility class used to wait until an asynchronous messaging operation
1.238 +has completed.
1.239 +
1.240 +To use the class:
1.241 +
1.242 +1. Create a new CMsvOperationActiveSchedulerWait object
1.243 +
1.244 +2. Call the messaging function that returns the asynchronous operation.
1.245 +The operation observer parameter should be the iStatus word of the CMsvOperationActiveSchedulerWait
1.246 +object. This means that the CMsvOperationActiveSchedulerWait object will be signalled when
1.247 +the operation completes.
1.248 +
1.249 +3. Call the CMsvOperationActiveSchedulerWait object's Start() function. This sets the object
1.250 +to be active.
1.251 +
1.252 +These steps cause the program to wait until the operation completes.
1.253 +
1.254 +@code
1.255 + CMsvOperationActiveSchedulerWait* waiter=CMsvOperationActiveSchedulerWait::NewLC();
1.256 + CMsvOperation* op = function_returning_opLC(waiter->iStatus);
1.257 + waiter->Start();
1.258 +
1.259 + CleanupStack::PopAndDestroy(2); // op, waiter
1.260 +@endcode
1.261 +
1.262 +@publishedAll
1.263 +@released
1.264 +*/
1.265 + {
1.266 +public:
1.267 + IMPORT_C static CMsvOperationActiveSchedulerWait* NewLC(TInt aPriority=EPriorityStandard);
1.268 + IMPORT_C ~CMsvOperationActiveSchedulerWait();
1.269 + IMPORT_C void Start();
1.270 +private:
1.271 + CMsvOperationActiveSchedulerWait(TInt aPriority);
1.272 + void RunL();
1.273 + void DoCancel();
1.274 +private:
1.275 + CActiveSchedulerWait iActiveSchedulerWait;
1.276 + };
1.277 +
1.278 +//**********************************
1.279 +// CMsvCompletedOperation
1.280 +//**********************************
1.281 +//
1.282 +// An operation which is already completed on construction
1.283 +//
1.284 +
1.285 +class CMsvCompletedOperation : public CMsvOperation
1.286 +/** Utility to create a messaging operation object for an operation that has already
1.287 +completed.
1.288 +
1.289 +This utility is useful, for example, for writers of MTMs, where the API requires that an
1.290 +asynchronous operation is returned, but where in reality, the operation has performed
1.291 +synchronously. It allows the program to construct an operation object for which
1.292 +the operation is already completed, with the progress information and error code set.
1.293 +
1.294 +@publishedAll
1.295 +@released
1.296 +*/
1.297 + {
1.298 +public:
1.299 + IMPORT_C static CMsvCompletedOperation* NewL(CMsvSession& aMsvSession, TUid aMtm, const TDesC8& aProgress, TMsvId aService, TRequestStatus& aObserverRequestStatus, TInt aErr=KErrNone);
1.300 + IMPORT_C ~CMsvCompletedOperation();
1.301 + //
1.302 + const TDesC8& ProgressL();
1.303 + const TDesC8& FinalProgress();
1.304 +private:
1.305 + CMsvCompletedOperation(CMsvSession& aSession, TRequestStatus& aObserverRequestStatus);
1.306 + void ConstructL(TUid aMtm, TInt aError, const TDesC8& aProgress, TMsvId aService);
1.307 + // from CActive
1.308 + void DoCancel();
1.309 + void RunL();
1.310 + //
1.311 +private:
1.312 + HBufC8* iProgress;
1.313 + };
1.314 +
1.315 +//**********************************
1.316 +// CMsvSendOperation
1.317 +//**********************************
1.318 +//
1.319 +// A send operation which returns a standard progress (used by SendAs2)
1.320 +//
1.321 +
1.322 +/** Utility to create an operation containing a sending operation which may be used
1.323 +to retrieve a standard progress structure.
1.324 +
1.325 +This class is intended to be derived from. The derived class must define the TranslateProgress()
1.326 +member function. This function is responsible for translating the native progress of the given
1.327 +mtm into the standard progress structure, CMsvSendOperation::TSendOperationProgress.
1.328 +
1.329 +@publishedAll
1.330 +@released
1.331 +*/
1.332 +class CMsvSendOperation : public CMsvOperation
1.333 + {
1.334 +public:
1.335 + /** Send progress state.
1.336 +
1.337 + @see TSendOperationProgress
1.338 + */
1.339 + enum TSendOperationState
1.340 + {
1.341 + ESendStateInPreparation,
1.342 + ESendStateWaitingToSend,
1.343 + ESendStateConnecting,
1.344 + ESendStateSending,
1.345 + ESendStateDone,
1.346 + ESendStateFailed
1.347 + };
1.348 + /** Send progress.
1.349 +
1.350 + Structure holding send progress. For mtms unable to provide detailed progress
1.351 + information, iProgressMax and iProgress must be zeroed. This will then allow
1.352 + the client to check for this case and display a busy status dialog as opposed to
1.353 + a progress dialog. If the mtm is capable of detailed progress, iProgressMax
1.354 + should be set to the total number of units to be sent and iProgress the number
1.355 + of units sent.
1.356 +
1.357 + @see TSendOperationState
1.358 + */
1.359 + class TSendOperationProgress
1.360 + {
1.361 + public:
1.362 + TSendOperationState iState;
1.363 + TInt iError;
1.364 + TInt iProgressMax;
1.365 + TInt iProgress;
1.366 + };
1.367 +
1.368 +public:
1.369 + IMPORT_C virtual ~CMsvSendOperation();
1.370 + // methods from CMsvOperation
1.371 + IMPORT_C virtual const TDesC8& ProgressL();
1.372 + IMPORT_C virtual const TDesC8& FinalProgress();
1.373 + IMPORT_C void Start(CMsvOperation* aOperation);
1.374 +protected:
1.375 + IMPORT_C CMsvSendOperation(CMsvSession& aMsvSession, TRequestStatus& aObserverRequestStatus);
1.376 +private: // methods from CActive
1.377 + IMPORT_C virtual void DoCancel();
1.378 + IMPORT_C virtual void RunL();
1.379 +private:
1.380 + /** Translates the progress from sending operation's progress into TSendOperationProgress.
1.381 +
1.382 + This member function must be defined by derived classes. Must not leave.
1.383 + @see TSendOperationProgress
1.384 + @return Descriptor holding progress information.
1.385 + */
1.386 + virtual const TDesC8& TranslateProgress(const TDesC8& aProgress)=0;
1.387 + void Complete(TInt anError);
1.388 +protected:
1.389 + /** The progress that is associated with this operation.
1.390 +
1.391 + The TranslateProgress defined by derived classes must populate and return
1.392 + this progress structure.
1.393 + @see TranslateProgress()
1.394 + @see TSendOperationProgress */
1.395 + TPckgBuf<TSendOperationProgress> iProgress;
1.396 + /** The sending operation.
1.397 +
1.398 + Assigned when ConstructL is called
1.399 + */
1.400 + CMsvOperation* iOperation;
1.401 + };
1.402 +
1.403 +/** Package buffer for a TSendOperationProgress
1.404 +*/
1.405 +typedef TPckgBuf<CMsvSendOperation::TSendOperationProgress> TMsvSendOperationProgress;
1.406 +
1.407 +
1.408 +//**********************************
1.409 +// MMsvSessionObserver
1.410 +//**********************************
1.411 +//
1.412 +//
1.413 +//
1.414 +
1.415 +class MMsvSessionObserver
1.416 +/** Provides the interface for notification of events from a Message Server session.
1.417 +
1.418 +
1.419 +The types of event are given in the enumeration TMsvSessionEvent. Clients
1.420 +must provide an object that implements the interface, and set it to be notified
1.421 +through CMsvSession::OpenSyncL() or CMsvSession::OpenASyncL(). Additional
1.422 +observers can also be added and removed through CMsvSession.
1.423 +
1.424 +@see CMsvSession::AddObserverL()
1.425 +@see CMsvSession::RemoveObserver()
1.426 +@publishedAll
1.427 +@released
1.428 +*/
1.429 + {
1.430 +public:
1.431 + /** Session event type.
1.432 +
1.433 + @see EMsvMediaUnavailable
1.434 + @see TDriveNumber
1.435 + */
1.436 + enum TMsvSessionEvent
1.437 + {
1.438 + /** One or more entries have been created.
1.439 +
1.440 + aArg1 is a CMsvEntrySelection of the new entries. aArg2 is the TMsvId of the
1.441 + parent entry. */
1.442 + EMsvEntriesCreated,
1.443 + /** One or more index entries have been changed.
1.444 +
1.445 + aArg1 is a CMsvEntrySelection of the index entries. aArg2 is the TMsvId of
1.446 + the parent entry. */
1.447 + EMsvEntriesChanged,
1.448 + /** One or more entries have been deleted.
1.449 +
1.450 + aArg1 is a CMsvEntrySelection containing the IDs of the deleted entries. aArg2
1.451 + is the TMsvId of the parent entry. */
1.452 + EMsvEntriesDeleted,
1.453 + /** One or more entries have been moved.
1.454 +
1.455 + aArg1 is a CMsvEntrySelection containing the IDs of the moved entries. aArg2
1.456 + is the TMsvId of the new parent. aArg3 is the TMsvId of the old parent entry. */
1.457 + EMsvEntriesMoved,
1.458 + /** A new MTM has been installed.
1.459 +
1.460 + aArg2 points to a TUid for the new MTM. */
1.461 + EMsvMtmGroupInstalled,
1.462 + /** A MTM has been uninstalled.
1.463 +
1.464 + aArg2 points to a TUid of the removed MTM. */
1.465 + EMsvMtmGroupDeInstalled,
1.466 + /** Something has happening in the server, but this client was unable to retrieve
1.467 + the information.
1.468 +
1.469 + aArg1 points to the error code. */
1.470 + EMsvGeneralError,
1.471 + /** The client should immediately close the session with the Message Server. */
1.472 + EMsvCloseSession,
1.473 + /** Received after a client has used CMsvSession::OpenAsyncL() to create a session.
1.474 +
1.475 +
1.476 + The session can now be used. */
1.477 + EMsvServerReady,
1.478 + /** Received after a client has used CMsvSession::OpenAsyncL() to create a session.
1.479 +
1.480 +
1.481 + The server could not be started, and aArg1 points to the error code. */
1.482 + EMsvServerFailedToStart,
1.483 + /** The Message Server index had been corrupted and had to be rebuilt.
1.484 +
1.485 + All local entries are recovered, but all remote entries have been lost. */
1.486 + EMsvCorruptedIndexRebuilt,
1.487 + /** The Message Server has been terminated.
1.488 +
1.489 + All clients must close their sessions immediately. */
1.490 + EMsvServerTerminated,
1.491 + /** The Message Server has automatically changed the index location to use the
1.492 + internal disk.
1.493 +
1.494 + aArg1 is a TDriveNumber value that identifies the drive used by the Message
1.495 + Server to hold the index prior to the change.
1.496 +
1.497 + aArg2 is also a TDriveNumber value; it identifies the new drive that the Message
1.498 + Server is using.
1.499 +
1.500 + CMsvEntry contexts either refresh themselves or mark themselves invalid.
1.501 +
1.502 + @see EMsvMediaUnavailable
1.503 + @see TDriveNumber */
1.504 + EMsvMediaChanged, // I assume the following four are in sequential order
1.505 + /** The media (disk) containing the Message Server index has been removed.
1.506 +
1.507 + aArg1 is a TDriveNumber value that identifies the drive that is no longer
1.508 + available.
1.509 +
1.510 + Future requests may fail with KMsvMediaUnavailable. A EMsvMediaChanged event
1.511 + may be received in the future, as the Message Server switches back to the
1.512 + internal drive. */
1.513 + EMsvMediaUnavailable,
1.514 + /** The disk containing the Message Store is available again.
1.515 +
1.516 + aArg1 is a TDriveNumber value that identifies the drive that is being used.
1.517 +
1.518 + The Message Server can now operate as normal. No client action is necessary. */
1.519 + EMsvMediaAvailable,
1.520 + /** An incorrect disk is inserted.
1.521 +
1.522 + aArg1 is a TDriveNumber value that identifies the drive in which the incorrect
1.523 + disk has been inserted.
1.524 +
1.525 + Some requests may fail with KMsvMediaIncorrect. Clients may get an EMsvMediaChanged
1.526 + event in the future telling them that the Message Server has switched back
1.527 + to the internal drive. */
1.528 + EMsvMediaIncorrect,
1.529 + /** The Message Server has started to rebuild its index after it has been corrupted.
1.530 +
1.531 + @see EMsvCorruptedIndexRebuilt */
1.532 + EMsvCorruptedIndexRebuilding
1.533 + };
1.534 +public:
1.535 + /** Indicates an event has occurred.
1.536 +
1.537 + The type of event is indicated by the value of aEvent. The interpretation
1.538 + of the TAny arguments depends on this type.
1.539 +
1.540 + For most event types, the action that is taken, for example, updating the
1.541 + display, is client-specific. All clients though should respond to EMsvCloseSession
1.542 + and EMsvServerTerminated events.
1.543 +
1.544 + @param aEvent Indicates the event type.
1.545 + @param aArg1 Event type-specific argument value
1.546 + @param aArg2 Event type-specific argument value
1.547 + @param aArg3 Event type-specific argument value */
1.548 + virtual void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0;
1.549 + };
1.550 +
1.551 +//**********************************
1.552 +// CMsvSession
1.553 +//**********************************
1.554 +//
1.555 +//
1.556 +//
1.557 +
1.558 +class TCapabilitySet;
1.559 +
1.560 +const TInt KMsvSessionObserverGranularity=4; //???
1.561 +
1.562 +class CMsvSession: public CActive
1.563 +/** Represents a channel of communication between a client thread (Client-side
1.564 +MTM, User Interface MTM, or message client application) and the Message Server
1.565 +thread.
1.566 +
1.567 +The class provides the means by which clients are notified when important
1.568 +Message Server events occur.
1.569 +
1.570 +Note the following significant groups of functions:
1.571 +
1.572 +Creation functions: a message client application must use OpenSyncL() or OpenASyncL()
1.573 +to create a session object, before it can instantiate any MTM or CMsvEntry
1.574 +object. Only a single session should be created within a thread. As Client-side
1.575 +MTM, User Interface MTM, and CMsvEntry objects are created in the client thread,
1.576 +these use the client session, and do not create their own. Note that to close
1.577 +a session, delete all objects relying on that session, and then the session
1.578 +object itself.
1.579 +
1.580 +Cleanup functions: CMsvSession provides the ability to handle the cleanup
1.581 +of entries in the event of a leave occurring, in a very similar manner to
1.582 +the standard cleanup stack. The difference is that, on a leave, any entries
1.583 +that are on the entry cleanup stack are removed from the Message Server. The
1.584 +implementation uses the standard cleanup stack, so entry push and pop functions
1.585 +should be used in the same order as all other types of push and pop. The functions
1.586 +can be used both by MTM implementations and message client applications.
1.587 +@publishedAll
1.588 +@released
1.589 +*/
1.590 + {
1.591 +public:
1.592 + IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver);
1.593 + IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver);
1.594 + IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver);
1.595 +
1.596 + IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, RFs& aFs);
1.597 + IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, RFs& aFs);
1.598 + IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, RFs& aFs);
1.599 +
1.600 + IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, TInt aPriority);
1.601 + IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, TInt aPriority);
1.602 + IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, TInt aPriority);
1.603 +
1.604 + IMPORT_C static CMsvSession* OpenSyncL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority);
1.605 + IMPORT_C static CMsvSession* OpenAsyncL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority);
1.606 + IMPORT_C static CMsvSession* OpenAsObserverL(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority);
1.607 +
1.608 + ~CMsvSession();
1.609 + // --- Observer functions ---
1.610 + IMPORT_C void AddObserverL(MMsvSessionObserver& aObserver);
1.611 + IMPORT_C void RemoveObserver(MMsvSessionObserver& aObserver);
1.612 + IMPORT_C TInt SetReceiveEntryEvents(TBool aReceive);
1.613 + // --- Utility functions ---
1.614 + IMPORT_C CMsvEntry* GetEntryL(TMsvId aEntId);
1.615 + IMPORT_C TInt GetEntry(TMsvId aId, TMsvId& aService, TMsvEntry& aEntry);
1.616 +
1.617 + IMPORT_C CMsvOperation* TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TRequestStatus& aStatus);
1.618 + IMPORT_C void TransferCommandL(const CMsvEntrySelection& aSelection, TInt aCommandId, const TDesC8& aParameter, TDes8& aProgress);
1.619 + IMPORT_C void IncPcSyncCountL(const CMsvEntrySelection& aSelection);
1.620 + IMPORT_C void DecPcSyncCountL(const CMsvEntrySelection& aSelection);
1.621 + IMPORT_C void GetChildIdsL(TMsvId aId, const CMsvEntryFilter& aFilter, CMsvEntrySelection& aSelection);
1.622 + IMPORT_C void ChangeAttributesL(const CMsvEntrySelection& aSelection, TUint aSetAttributes, TUint aClearAttributes);
1.623 + IMPORT_C CMsvOperation* ChangeDriveL(TInt aDrive, TRequestStatus& aStatus);
1.624 + IMPORT_C TInt OutstandingOperationsL();
1.625 + IMPORT_C CMsvOperation* CopyStoreL(const TDriveUnit& aDrive, TRequestStatus& aStatus);
1.626 + IMPORT_C CMsvOperation* DeleteStoreL(const TDriveUnit& aDrive, TRequestStatus& aStatus);
1.627 + // --- cleanup functions
1.628 + IMPORT_C static void CleanupEntry(TAny* aPtr);
1.629 + IMPORT_C void CleanupEntryPushL(TMsvId aId);
1.630 + IMPORT_C void CleanupEntryPop(TInt aCount=1);
1.631 +
1.632 + IMPORT_C void RemoveEntry(TMsvId aId);
1.633 + /// MTM functions
1.634 + IMPORT_C TInt InstallMtmGroup(const TDesC& aFullName);
1.635 + IMPORT_C TInt DeInstallMtmGroup(const TDesC& aFullName);
1.636 +
1.637 + IMPORT_C TInt StopService(TMsvId aServiceId);
1.638 + IMPORT_C TBool ServiceActive(TMsvId aServiceId);
1.639 + IMPORT_C TInt ServiceProgress(TMsvId aServiceId, TDes8& aProgress);
1.640 +
1.641 + IMPORT_C void CloseMessageServer();
1.642 + IMPORT_C RFs& FileSession();
1.643 +
1.644 + IMPORT_C void GetMtmRequiredCapabilitiesL(TUid aMtmTypeUid, TCapabilitySet& aCapSet) const;
1.645 + MMsvStoreManager& StoreManager();
1.646 +
1.647 + IMPORT_C TBool GetAndClearIndexCorruptFlagL();
1.648 + IMPORT_C TDriveUnit CurrentDriveL();
1.649 + IMPORT_C TBool DriveContainsStoreL(TDriveUnit aDrive);
1.650 + IMPORT_C TBool MessageStoreDrivePresentL();
1.651 +
1.652 + IMPORT_C TInt ServiceAccessPointId(TMsvId aServiceId, TUint32& aAccessPointId);
1.653 +
1.654 +protected:
1.655 + CMsvSession(MMsvSessionObserver& aObserver);
1.656 + CMsvSession(MMsvSessionObserver& aObserver, RFs& aFs);
1.657 + CMsvSession(MMsvSessionObserver& aObserver, TInt aPriority);
1.658 + CMsvSession(MMsvSessionObserver& aObserver, RFs& aFs, TInt aPriority);
1.659 +
1.660 + void ConstructL(TBool aSyncOpening);
1.661 + void ConstructAsObserverL();
1.662 + //
1.663 + IMPORT_C TInt OperationId();
1.664 + IMPORT_C RMsvServerSession& Session();
1.665 +
1.666 + void CheckDrive();
1.667 + //
1.668 + // from CActive
1.669 + void RunL();
1.670 + void DoCancel();
1.671 + TInt RunError(TInt aError);
1.672 + //
1.673 +private:
1.674 + void NotifyAllObserversL(MMsvSessionObserver::TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3);
1.675 + void CleanupEntryDelete();
1.676 + void DoRunL(TMsvNotifBuffer& aBuffer);
1.677 + void HandleNotifyL();
1.678 + void DoHandleNotifyL(TMsvNotifBuffer& aBuffer);
1.679 + void GetMessageFolderL();
1.680 + //
1.681 +private:
1.682 + TInt iOperationId;
1.683 + RFs iFs;
1.684 + RMsvServerSession iSession;
1.685 + TMsvNotifBuffer iChange;
1.686 + MMsvSessionObserver& iMainObserver;
1.687 + CArrayPtrFlat<MMsvSessionObserver>* iObservers;
1.688 + CMsvEntrySelection* iCleanupList;
1.689 + TInt iSyncStart;
1.690 + HBufC* iMessageFolder;
1.691 + TDriveNumber iDrive;
1.692 + CMsvEntrySelection* iNotifSelection;
1.693 + TPckgBuf<TUint32> iSequenceBuf;
1.694 + TUint32 iNotifySequence;
1.695 + TBool iReceiveEntryEvents;
1.696 + /** Specifies whether to use the shared file server session */
1.697 + TBool iUseSharedFs;
1.698 + //
1.699 +#ifndef _NO_SESSION_LOGGING_
1.700 + void CreateSessionLogL();
1.701 + void Log(TRefByValue<const TDesC> aFmt, ...);
1.702 +
1.703 + // must be the last data member in the class to preserve BC.
1.704 + mutable RFileLogger iLog;
1.705 +#endif
1.706 + //
1.707 +friend class CSendAs;
1.708 +friend class CMsvEntry;
1.709 +friend class CMsvOperation;
1.710 +friend class CMsvEntryOperation;
1.711 +friend class CObserverRegistry;
1.712 + //
1.713 + };
1.714 +
1.715 +
1.716 +
1.717 +
1.718 +//**********************************
1.719 +// MMsvEntryObserver
1.720 +//**********************************
1.721 +//
1.722 +//
1.723 +//
1.724 +
1.725 +class MMsvEntryObserver
1.726 +/** Provides the interface for notification of events associated with an entry.
1.727 +
1.728 +The types of event are given in the enumeration TMsvEntryEvent. Clients can
1.729 +provide an object that implements the interface, and set it to be notified
1.730 +through CMsvEntry::AddObserverL().
1.731 +@publishedAll
1.732 +@released
1.733 +*/
1.734 + {
1.735 +public:
1.736 + /** Defines entry event types.
1.737 +@publishedAll
1.738 +@released
1.739 +*/
1.740 + enum TMsvEntryEvent
1.741 + {
1.742 + /** The entry has been changed, either as a result of a CMsvEntry::ChangeL() or
1.743 + by another client. */
1.744 + EMsvEntryChanged,
1.745 + /** New children have been created. aArg1 points to a CMsvEntrySelection contain
1.746 + the ID of the new children. */
1.747 + EMsvNewChildren,
1.748 + /** Children have been deleted. aArg1 points to a CMsvEntrySelection contain the
1.749 + ID of the deleted children. */
1.750 + EMsvDeletedChildren,
1.751 + /** One or more of the children have been changed. aArg1 points to a CMsvEntrySelection
1.752 + containing the IDs of the changed children. */
1.753 + EMsvChildrenChanged,
1.754 + /** The entry has been deleted by another client. The context is now invalid. */
1.755 + EMsvEntryDeleted,
1.756 + /** The context has become invalid. The entry has been changed, but the CMsvEntry
1.757 + was unable to update the context. The context will only become valid by a
1.758 + successful CMsvEntry::SetEntryL() call. aArg1 points to a TInt containing
1.759 + the error code for the invalid context. */
1.760 + EMsvContextInvalid,
1.761 + /** Some new children have been created, but CMsvEntry was unable to retrieve the
1.762 + data from the Message Server. The children will be correct only after a successful
1.763 + call to CMsvEntry::SetEntryL(). */
1.764 + EMsvChildrenMissing,
1.765 + /** An error has occurred such that the status of the children is unknown and probably
1.766 + invalid. aArg1 points to a TInt containing the error code for the invalid
1.767 + context */
1.768 + EMsvChildrenInvalid,
1.769 + /** The current entry has been moved by another client. The CMsvEntry has already
1.770 + been updated to reflect the new parent. */
1.771 + EMsvEntryMoved};
1.772 +public:
1.773 + /** Indicates when called by a CMsvEntry object that an event has occurred.
1.774 +
1.775 + The type of event is indicated by the value of aEvent. The interpretation of the aArg1-3 values depends on this type.
1.776 + For most event types, the action that is taken, for example, updating the display, is client-specific. Most clients will
1.777 + need to handle events that make the current context invalid: EMsvContextInvalid and EMsvEntryDeleted.
1.778 +
1.779 + An implementation can leave if an error occurs. The leave is not trapped by the framework, so
1.780 + the error code may be displayed to the user.
1.781 +
1.782 + @param aEvent Indicates the event type.
1.783 + @param aArg1 Event-specific argument value
1.784 + @param aArg2 Event-specific argument value
1.785 + @param aArg3 Event-specific argument value
1.786 + */
1.787 + virtual void HandleEntryEventL(TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0;
1.788 + };
1.789 +
1.790 +
1.791 +
1.792 +//**********************************
1.793 +// CMsvEntry
1.794 +//**********************************
1.795 +//
1.796 +//
1.797 +//
1.798 +
1.799 +class CMsvEntry: public CBase, public MMsvSessionObserver, public MMsvStoreObserver
1.800 +/** Accesses and acts upon a particular Message Server entry. The current entry
1.801 +that a CMsvEntry object relates is referred to as its context.
1.802 +
1.803 +It may be helpful to consider CMsvEntry functions in two broad groups. The
1.804 +first provides means to access the various types of storage associated with
1.805 +an entry. The second provides a means to discover and access other entries
1.806 +that the entry owns (its children).
1.807 +
1.808 +Message client applications, Client-side MTMs, and User Interface MTMs all
1.809 +commonly use CMsvEntry objects. CMsvEntry objects though represent a lower
1.810 +level of access to an entry than that provided by a Client-side MTM or User
1.811 +Interface MTM. In particular, any MTM-specific functionality, such as address
1.812 +lists or subject fields, must be accessed by a message client application
1.813 +through an MTM inteface.
1.814 +
1.815 +A CMsvEntry object is relatively expensive in RAM usage, as it caches its
1.816 +children, updating them as necessary when notified of changes. They should
1.817 +therefore be created sparingly.
1.818 +
1.819 +Note that Server-side MTMs do not use this class, but a similar one, CMsvServerEntry.
1.820 +
1.821 +@publishedAll
1.822 +@released
1.823 +*/
1.824 + {
1.825 +public: // Public member functions
1.826 + IMPORT_C static CMsvEntry* NewL(CMsvSession& aMsvSession, TMsvId aMsvId, const TMsvSelectionOrdering& aOrdering);
1.827 + IMPORT_C ~CMsvEntry();
1.828 + //
1.829 + // --- Observer functions ---
1.830 + IMPORT_C void AddObserverL(MMsvEntryObserver& aObserver);
1.831 + IMPORT_C void RemoveObserver(MMsvEntryObserver& aObserver);
1.832 + //
1.833 + // --- Accessor for associated session ---
1.834 + inline CMsvSession& Session();
1.835 + //
1.836 + // --- Accessors the associated message store ---
1.837 + IMPORT_C CMsvStore* ReadStoreL();
1.838 + IMPORT_C CMsvStore* EditStoreL();
1.839 + //
1.840 + // --- Synchronous Current Entry functions ---
1.841 + inline TMsvId EntryId() const;
1.842 + inline const TMsvEntry& Entry() const;
1.843 + inline const TMsvSelectionOrdering& SortType() const;
1.844 + inline TMsvId OwningService() const;
1.845 + IMPORT_C void SetSortTypeL(const TMsvSelectionOrdering& aOrdering);
1.846 + IMPORT_C void SetMtmListL(const CArrayFix<TUid>& aMtmList);
1.847 + IMPORT_C void SetEntryL(TMsvId aId);
1.848 + IMPORT_C void ChangeL(const TMsvEntry& aEntry);
1.849 + IMPORT_C void ChangeL(const TMsvEntry& aEntry, TSecureId aOwnerId);
1.850 +
1.851 +
1.852 + //
1.853 + // --- Asynchronous Current Entry functions ---
1.854 + IMPORT_C CMsvOperation* ChangeL(const TMsvEntry& aEntry, TRequestStatus& aStatus);
1.855 + IMPORT_C CMsvOperation* ChangeL(const TMsvEntry& aEntry, TSecureId aOwnerId, TRequestStatus& aStatus);
1.856 + //
1.857 + // --- Asynchronous Child Entry functions ---
1.858 + IMPORT_C CMsvOperation* CreateL(const TMsvEntry& aEntry, TRequestStatus& aStatus);
1.859 + IMPORT_C CMsvOperation* CreateL(const TMsvEntry& aEntry, TSecureId aOwnerId, TRequestStatus& aStatus);
1.860 + IMPORT_C CMsvOperation* DeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);
1.861 + IMPORT_C CMsvOperation* DeleteL(TMsvId aMsvId, TRequestStatus& aStatus);
1.862 + IMPORT_C CMsvOperation* CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);
1.863 + IMPORT_C CMsvOperation* CopyL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus);
1.864 + IMPORT_C CMsvOperation* MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TRequestStatus& aStatus);
1.865 + IMPORT_C CMsvOperation* MoveL(TMsvId aMsvId, TMsvId aTargetId, TRequestStatus& aStatus);
1.866 + //
1.867 + // --- Synchronous Child Entry functions ---
1.868 + IMPORT_C CMsvEntrySelection* ChildrenL() const;
1.869 + IMPORT_C CMsvEntrySelection* ChildrenWithServiceL(TMsvId aServiceId) const;
1.870 + IMPORT_C CMsvEntrySelection* ChildrenWithMtmL(TUid aMtm) const;
1.871 + IMPORT_C CMsvEntrySelection* ChildrenWithTypeL(TUid aType) const;
1.872 + inline TInt Count() const;
1.873 + IMPORT_C const TMsvEntry& ChildDataL(TMsvId aId) const;
1.874 + IMPORT_C const TMsvEntry& operator[](TInt aIndex) const;
1.875 + IMPORT_C CMsvEntry* ChildEntryL(TMsvId aId) const;
1.876 + IMPORT_C void MoveL(TMsvId aMsvId, TMsvId aTargetId);
1.877 + IMPORT_C void MoveL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TMsvLocalOperationProgress& aProgress);
1.878 + IMPORT_C void CopyL(const CMsvEntrySelection& aSelection, TMsvId aTargetId, TMsvLocalOperationProgress& aProgress);
1.879 + IMPORT_C void CopyL(TMsvId aMsvId, TMsvId aTargetId);
1.880 +
1.881 +
1.882 + IMPORT_C void CreateL(TMsvEntry& aEntry);
1.883 + IMPORT_C void CreateL(TMsvEntry& aEntry, TSecureId aOwnerId);
1.884 + IMPORT_C void DeleteL(TMsvId aId);
1.885 + IMPORT_C void DeleteL(const CMsvEntrySelection& aSelection, TMsvLocalOperationProgress& aProgress);
1.886 + IMPORT_C void ChangeAttributesL(const CMsvEntrySelection& aSelection, TUint aSetAttributes, TUint aClearAttributes);
1.887 + //
1.888 + // from MMsvSessionObserver
1.889 + void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3);
1.890 + // From MMsvStoreObserver
1.891 + void HandleStoreEvent(TMsvStoreEvent aEvent, TMsvId aId);
1.892 +
1.893 +
1.894 + IMPORT_C TBool HasStoreL() const;
1.895 + //
1.896 + /** @internalTechnology */
1.897 + IMPORT_C void SetEntryNoCheckL(TMsvId aId);
1.898 + //
1.899 +private: // Private members
1.900 + CMsvEntry(CMsvSession& aMsvSession, const TMsvSelectionOrdering& aOrdering);
1.901 + void ConstructL(TMsvId aMsvId);
1.902 + //
1.903 + void NotifyAllObserversL(MMsvEntryObserver::TMsvEntryEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3);
1.904 + void ContextChangedL(MMsvEntryObserver::TMsvEntryEvent aEvent);
1.905 + void NewChildrenL(const CMsvEntrySelection& aSelection);
1.906 + CMsvEntrySelection* DoGetNewChildrenL(const CMsvEntrySelection& aSelection);
1.907 + void DeletedChildrenL(const CMsvEntrySelection& aSelection);
1.908 + void ChildrenChangedL(const CMsvEntrySelection& aSelection);
1.909 + void CheckNewGrandchildrenL(TMsvId aId);
1.910 + void CheckDeletedGrandchildrenL(TMsvId aId);
1.911 + void NotifyChildChangedL(TMsvId aId);
1.912 + CMsvEntrySelection* DoMakeSelectionL(TMsvId aId);
1.913 + void CheckIfContextMovedL(const CMsvEntrySelection& aSelection);
1.914 + //
1.915 + TBool IsAChild(TMsvId aId) const;
1.916 + TBool AreChildren(const CMsvEntrySelection& aSelection) const;
1.917 + //
1.918 + CMsvOperation* DoDeleteL(const CMsvEntrySelection& aSelection, TRequestStatus& aStatus);
1.919 + CMsvClientEntry* DoGetEntryLC(TMsvId aId, TMsvId& aOwningService);
1.920 + void DoGetChildrenL();
1.921 + CMsvEntryArray* GetNewSortedListL(const TMsvSelectionOrdering& aOrdering, const CArrayFix<TUid>& aMtmList);
1.922 + void DoSortTypeL(CMsvClientEntry* aContext);
1.923 + void ReplaceChildL(TInt pos, const TMsvEntry& aEntry);
1.924 + void DeleteChild(TInt aPosition);
1.925 + void HandleMediaChangeL();
1.926 +
1.927 + TInt MoveOneL(TMsvId aMsvId, TMsvId aTargetId);
1.928 + TInt CopyOneL(TMsvId aMsvId, TMsvId aTargetId);
1.929 + TInt DeleteOneL(TMsvId aMsvId);
1.930 + //
1.931 +private:
1.932 + enum TEntryState { EValid,
1.933 + EInvalidChangingContext,
1.934 + EInvalidDeletedContext,
1.935 + EInvalidOldContext,
1.936 + EInvalidMissingChildren};
1.937 + //
1.938 +#ifndef _NO_SESSION_LOGGING_
1.939 + void Log(TRefByValue<const TDesC> aFmt, ...);
1.940 +#endif
1.941 + //
1.942 +private:
1.943 + TBool iOberserverAdded;
1.944 + TEntryState iState;
1.945 + CMsvSession& iMsvSession;
1.946 + TMsvSelectionOrdering iOrdering;
1.947 + const TMsvEntry* iEntryPtr;
1.948 + CArrayPtrFlat<MMsvEntryObserver>* iObservers;
1.949 + CArrayPtrFlat<CMsvClientEntry>* iEntries;
1.950 + CMsvEntryArray* iSortedChildren;
1.951 + CMsvStore* iStore;
1.952 + CArrayFixFlat<TUid>* iMtmList;
1.953 + TMsvId iOwningService;
1.954 + TUint32 iNotifySequence;
1.955 + };
1.956 +
1.957 +//**********************************
1.958 +// MessageServer
1.959 +//**********************************
1.960 +//
1.961 +//
1.962 +//
1.963 +
1.964 +class MessageServer
1.965 +/** Provides various static information functions relating to the Message Server.
1.966 +
1.967 +@see TDriveNumber
1.968 +@publishedAll
1.969 +@released
1.970 +*/
1.971 + {
1.972 +public:
1.973 + IMPORT_C static TVersion Version();
1.974 + IMPORT_C static TMsvId NullUidValue();
1.975 + //
1.976 + IMPORT_C static TBool DriveContainsStore(RFs& aFs, TInt aDrive);
1.977 + IMPORT_C static TInt CurrentDriveL(RFs& aFs);
1.978 + IMPORT_C static TBool IsMessageStoreDrivePresentL(RFs& aFs);
1.979 + };
1.980 +
1.981 +//**********************************
1.982 +// MtmClientUtils
1.983 +//**********************************
1.984 +//
1.985 +//
1.986 +//
1.987 +
1.988 +class McliUtils
1.989 +/** Utility class to simplify getting progress information from a messaging operation object.
1.990 +
1.991 +The functions get and unpack the progress information buffers from an operation object.
1.992 +
1.993 +@publishedAll
1.994 +@released
1.995 +*/
1.996 + {
1.997 +public:
1.998 + IMPORT_C static TMsvLocalOperationProgress GetLocalProgressL(CMsvOperation& aOperation);
1.999 + IMPORT_C static TMsvLocalOperationProgress GetFinalLocalProgress(CMsvOperation& aOperation);
1.1000 + IMPORT_C static TInt GetProgressErrorL(CMsvOperation& aOperation);
1.1001 + IMPORT_C static TMsvId GetProgressIdL(CMsvOperation& aOperation);
1.1002 + };
1.1003 +
1.1004 +#include <msvapi.inl>
1.1005 +
1.1006 +#endif // __MSVAPI_H__