1.1 --- a/epoc32/include/msvapi.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1002 +0,0 @@
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__