/*

* Copyright (c) 2005 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:  This file defines an interface for sending and receiving data

*               from transport module. In other words a transport module must

*               provide the methods defined below and call the observer methods

*               for incoming data.

*

*

*/

#ifndef WV_DATACHANNEL_API_H

#define WV_DATACHANNEL_API_H

// CLASS DECLARATIONS

/**

* MImpsDataReceiver

*

* Abstract interface for handling responses from data channel module.

* Server implements this class and gives a pointer to the data channel.

* Data channel module calls the method when it has received data.

*/

class MImpsDataReceiver

    {

    public: // New functions

        /**

        * Callback for transport request response

        * This handles the responses to the SendL() method from MImpsSender

        *

        * NOTE: It is very important to bear in mind that the memory

        *       area which the fourth parameter points to, MUST be

        *       deallocated by the object that implements this abstract

        *       interface! After the IMPS Data Channel component has

        *       called this method, it is no longer responsible for

        *       maintenance (including deallocation) of this chunk of

        *       heap. Failure to free the memory area will result in

        *       a serious memory leak and, consequently, a crash.

        *       Also note that in many error cases, including a request

        *       timing out, the pointer will be NULL as there is no data

        *       to relay.

        *

        * @param TInt Operation-id given in SendL() method

        * @param TInt Internal error code, KErrNone if successful

        * @param TInt HTTP status code, 200 if successful

        * @param HBufC8* Pointer to the raw eight-bit CSP data;

        *                must be deleted by the implementing class

        *                after its contents are no longer needed

        */

        virtual void TransportResponse( const TInt aId,

                                        const TInt aError,

                                        const TInt aHttpStatus,

                                        HBufC8* aCspMessage ) = 0;

    };

/**

* MImpsSender

*

* Abstract interface for sending messages to the data channel.

* The data channel module implements this class.

*/

//The bearer connection manager used by MImpsSender instances

class MMsgConnManager;

class MImpsSender

    {

    public: // New functions

        /**

         * Opens a session to the HTTP Stack.

         *    - If already opened then error code is returned ( KErrAlreadyExists )

         *    - Leaves with KImpsErrorBearerSuspended if GPRS is suspended

         *    - KErrOutOfMemory if new objects cannot be allocated

         *    (- some other system-wide error code returned by the HTTP framework)

         *

         * This is a synchronous method: after a call to this method, the client

         * application can assume the data channel to be open - provided the

         * method call did not leave.

         *

         * @param aSAP WV SAP.

         *        The address has a format:

         *        hostport [ "/" hpath [ "?" search ]]

         *        Refer to RFC1738

         * @return void

         */

        virtual void OpenL( const TDesC& aSAP ) = 0;

        /**

        * Closes the session to HTTP Stack

        * @return Status code of the performed operation.

        */

        virtual void Close() = 0;

        /**

        * Send a request.

        * When this method returns the data is saved and aMessage

        * parameter can be re-used.

        * If the state of the bearer connection is other than

        * EImpsBearerActive, leaves with an error immediately:

        *   * EImpsBearerLost state - KImpsErrorBearerNotReady

        *   * EImpsBearerSuspended state - KImpsErrorBearerSuspended

        * The function may also leave with KImpsErrorSessionNotOpen

        * in case OpenL() has not been called prior to the call of this method.

        *

        * A response is received through MImpsReceiver.

        * The third parameter, aExpiryTime is optional. The function

        * first checks whether the value is something other than 0. If

        * it is, a timer gets instantiated and activated, and expires

        * according to the value passed in the parameter. The

        * value should be presented in seconds.

        *

        * @param aId operation-id to identify the request.

        * @param aMessage data to be sent

        * @param aExpiryTime expiry time of the request in seconds

        */

        virtual void SendL( const TInt aId,

                            const TDesC8& aMessage,

                            const TInt aExpiryTime = 0 ) = 0;

        /**

        * Destructor. A simple wrapper to the C++ destructor.

        *

        * NOTE that HTTP Stack uses the connection and socket

        * server instances owned by MImpsConnectionManager,

        * so one should be very careful NOT to Destroy() the

        * ConnMan instance before an instance of this interface.

        * At deletion time HTTP Stack might have outstanding socket

        * reads and/or writes, the cancelling of which will surely

        * fail in case the socket session on which the sockets were

        * initially opened has been prematurely closed.

        */

        virtual void Destroy() = 0;

        /**

        * Cancel all pending transactions.

        * After this request it is guaranteed that observer methods

        * are not called until new requests have been made.

        */

        virtual void CancelAll() = 0;

        /**

        * Cancel a named transaction.

        */

        virtual void CancelTransaction( const TInt aTID ) = 0;

        /**

        * Return the number of requests to which

        * a response has not yet been received.

        */

        virtual TInt PendingRequests() const = 0;

    };

/**

* Creates a new sender object

* @param RFs& aSession Reference to an opened file session

* @param TDesC8& aMimeType MIME type of the messages to be sent

* @param MImpsReceiver* aReceiver Pointer to the receiving object

* @return MImpsSender

*/

IMPORT_C MImpsSender* NewImpsSenderL( MImpsDataReceiver& aReceiver,

                                      MMsgConnManager& aConnManager,

                                      const TDesC8& aMimeType );

#endif      // ?INCLUDE_H   

// End of File