1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/obexsendop.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,443 @@
1.4 +// Copyright (c) 2001-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 +
1.20 +#ifndef __OBEXSENDOP_H__
1.21 +#define __OBEXSENDOP_H__
1.22 +
1.23 +
1.24 +
1.25 +//#define __OBEX_SEND_OP_FILE_DEBUG_MODE__
1.26 +
1.27 +#include <msvapi.h>
1.28 +#include <badesca.h> // CDesCArray
1.29 +#include <obex.h>
1.30 +#include <obexclientmtm.h> //TObexMtmProgress
1.31 +
1.32 +
1.33 +class CObexHeaderList;
1.34 +
1.35 +
1.36 +///////////////////////////////////////////////////////////////////////////////////
1.37 +// Panic Code
1.38 +///////////////////////////////////////////////////////////////////////////////////
1.39 +
1.40 +///Obex Send Operation Panics
1.41 +enum TObexSendOperationPanic
1.42 + {
1.43 + EObexSendOperationAlreadyActive, ///< The current Obex send operation is already active
1.44 + EObexSendOperationUnknownJob, ///<
1.45 + EObexSendOperationUnknownSendState, ///< The current value of the Obex send state of the send operation is not found in TObexMtmProgress::TSendState
1.46 + EObexSendOperationUnexpectedTimeout ///< Panic if send has timeout unexpectedly
1.47 + };
1.48 +
1.49 +GLDEF_C void Panic(TObexSendOperationPanic aPanic);
1.50 +
1.51 +
1.52 +
1.53 +///////////////////////////////////////////////////////////////////////////////////
1.54 +// CObexServerSendOperation
1.55 +///////////////////////////////////////////////////////////////////////////////////
1.56 +class CObexSendOpTimeout;
1.57 +class CObexPasswordGetter;
1.58 +
1.59 +class CObexServerSendOperation : public CActive, public MObexAuthChallengeHandler
1.60 +/**
1.61 +class CObexServerSendOperation
1.62 +
1.63 +Obex Server Send Operation:
1.64 +
1.65 +Base class for Send operations using Obex protocol.
1.66 +
1.67 +Implements a state machine with the following states:
1.68 +Initialise-->Connect-->ConnectAttemptComplete-->SendObject-->(SendNextObject-->)SendComplete-->MovedToSent-->Disconnected
1.69 +
1.70 +The pure virtual function InitialiseObexClientL() must be overridden in the base class to initialise the
1.71 +iObexClient member to use the desired Obex transport mechanism (e.g. infrared, Bluetooth).
1.72 +
1.73 +In order to allow asynchronous transport initialisations (for example BT's SDP Query)
1.74 +implementations of this function must set iAsyncInit and provide a mechanism to
1.75 +complete a request. See the bluetooth server mtm code for implementation details.
1.76 +
1.77 +@internalTechnology
1.78 +@released
1.79 +*/
1.80 + {
1.81 +public:
1.82 +
1.83 + /**
1.84 + * Destructor. Cancel()s, deletes owned objects and Close()s the connection to the FileServer.
1.85 + */
1.86 +
1.87 + virtual IMPORT_C ~CObexServerSendOperation();
1.88 +
1.89 + /// Must be implemented in the derived class to initialise the iObexClient member to use the desired Obex transport mechanism
1.90 + virtual void InitialiseObexClientL() =0;
1.91 +
1.92 + /**
1.93 + * This is not required to do anything in the base implementation.
1.94 + */
1.95 +
1.96 + IMPORT_C virtual void SecondPhaseObexClientInitL(); // may be overridden to do anything required in a second phase. default implementation is blank.
1.97 +
1.98 + /**
1.99 + * Operations to perform before attempting a connection.
1.100 + * As multiple connection attempts can be made, it is necessary for this
1.101 + * routine to ensure it can handle being called multiple times.
1.102 + * May be overridden. Default implementation is blank.
1.103 + */
1.104 + IMPORT_C virtual void PreConnectOperations();
1.105 +
1.106 + /**
1.107 + * Operations to perform after attempting a connection.
1.108 + * As multiple connection attempts can be made, it is necessary for this
1.109 + * routine to ensure it can handle being called multiple times.
1.110 + * May be overridden. Default implementation is blank.
1.111 + */
1.112 + IMPORT_C virtual void PostConnectOperations();
1.113 +
1.114 + /**
1.115 + * Operations to perform before attempting to send a set of objects.
1.116 + * May be overridden. Default implementation is blank.
1.117 + */
1.118 + IMPORT_C virtual void PreSendOperations();
1.119 +
1.120 + /**
1.121 + * Operations to perform after attempting to send a set of objects.
1.122 + * May be overridden. Default implementation is blank.
1.123 + */
1.124 + IMPORT_C virtual void PostSendOperations();
1.125 +
1.126 +
1.127 +protected: // for use by derived classes
1.128 + /**
1.129 + * Constructor.
1.130 + *
1.131 + * @param aMsgTypeUid UID of message type
1.132 + * @param aSendObj Reference to the object to send.
1.133 + * @param aConnectTimeoutMicroSeconds Timeout period for Connect operation in microseconds.
1.134 + * @param aPutTimeoutMicroseconds Timeout period for Put operation in microseconds.
1.135 + * @param aObserverRequestStatus TRequestStatus of owning active object.
1.136 + */
1.137 +
1.138 + IMPORT_C CObexServerSendOperation(TUid aMsgTypeUid, CMsvServerEntry& aSendObj, TInt aConnectTimeoutMicroSeconds, TInt aPutTimeoutMicroSeconds, TRequestStatus& aObserverRequestStatus);
1.139 +
1.140 + /**
1.141 + * Second phase constructor. Sets up connection to the FileServer, initialises attachments or filename list then
1.142 + * starts sending process by initialising.
1.143 + *
1.144 + * @param aConnectPassword Pointer to the password to be used for authentication.
1.145 + * @leave Leaves if insufficient memory.
1.146 + * @leave Leaves if cannot connect to FileServer.
1.147 + */
1.148 +
1.149 + IMPORT_C void ConstructL(const TDesC* aConnectPassword);
1.150 +
1.151 + /**
1.152 + * Cancels the current operation, deletes the client and Cancel()s the timeout timer. Only completes the observer
1.153 + * (by a call to CompleteObserver) if an external entity (i.e. the owner) has called Cancel().
1.154 + * Otherwise the observer is not completed.
1.155 + */
1.156 +
1.157 + IMPORT_C virtual void DoCancel();
1.158 +
1.159 + /* Constructor, Alternative version
1.160 + *
1.161 + * @param aMsgTypeUid UID of message type
1.162 + * @param aSendObj Reference to the object to send.
1.163 + * @param aConnectTimeoutMicroSeconds Timeout period for Connect operation in microseconds.
1.164 + * @param aPutTimeoutMicroseconds Timeout period for Put operation in microseconds.
1.165 + * @param aObserverRequestStatus TRequestStatus of owning active object.
1.166 + * @param aLastSendAttempt TBool flag to check for the second send attempt and also control header sending. EFalse sends full headers, ETrue only sends name and size.
1.167 + */
1.168 +
1.169 + IMPORT_C CObexServerSendOperation(TUid aMsgTypeUid, CMsvServerEntry& aSendObj, TInt aConnectTimeoutMicroSeconds,
1.170 + TInt aPutTimeoutMicroSeconds, TRequestStatus& aObserverRequestStatus,
1.171 + TBool aLastSendAttempt);
1.172 +
1.173 + /**
1.174 + * Tells the derived class that the base class is about to complete the observer.
1.175 + * This is the first thing called when CompleteObserver is called.
1.176 + * Since the behaviour of CompleteObserver is to clean up the message that it was trying to send,
1.177 + * this calls gives the derived class an opportunity to either stop this deletion or recover any information
1.178 + * synchronously from the message.
1.179 + * If the derived class has no need to use this functionality, the default implementation allows deletion.
1.180 + * @param aErrorCode The last error code encountered
1.181 + * @return TBool True delete the message
1.182 + * @return TBool False DO NOT delete the message
1.183 + */
1.184 + IMPORT_C virtual TBool CompletingObserver(TInt aErrorCode);
1.185 +
1.186 +public: // called by CObexSendOpTimeout
1.187 +
1.188 + /**
1.189 + * Called when the current operation times out. Causes the current operation to be cancelled, then reactivates with
1.190 + * the appropriate error code (KErrIrObexClientNoDevicesFound or KErrIrObexClientPutPeerAborted).
1.191 + */
1.192 +
1.193 + void TimeOut();
1.194 +
1.195 +public:
1.196 +
1.197 + /**
1.198 + * Returns current progress information.
1.199 + *
1.200 + * @return A reference to a TPckgC<TObexMtmProgress> package pointer descriptor containing progress information on this send operation.
1.201 + * @leave KErrXXX system wide error codes
1.202 + */
1.203 + IMPORT_C const TDesC8& ProgressL();
1.204 +
1.205 + TBool iAsyncInit;
1.206 +
1.207 +private: // From MObexAuthChallengeHandler
1.208 +
1.209 + /**
1.210 + * Called by the Obex Client when authentication is requested to pass the password back. If the password is invalid, this
1.211 + * call should succeed but the send operation as a whole will inevitably fail.
1.212 + *
1.213 + * @param aRelm ignored, but could be used to indicate which password to use.
1.214 + * @leave KErrXXX system wide error codes. Shouldn't leave just because the password is invalid.
1.215 + */
1.216 +
1.217 + IMPORT_C virtual void GetUserPasswordL(const TDesC& aUserID);
1.218 +
1.219 +private: // From CActive
1.220 +
1.221 +
1.222 + /**
1.223 + * Calls RealRunL(), and traps errors
1.224 + *
1.225 + * @leave Leaves with errors from RealRunL()
1.226 + */
1.227 +
1.228 + IMPORT_C virtual void RunL();
1.229 +
1.230 +private:
1.231 +
1.232 + /**
1.233 + * Destructor. Cancel()s, deletes owned objects and Close()s the connection to the FileServer.
1.234 + */
1.235 +
1.236 + void BuildSpecificDestructor();
1.237 +
1.238 + /**
1.239 + * Normal second phase constructor.
1.240 + */
1.241 +
1.242 + void BuildSpecificConstructL();
1.243 +
1.244 + /**
1.245 + * Cancels the current operation, then reactivates with the given error code.
1.246 + *
1.247 + * @param aError Error code to be passed to CompleteSelf.
1.248 + */
1.249 +
1.250 + void ActivateRunLWithError(TInt aError);
1.251 +
1.252 + /**
1.253 + * Cancel any pending obex operation without completing the observer.
1.254 + */
1.255 +
1.256 + void ExplicitCancel(); // Must call this instead of just Cancel(), otherwise the owner of this op will be completed.
1.257 +
1.258 + /**
1.259 + * Complete the observer, reporting any error via the progress. THIS METHOD MUST BE CALLED ONCE ONLY.
1.260 + *
1.261 + */
1.262 +
1.263 + void CompleteObserverL();
1.264 +
1.265 + /**
1.266 + * This causes this active object's request to complete which means
1.267 + * RunL() will be called again if we are active (immediately if there
1.268 + * are no higher priority active objects in the active scheduler).
1.269 + *
1.270 + * @param aError Error to be passed forward to the next step of the state machine
1.271 + */
1.272 +
1.273 + void CompleteSelf(TInt aError);
1.274 +
1.275 + /**
1.276 + * Implementation of the send operation state machine. Progresses as:
1.277 + * Initialise-->Connect-->ConnectAttemptComplete-->SendObject-->(SendNextObject-->)SendComplete-->Disconnected
1.278 + * The SendNextObject state is repeated for each attachment in excess of one.
1.279 + * Also handles UserCancelled and SendError states by CompleteObserver()ing with appropriate error codes.
1.280 + * Leaves will be passed back to RunL and handled there.
1.281 + *
1.282 + * @leave KErrXXX system wide error codes
1.283 + */
1.284 +
1.285 + void RealRunL();
1.286 +
1.287 + /**
1.288 + * Delete the outbox entry as operation has 'completed'.
1.289 + * Will be invisible&InPreparation anyway (MS delete will delete it the next
1.290 + * time it starts).
1.291 + */
1.292 +
1.293 + TInt SynchronousEntryDelete();
1.294 +
1.295 + /**
1.296 + * Load an attachment into the obex sending buffer, and create a new Obex object of name TMsvEntry::iDetails.
1.297 + *
1.298 + * @param aParent Reference to CMsvServerEntry to be sent.
1.299 + * @param aWhichAttachment Zero-based index of attachment to send.
1.300 + * @leave KErrXXX system wide error codes
1.301 + */
1.302 +
1.303 + void InitialiseAttachmentL(CMsvServerEntry& aParent, TInt aWhichAttachment);
1.304 +
1.305 + void LoadFileIntoObjectL(const TDesC& aFileName, const TDesC& aObexName, const TDesC8& aMimeType);
1.306 +
1.307 +
1.308 + /**
1.309 + * Checks the last object was sent correctly, and tries to action appropriate error feedback if not. Only to be called
1.310 + * from ESendObject/ESendNextObject or ESendComplete states.
1.311 + *
1.312 + * @param aStatus Status of last object
1.313 + * @return ETrue if message was OK--EFalse if message failed and this function has taken the necessary action
1.314 + */
1.315 +
1.316 + TBool CheckStatusOfLastObject(TInt aStatus, TObexMtmProgress::TSendState aSendState);
1.317 +
1.318 + /**
1.319 + * Loads the next object to be sent, whether an attachment or a file in the file list.
1.320 + *
1.321 + * @return KErrXXX standard error code
1.322 + * @return KErrNotFound if there were neither attachments nor files in the file list
1.323 + * @leave KErrXXX system wide error codes
1.324 + */
1.325 +
1.326 + TInt PrepareCurrentObjectAndSetStateL();
1.327 +
1.328 + /**
1.329 + * Moves the newly sent message to the global sent items folder, and sets active ready for its completion.
1.330 + *
1.331 + * @leave KErrXXX system wide error codes
1.332 + */
1.333 +
1.334 + void MoveToSentAndSetActiveL();
1.335 +
1.336 + /**
1.337 + * Restores after the message has been moved to the inbox, and marks the message as visible.
1.338 + */
1.339 +
1.340 + void CleanupAfterMovedToSent();
1.341 +
1.342 + /**
1.343 + * Returns a reference to the file session (RFs) of the message
1.344 + *
1.345 + * @return A reference to the file session of the the message
1.346 + */
1.347 +
1.348 + RFs& FileSession();
1.349 +
1.350 +
1.351 +#ifdef __OBEX_SEND_OP_FILE_DEBUG_MODE__
1.352 + /**
1.353 + * Output the obex object to a file in the service folder
1.354 + *
1.355 + * @leave KErrXXX system wide error codes
1.356 + */
1.357 +
1.358 + TInt PutObexObjectToServiceFileL();
1.359 +#endif //__OBEX_SEND_OP_FILE_DEBUG_MODE__
1.360 +
1.361 +protected:
1.362 + CObexClient* iObexClient; ///<The Obex client memeber
1.363 + TBool iLastSendAttempt; // check for second send attempt and also to control header sending
1.364 +
1.365 +private:
1.366 + //From member initialisation list
1.367 + TRequestStatus& iObserverRequestStatus; ///<TRequestStatus for notifying observer (eventually ClientMTM) of completion
1.368 + CMsvServerEntry& iMsvSendParent; ///<The message being sent (i.e. the parent of any attachments being sent)
1.369 + const TInt iConnectTimeout; ///<Connection attempt timeout in microseconds
1.370 + const TInt iPutTimeout; ///<Put attempt timeout in microseconds
1.371 + TBool iCancelWithoutCompleting; ///<Flag to allow cancellation without completing observer
1.372 + TPckgBuf<TObexMtmProgress> iProgressPckg; ///<Progress package buffer
1.373 + const TUid iMtm; ///<UID of this MTM
1.374 +
1.375 +
1.376 + TInt iNextAttachment; ///<Index of next attachment to be sent
1.377 + CObexFileObject* iObexObject; ///<Obex object currently being sent
1.378 + TFileName iSendFile; ///<Filename of the object to be sent--necessary since CObexFileObject does not export its copy
1.379 + CObexSendOpTimeout* iTimeoutTimer; ///<Timeout timer used for various operations
1.380 + HBufC* iConnectPassword; ///<Authentication password
1.381 + TObexMtmProgress::TSendState iSendState; ///<State machine state
1.382 + TInt iAttachmentEntryCount; ///<Number of attachments to send (==0 if iFileNameEntryCount!=0)
1.383 +
1.384 +
1.385 + CMsvOperation* iMoveOperation; ///<Operation to govern the movement of the sccessfully sent message to the sent folder
1.386 + CMsvEntrySelection* iMoveEntrySelection; ///<Entry selection containing the entry to rename
1.387 +
1.388 + TFileName iServicePath; ///<Path of service folder
1.389 + };
1.390 +
1.391 +
1.392 +
1.393 +///////////////////////////////////////////////////////////////////////////////////
1.394 +// CObexSendOpTimeout
1.395 +///////////////////////////////////////////////////////////////////////////////////
1.396 +
1.397 +class CObexSendOpTimeout : public CTimer
1.398 +/**
1.399 +class CObexSendOpTimeout
1.400 +
1.401 +Obex Send Operation Timeout active object:
1.402 +
1.403 +Straightforward active object used for timeout operations by CObexServerSendOperation.
1.404 +
1.405 +@internalComponent
1.406 +@released
1.407 +*/
1.408 + {
1.409 +public:
1.410 +
1.411 + /**
1.412 + *Canonical NewL function, which also sets the owner operation.
1.413 + *
1.414 + *@param aSendOperation Obex send operation which will be "timed out" when the timer expires
1.415 + */
1.416 +
1.417 + static CObexSendOpTimeout* NewL(CObexServerSendOperation* aSendOperation);
1.418 +private:
1.419 +
1.420 + /**
1.421 + * Constructor. Calls CTimer's constructor with priority EPriorityStandard
1.422 + */
1.423 +
1.424 + CObexSendOpTimeout();
1.425 +
1.426 + /**
1.427 + * Second phase constructor. Calls CTimer::ConstructL(), and adds itself to the active scheduler
1.428 + *
1.429 + * @leave KErrXXX system wide error codes
1.430 + */
1.431 +
1.432 + void ConstructL();
1.433 +
1.434 + /**
1.435 + * Calls the TimeOut method of the associated CObexServerSendOperation when the timer expires
1.436 + *
1.437 + * @leave KErrXXX system wide error codes
1.438 + */
1.439 +
1.440 + void RunL();
1.441 +private:
1.442 + CObexServerSendOperation* iSendOperation; ///<The Obex server send operation
1.443 + };
1.444 +
1.445 +
1.446 +#endif // __OBEXSENDOP_H__