/*

* Copyright (c) 2003 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:  Outgoing transaction handling interface.

*                Defines a protocol between Presence Engine server

*                and concrete transaction handlers to generate outgoing

*                XML to network and process the responce.

*

*/

#ifndef __MPENGOUTGOINGTRANSACTIONHANDLER_H__

#define __MPENGOUTGOINGTRANSACTIONHANDLER_H__

//  INCLUDES

#include <E32Std.h>

// FORWARD DECLARATIONS

class CPEngTransactionStatus;

// CLASS DECLARATION

/**

 * Outgoing transaction handling interface.

 *

 * Defines a protocol between Presence Engine server

 * and concrete transaction handlers to generate outgoing

 * XML to network and process the response.

 *

 * Methods are listed here in their "calling order".

 *

 * @since 3.0

 */

class MPEngOutgoingTransactionHandler

    {

    public: // New functions

        /**

         *	Synchronous method, get Outgoing transaction request

         *

         *	This method is called to generate a outgoing XML request

         *	for the presence network server

         *	request is no further processed and it is send to network

         *

         *  @since 3.0

         *  @param aSendBuffer The send buffer to write XML request.

         *        Buffer has the maximum send buffer size available.

         *        Handler is responsible to divide too big requests

         *        to smaller partitions, that fit into available

         *        send buffer. In case of separation, handler must

         *        utilize incremental sending, see method

         *        OutgoingTransactionComplete().

         */

        virtual void RequestL( TDes8& aSendBuffer ) = 0;

        /**

         *	Signals to the transaction handler thst it is last

         *	active transaction handler in the scope of the client request

         *

         *	This function is called by the transaction handler runner

         *	when there is no more running transaction handler in

         *	the scope of one client request, same as this transaction

         *	handler is running.

         *	However Request handler can still multiply itself

         *	or continue running in loops as single instance.

         *

         *	@since 3.0

         */

        virtual void LastRunningTransactionHandler( ) = 0;

        /**

         *	Process the response to the request.

         *

         *	This method is called to process XML request response

         *	from network server.

         *	Request can be processed either in synchronous way

         *	there passed TRequestStatus is not touched by the handler

         *	or when state is changed to pending, and handler will not be

         *	deleted till its completion.

         *

         *

         *	@since 3.0

         *	@param aResponse buffer containing XML request response

         *	@param aStatus status where transaction signals completion

         */

        virtual void ProcessResponseL( const TDesC8& aResponse,

                                       TRequestStatus& aStatus ) = 0;

        /**

         *	Cancels asynchronous processing of the request

         *

         *	When processing of the request is not asynchronous

         *	this function does nothing

         *

         *  @since 3.0

         *  @param

         *  @return

         */

        virtual void CancelProcessing( ) = 0;

        /**

         *	Support for simultaneous transaction handling.

         *

         *	This method is called by the transaction handler

         *	runner to ask if there is need to created extra

         *	transaction handlers which will be run separately but

         *	still withing the scope of the clients request this

         *	request handler is belonging.

         *

         *  @since 3.0

         *	@param aTransactionsArray Reference to the pointer array

         *        where new transaction handlers can be stored.

         */

        virtual void NewTransactionHandlersL(

            RPointerArray<MPEngOutgoingTransactionHandler>& aHandlers ) = 0;

        /**

         *	Function to signal completing of the transaction

         *

         *	Runner of the transaction handler is using this function

         *	to check if handler needs to send another data to the

         *	network server.

         *	It is called one processing of the request response is

         *	finished.

         *

         *  @since 3.0

         *  @param

         *  @return ETrue if transaction is completed and does not need

         *		to create any new request

         */

        virtual TBool TransactionCompleted( ) = 0;

        /**

         *	Gets transaction status result class

         *

         *	Transaction handler returns instance of the transaction

         *	status class where are details about finished transaction.

         *	This function is called once transaction handler is completed

         *	Ownership is transfered to the caller

         *

         *  @since 3.0

         *  @return instance of the transaction status with ownership

         */

        virtual CPEngTransactionStatus* TransactionResult( ) = 0;

        /**

         *	Releases handler

         *

         *	This function is called when some Symbian system error will

         *	occur, so handler has chance to do cleaning if this is

         *	needed.

         *	This function is called when for example processing of the

         *	incoming date failed and left with some error

         *	It is also called  when send data to network failed

         *	How ever, handle is not informed about particular error

         *	and its not event its concern

         *

         *  @since 3.0

         */

        virtual void ReleaseHandler( ) = 0;

    public:  //Destructor

        /**

         * Virtual inline destructor.

         *

         * Concrete transaction handlers can be

         * destroyed using this inteface.

         */

        virtual ~MPEngOutgoingTransactionHandler() {};

    };

#endif      //  __MPENGOUTGOINGTRANSACTIONHANDLER_H__

//  End of File