1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 

    17 #ifndef __OBEXSENDOP_H__

    18 #define __OBEXSENDOP_H__

    19 

    20 

    21 

    22 //#define __OBEX_SEND_OP_FILE_DEBUG_MODE__

    23 

    24 #include <msvapi.h>

    25 #include <badesca.h> // CDesCArray

    26 #include <obex.h>

    27 #include <obexclientmtm.h>	//TObexMtmProgress

    28 

    29 

    30 class CObexHeaderList;

    31 

    32 

    33 //

    34 // Panic Code

    35 //

    36 

    37 //Obex Send Operation Panics

    38 enum TObexSendOperationPanic

    39 	{

    40 	EObexSendOperationAlreadyActive, //< The current Obex send operation is already active

    41 	EObexSendOperationUnknownJob, //<

    42 	EObexSendOperationUnknownSendState, //< The current value of the Obex send state of the send operation is not found in TObexMtmProgress::TSendState

    43 	EObexSendOperationUnexpectedTimeout //< Panic if send has timeout unexpectedly

    44 	};

    45 

    46 GLDEF_C void Panic(TObexSendOperationPanic aPanic);

    47 

    48 

    49 

    50 //

    51 // CObexServerSendOperation 

    52 //

    53 class CObexSendOpTimeout;

    54 class CObexPasswordGetter;

    55 

    56 class CObexServerSendOperation : public CActive, public MObexAuthChallengeHandler

    57 /**

    58 class CObexServerSendOperation

    59 

    60 Obex Server Send Operation:

    61 

    62 Base class for Send operations using Obex protocol.

    63 

    64 Implements a state machine with the following states:

    65 Initialise-->Connect-->ConnectAttemptComplete-->SendObject-->(SendNextObject-->)SendComplete-->MovedToSent-->Disconnected

    66 

    67 The pure virtual function InitialiseObexClientL() must be overridden in the base class to initialise the

    68 iObexClient member to use the desired Obex transport mechanism (e.g. infrared, Bluetooth).

    69 

    70 In order to allow asynchronous transport initialisations (for example BT's SDP Query)

    71 implementations of this function must set iAsyncInit and provide a mechanism to 

    72 complete a request.  See the bluetooth server mtm code for implementation details.

    73  

    74 @internalTechnology

    75 @released

    76 */

    77 	{

    78 public:

    79 	

    80 	/**

    81 	 * Destructor. Cancel()s, deletes owned objects and Close()s the connection to the FileServer.

    82 	 */

    83 	

    84 	virtual IMPORT_C ~CObexServerSendOperation();

    85 	

    86 	// Must be implemented in the derived class to initialise the iObexClient member to use the desired Obex transport mechanism

    87 	virtual void InitialiseObexClientL() =0;

    88 	

    89 	/**

    90 	 * This is not required to do anything in the base implementation.

    91 	 */

    92 		

    93 	IMPORT_C virtual void SecondPhaseObexClientInitL();		// may be overridden to do anything required in a second phase.  default implementation is blank.

    94 

    95 	/**

    96 	 * Operations to perform before attempting a connection.

    97 	 * As multiple connection attempts can be made, it is necessary for this

    98 	 * routine to ensure it can handle being called multiple times.

    99 	 * May be overridden. Default implementation is blank.

   100 	 */

   101 	IMPORT_C virtual void PreConnectOperations();

   102 

   103 	/**

   104 	 * Operations to perform after attempting a connection.

   105 	 * As multiple connection attempts can be made, it is necessary for this

   106 	 * routine to ensure it can handle being called multiple times.

   107 	 * May be overridden. Default implementation is blank.

   108 	 */

   109 	IMPORT_C virtual void PostConnectOperations();

   110 

   111 	/**

   112 	 * Operations to perform before attempting to send a set of objects.

   113 	 * May be overridden. Default implementation is blank.

   114 	 */

   115 	IMPORT_C virtual void PreSendOperations();

   116 

   117 	/**

   118 	 * Operations to perform after attempting to send a set of objects.

   119 	 * May be overridden. Default implementation is blank.

   120 	 */

   121 	IMPORT_C virtual void PostSendOperations();

   122 

   123 

   124 protected: // for use by derived classes

   125 	/**

   126 	 * Constructor.

   127 	 *

   128 	 * @param aMsgTypeUid UID of message type

   129 	 * @param aSendObj Reference to the object to send.

   130 	 * @param aConnectTimeoutMicroSeconds Timeout period for Connect operation in microseconds.

   131 	 * @param aPutTimeoutMicroseconds Timeout period for Put operation in microseconds.

   132 	 * @param aObserverRequestStatus TRequestStatus of owning active object.

   133 	 */

   134 	

   135 	IMPORT_C CObexServerSendOperation(TUid aMsgTypeUid, CMsvServerEntry& aSendObj, TInt aConnectTimeoutMicroSeconds, TInt aPutTimeoutMicroSeconds, TRequestStatus& aObserverRequestStatus);

   136 	

   137 	/**

   138 	 * Second phase constructor. Sets up connection to the FileServer, initialises attachments or filename list then 

   139 	 * starts sending process by initialising.

   140 	 *

   141 	 * @param aConnectPassword Pointer to the password to be used for authentication.

   142 	 * @leave Leaves if insufficient memory.

   143 	 * @leave Leaves if cannot connect to FileServer.

   144 	 */

   145 	

   146 	IMPORT_C void ConstructL(const TDesC* aConnectPassword);

   147 

   148 	/**

   149 	 * Cancels the current operation, deletes the client and Cancel()s the timeout timer. Only completes the observer

   150 	 * (by a call to CompleteObserver) if an external entity (i.e. the owner) has called Cancel().

   151 	 * Otherwise the observer is not completed.

   152 	 */

   153 	

   154 	IMPORT_C virtual void DoCancel();

   155 

   156 	 /* Constructor, Alternative version

   157 	 *

   158 	 * @param aMsgTypeUid UID of message type

   159 	 * @param aSendObj Reference to the object to send.

   160 	 * @param aConnectTimeoutMicroSeconds Timeout period for Connect operation in microseconds.

   161 	 * @param aPutTimeoutMicroseconds Timeout period for Put operation in microseconds.

   162 	 * @param aObserverRequestStatus TRequestStatus of owning active object.

   163 	 * @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.

   164 	 */

   165 	

   166 	IMPORT_C CObexServerSendOperation(TUid aMsgTypeUid, CMsvServerEntry& aSendObj, TInt aConnectTimeoutMicroSeconds,

   167 	                                  TInt aPutTimeoutMicroSeconds, TRequestStatus& aObserverRequestStatus, 

   168 	                                  TBool aLastSendAttempt);

   169 	

   170 	/**

   171 	* Tells the derived class that the base class is about to complete the observer.

   172 	* This is the first thing called when CompleteObserver is called.

   173 	* Since the behaviour of CompleteObserver is to clean up the message that it was trying to send,

   174 	* this calls gives the derived class an opportunity to either stop this deletion or recover any information

   175 	* synchronously from the message.

   176 	* If the derived class has no need to use this functionality, the default implementation allows deletion.

   177 	* @param aErrorCode The last error code encountered

   178 	* @return TBool True delete the message

   179 	* @return TBool False DO NOT delete the message

   180 	*/

   181 	IMPORT_C virtual TBool CompletingObserver(TInt aErrorCode);

   182 

   183 public: // called by CObexSendOpTimeout

   184 	

   185 	/**

   186 	 * Called when the current operation times out. Causes the current operation to be cancelled, then reactivates with

   187 	 * the appropriate error code (KErrIrObexClientNoDevicesFound or KErrIrObexClientPutPeerAborted).

   188 	 */

   189 	

   190 	void TimeOut();

   191 

   192 public:

   193 	

   194 	/**

   195 	 * Returns current progress information.

   196 	 *

   197 	 * @return A reference to a TPckgC<TObexMtmProgress> package pointer descriptor containing progress information on this send operation.

   198 	 * @leave KErrXXX system wide error codes

   199 	 */

   200 	IMPORT_C const TDesC8& ProgressL();

   201 	

   202 	TBool iAsyncInit;

   203 

   204 private: // From MObexAuthChallengeHandler

   205 

   206 	/**

   207 	 * Called by the Obex Client when authentication is requested to pass the password back. If the password is invalid, this

   208 	 * call should succeed but the send operation as a whole will inevitably fail.

   209 	 *

   210 	 * @param aRelm ignored, but could be used to indicate which password to use.

   211 	 * @leave KErrXXX system wide error codes. Shouldn't leave just because the password is invalid.

   212 	 */

   213 	

   214 	IMPORT_C virtual void GetUserPasswordL(const TDesC& aUserID);

   215 

   216 private: // From CActive

   217 	

   218 	

   219 	/**

   220 	 * Calls RealRunL(), and traps errors

   221 	 *

   222 	 * @leave Leaves with errors from RealRunL()

   223 	 */

   224 	

   225 	IMPORT_C virtual void RunL();

   226 

   227 private:

   228 

   229 	/**

   230 	 * Destructor. Cancel()s, deletes owned objects and Close()s the connection to the FileServer.

   231 	 */

   232 	

   233 	void BuildSpecificDestructor();

   234 	

   235 	/**

   236 	 * Normal second phase constructor.

   237 	 */

   238 	

   239 	void BuildSpecificConstructL();

   240 	

   241 	/**

   242 	 * Cancels the current operation, then reactivates with the given error code.

   243 	 *

   244 	 * @param aError Error code to be passed to CompleteSelf.

   245 	 */

   246 	

   247 	void ActivateRunLWithError(TInt aError);

   248 	

   249 	/**

   250 	 * Cancel any pending obex operation without completing the observer. 

   251 	 */

   252 

   253 	void ExplicitCancel();  // Must call this instead of just Cancel(), otherwise the owner of this op will be completed.

   254 	

   255 	/**

   256 	 * Complete the observer, reporting any error via the progress. THIS METHOD MUST BE CALLED ONCE ONLY.

   257 	 *

   258 	 */

   259 	

   260 	void CompleteObserverL();

   261 	

   262 	/**

   263 	 * This causes this active object's request to complete which means

   264 	 * RunL() will be called again if we are active (immediately if there 

   265 	 * are no higher priority active objects in the active scheduler).

   266 	 *

   267 	 * @param aError Error to be passed forward to the next step of the state machine

   268 	 */

   269 	

   270 	void CompleteSelf(TInt aError);

   271 

   272 	/**

   273 	 * Implementation of the send operation state machine. Progresses as:

   274 	 * Initialise-->Connect-->ConnectAttemptComplete-->SendObject-->(SendNextObject-->)SendComplete-->Disconnected

   275 	 * The SendNextObject state is repeated for each attachment in excess of one. 

   276 	 * Also handles UserCancelled and SendError states by CompleteObserver()ing with appropriate error codes.

   277 	 * Leaves will be passed back to RunL and handled there. 

   278 	 *

   279 	 * @leave KErrXXX system wide error codes

   280 	 */

   281 	

   282 	void RealRunL();

   283 	

   284 	/**

   285 	 * Delete the outbox entry as operation has 'completed'.

   286 	 * Will be invisible&InPreparation anyway (MS delete will delete it the next 

   287 	 * time it starts).

   288 	 */

   289 	

   290 	TInt SynchronousEntryDelete();

   291 	

   292 	/**

   293 	 * Load an attachment into the obex sending buffer, and create a new Obex object of name TMsvEntry::iDetails.

   294 	 *

   295 	 * @param aParent Reference to CMsvServerEntry to be sent.

   296 	 * @param aWhichAttachment Zero-based index of attachment to send.

   297 	 * @leave KErrXXX system wide error codes

   298 	 */

   299 	

   300 	void InitialiseAttachmentL(CMsvServerEntry& aParent, TInt aWhichAttachment);

   301 	

   302 	void LoadFileIntoObjectL(const TDesC& aFileName, const TDesC& aObexName, const TDesC8& aMimeType);

   303 

   304 

   305 	/**

   306 	 * Checks the last object was sent correctly, and tries to action appropriate error feedback if not. Only to be called

   307 	 * from ESendObject/ESendNextObject or ESendComplete states. 

   308 	 *

   309 	 * @param aStatus Status of last object

   310 	 * @return ETrue if message was OK--EFalse if message failed and this function has taken the necessary action

   311 	 */

   312 

   313 	TBool CheckStatusOfLastObject(TInt aStatus, TObexMtmProgress::TSendState aSendState);

   314 	

   315 	/**

   316 	 * Loads the next object to be sent, whether an attachment or a file in the file list.

   317 	 *

   318 	 * @return KErrXXX standard error code

   319 	 * @return KErrNotFound if there were neither attachments nor files in the file list

   320 	 * @leave KErrXXX system wide error codes

   321 	 */

   322 	

   323 	TInt PrepareCurrentObjectAndSetStateL();

   324 	

   325 	/**

   326 	 * Moves the newly sent message to the global sent items folder, and sets active ready for its completion.

   327 	 *

   328 	 * @leave KErrXXX system wide error codes

   329 	 */

   330 	

   331 	void MoveToSentAndSetActiveL();

   332 	

   333 	/**

   334 	 * Restores after the message has been moved to the inbox, and marks the message as visible.

   335 	 */

   336 

   337 	void CleanupAfterMovedToSent();

   338 	

   339 	/**

   340 	 * Returns a reference to the file session (RFs) of the message

   341 	 *

   342 	 * @return A reference to the file session of the the message 

   343 	 */

   344 

   345 	RFs& FileSession();

   346 

   347 

   348 #ifdef __OBEX_SEND_OP_FILE_DEBUG_MODE__

   349 	/**

   350 	 * Output the obex object to a file in the service folder

   351 	 *

   352 	 * @leave KErrXXX system wide error codes

   353 	 */

   354 	

   355 	TInt PutObexObjectToServiceFileL();

   356 #endif	//__OBEX_SEND_OP_FILE_DEBUG_MODE__

   357 

   358 protected: 

   359 	CObexClient* iObexClient; //<The Obex client memeber

   360 	TBool        iLastSendAttempt;	// check for second send attempt and also to control header sending

   361 

   362 private:

   363 	//From member initialisation list

   364 	TRequestStatus&					iObserverRequestStatus;		//<TRequestStatus for notifying observer (eventually  ClientMTM) of completion

   365 	CMsvServerEntry&				iMsvSendParent;				//<The message being sent (i.e. the parent of any attachments being sent)

   366 	const TInt						iConnectTimeout;			//<Connection attempt timeout in microseconds

   367 	const TInt						iPutTimeout;				//<Put attempt timeout in microseconds

   368 	TBool							iCancelWithoutCompleting;	//<Flag to allow cancellation without completing observer

   369 	TPckgBuf<TObexMtmProgress>		iProgressPckg;				//<Progress package buffer

   370 	const TUid						iMtm;						//<UID of this MTM

   371 

   372 

   373 	TInt							iNextAttachment;			//<Index of next attachment to be sent

   374 	CObexFileObject*				iObexObject;				//<Obex object currently being sent

   375 	TFileName						iSendFile;					//<Filename of the object to be sent--necessary since CObexFileObject does not export its copy

   376 	CObexSendOpTimeout*				iTimeoutTimer;				//<Timeout timer used for various operations

   377 	HBufC*							iConnectPassword;			//<Authentication password 

   378 	TObexMtmProgress::TSendState	iSendState;					//<State machine state

   379 	TInt							iAttachmentEntryCount;		//<Number of attachments to send (==0 if iFileNameEntryCount!=0)

   380 

   381 

   382 	CMsvOperation*					iMoveOperation;				//<Operation to govern the movement of the sccessfully sent message to the sent folder

   383 	CMsvEntrySelection*				iMoveEntrySelection;		//<Entry selection containing the entry to rename

   384 

   385 	TFileName						iServicePath;				//<Path of service folder

   386 	};

   387 

   388 

   389 

   390 //

   391 // CObexSendOpTimeout 

   392 //

   393 

   394 class CObexSendOpTimeout : public CTimer

   395 /**

   396 class CObexSendOpTimeout

   397 

   398 Obex Send Operation Timeout active object:

   399 

   400 Straightforward active object used for timeout operations by CObexServerSendOperation.

   401 

   402 @internalComponent

   403 @released

   404 */

   405   	{

   406 public:

   407 	

   408 	/**

   409 	 *Canonical NewL function, which also sets the owner operation.

   410 	 *

   411 	 *@param aSendOperation Obex send operation which will be "timed out" when the timer expires

   412 	 */

   413 

   414 	static CObexSendOpTimeout* NewL(CObexServerSendOperation* aSendOperation);

   415 private:

   416 	

   417 	/**

   418 	 * Constructor. Calls CTimer's constructor with priority EPriorityStandard

   419 	 */

   420 

   421 	CObexSendOpTimeout();

   422 	

   423 	/**

   424 	 * Second phase constructor. Calls CTimer::ConstructL(), and adds itself to the active scheduler

   425 	 *

   426 	 * @leave KErrXXX system wide error codes

   427 	 */

   428 	

   429 	void ConstructL();

   430 	

   431 	/**

   432 	 * Calls the TimeOut method of the associated CObexServerSendOperation when the timer expires

   433 	 *

   434 	 * @leave KErrXXX system wide error codes

   435 	 */

   436 	

   437 	void RunL();

   438 private:

   439 	CObexServerSendOperation* iSendOperation; //<The Obex server send operation

   440 	};

   441 

   442 

   443 #endif // __OBEXSENDOP_H__