--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ncdengine/engine/inc/catalogsclientserverasynctask.h Tue Jan 26 12:06:03 2010 +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 <e32base.h>
+
+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<TInt> iIntegerHandleBuf;
+
+ /**
+ * Package that is used to send function-number
+ */
+ TPckgBuf<TInt> 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