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