/*

* 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