diff -r 000000000000 -r ba25891c3a9e ncdengine/engine/inc/catalogsclientserverasynctask.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ncdengine/engine/inc/catalogsclientserverasynctask.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,325 @@ +/* +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* +*/ + + +#ifndef C_CATALOGS_CLIENT_SERVER_ASYNC_TASK_H +#define C_CATALOGS_CLIENT_SERVER_ASYNC_TASK_H + +#include + +class RCatalogsClientServerClientSession; + +/** + * Class which handles tasks related to transfer of a asynchronous + * message. The most important function related to this is to + * keep a package-object alive when a return message is expected. + * + * + * @lib ?library + * @since S60 ?S60_version *** for example, S60 v3.0 + */ +class CCatalogsClientServerAsyncTask : public CActive + { + + +public: + + + /** + * @enumtype TClientServerAsyncTaskState + * + * @description The state of the asynchronous task that handles + * asynchronous message sending and receiving within + * ClientServer. + * @value ENoRequestsPending No task set. + * @value ECreateProviderRequest Task is handling provider creation. + * @value EAsyncMessageSendRequest Task is handling asynchronous message + * sending. + * @value EAsyncAllocMessageSendRequest Task is handling asynchronous + * message sending with return + * buffer's automatic allocation. + * @value EAsyncAllocCompleteMessageRequest Task is currently handling + * retrieval of incomplete + * message from the server side + * because originally allocated + * return buffer was too small + * and it had to be reallocated. + */ + enum TClientServerAsyncTaskState + { + ENoRequestsPending, + ECreateProviderRequest, + EAsyncMessageSendRequest, + EAsyncAllocMessageSendRequest, + EAsyncAllocCompleteMessageRequest + }; + + static CCatalogsClientServerAsyncTask* NewL( + RCatalogsClientServerClientSession& aSession ); + + static CCatalogsClientServerAsyncTask* NewLC( + RCatalogsClientServerClientSession& aSession ); + + virtual ~CCatalogsClientServerAsyncTask(); + + /** + * Function to handle asynchronous provider creation + * + * @since S60 ?S60_version + * @param aUid Uid of the provider that should be created. + * (integer containing a hexadecimal number) + * @param aStatus A request status which indicates the + * completion status of the asynchronous call + * @param aHandle a reference to an integer that holds + * the provider message handle after the + * asynchronous function call completes + * (i.e. used to return the handle.) + * @param aOptions Provider options + * + * @return Error code to tell whether the test succeeded or not. + */ + void CreateProvider( + TInt aUid, + TRequestStatus& aStatus, + TInt& aHandle, + TUint32 aOptions ); + + /** + * Function to send basic asynchronous message to a + * receiver on the server-side. + * + * @since S60 ?S60_version + * @param aFunction Integer for receiver usage. + * @param aInput Input data that should be sent. + * @param aOutput Descriptor for data returning purpose. + * @param aHandle An integer that identifies receiver. + * @param aStatus A request status which indicates the + * completion status of the asynchronous call. + */ + void SendAsync( TInt aFunction, + const TDesC8& aInput, + TDes8& aOutput, + TInt aHandle, + TRequestStatus& aStatus ); + + /** + * Function to send asynchronous message to a receiver on the + * server-side. Needed buffer for return message is allocated. + * + * @since S60 ?S60_version + * @param aFunction Integer for receiver usage. + * @param aInput Input data that should be sent. + * @param aOutput Reference to descriptor pointer which is used to + * return a pointer to allocated return buffer. + * @param aHandle An integer that identifies receiver. + * @param aStatus A request status which indicates the + * completion status of the asynchronous call. + * @param aLength Expected length of the return message. + */ + void SendAsyncAlloc( TInt aFunction, + const TDesC8& aInput, + HBufC8*& aOutput, + TInt aHandle, + TRequestStatus& aStatus, + TInt aLength ); + + /** + * Getter for pointer to the sender's TRequestStatus. + * + * @since S60 ?S60_version + * @return TRequestStatus of the sender. NULL if the sender info + * is not available anymore. (for example SenderDown has + * been called) + */ + TRequestStatus* SendersRequestStatus() const; + + /** + * Informs this task that the sender is going down. + * Message send (with aStatus given in send functions) + * is completed immediately with KErrCancel. After this + * the asyncTask waits for the completion of the server side + * message. When the task receives message completion the + * task is silently deleted. + * + * @since S60 ?S60_version + */ + void SenderDown(); + +protected: + +// from base class CActive + + /** + * From CActive. + * Handles request completion. + * + * @since S60 ?S60_version + * @param ?arg1 ?description + */ + void RunL(); + + /** + * From CActive. + * Cancels outstanding request. + * + * @since S60 ?S60_version + * @param ?arg1 ?description + */ + void DoCancel(); + + +private: + + CCatalogsClientServerAsyncTask( + RCatalogsClientServerClientSession& aSession ); + void ConstructL(); + + /** + * Function that cleans up some generally used member variables + * and informs that this task is not used anymore. + * + * @since S60 ?S60_version + */ + void GeneralCleanAndComplete(); + + /** + * Function that cleans up member variables needed in + * asyncalloc. Also does GeneralCleanAndComplete. + * Completes with given error. + * + * @since S60 ?S60_version + * @param aError Error code that is used when completing send. + */ + void CompleteAllocWithError( TInt aError ); + + /** + * Function that does needed tasks after asynchronous message + * with return message allocation has been sent and completed. + * + * @since S60 ?S60_version + */ + void HandleAllocMessageComplete(); + + /** + * Function that does needed tasks after asynchronous message + * with return message allocation has been reallocated, + * sent and completed. + * + * @since S60 ?S60_version + */ + void HandleReallocMessageComplete(); + + /** + * Function that sets the given pointer to be the return pointer + * used to return messages from the asyncAlloc message transfer. + * In other words writes into pointer reference given by sender + * the pointer received as a parameter. If the sender is already + * down does not write the return pointer. + * + * @since S60 ?S60_version + * @param aBufferForReturn Pointer to buffer that should be used + * for returning purposes. + */ + void SetAllocReturnPointer( HBufC8* aBufferForReturn ); + +private: // data + + + /** + * Variable to keep track of the state of this object + */ + TClientServerAsyncTaskState iState; + + /** + * Tells whether the original sender of the message still + * exists and message sending can be completed. + */ + TBool iSenderDown; + + /** + * Session that is used to perform needed tasks + */ + RCatalogsClientServerClientSession& iSession; + + /** + * This is used to inform client that the message transfer has + * been completed. + * Not own. + */ + TRequestStatus* iClientStatus; + + /** + * Pointer for handle returning purpose + * Not own. + */ + TInt* iReturnHandle; + /** + * Package that is used to send to and receive handle + * value from the server. Used in external and internal + * messages of ClientServer. So this does not always + * contain handle of the original receiver object. + */ + TPckgBuf iIntegerHandleBuf; + + /** + * Package that is used to send function-number + */ + TPckgBuf iIntegerFunctionBuf; + + /** + * TIpcArgs for message transportation needs. + */ + TIpcArgs iArgs; + + + // Variables for message returning purposes + + /** + * Pointer to a descriptor that is given by the sender. + * This is used to return message when using asynchronous + * messaging. + * Not own. + */ + TDes8* iReturnPointer; + + /** + * Pointer to a descriptor pointer that is given by the sender. + * This is used to return allocated return message when using + * asynchronous messaging with return buffer allocation. + * Not own. + */ + HBufC8** iAllocReturnPointer; + + + // Temporary variables which are used in asynchronous communication + // and message returning from the server side. + + /** + * Pointer to created buffer which is sent to server-side + * to retrieve a return message. + * Own. + */ + HBufC8* iTempReturnBuf; + /** + * Modifiable version of iTempReturnBuf. + */ + TPtr8 iTempWritableReturnBuf; + + }; + + +#endif // C_CATALOGS_CLIENT_SERVER_ASYNC_TASK_H