/*

* Copyright (c) 2006-2009 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:

* Name          : MTransactionUser.h

* Part of       : TransactionUser

* Version       : SIP/6.0

*

*/

/**

 @internalComponent

*/

#ifndef MTRANSACTIONUSER_H

#define MTRANSACTIONUSER_H

// INCLUDES

#include "SipStackServerDefs.h"

#include <in_sock.h>

// FORWARD DECLARATIONS

class CSIPRequest;

class CSIPResponse;

class CURIContainer;

class MTransactionOwner;

class MTransactionHeaders;

class TSIPTransportParams;

class MSIPNATBindingObserver;

// CLASS DECLARATION

/**

 * Transaction user interface for sending SIP messages, retrieving state of a

 * particular transaction and detaching from transaction.

 */

class MTransactionUser

	{

public:

	enum TRandomStringLength

		{

		// Amount of characters in a To/From header's tag when TransactionUser

		// creates it

		KTagLength = 20,

		// Amount of characters in a Call-ID when TransactionUser creates it

		KCallIDLength = 30

		};

	virtual ~MTransactionUser() {}

	/**

	 * Send a SIP request message. In case of error, function leaves and 

	 * the ownership of the SIP Request isn't transferred.

	 *

	 * @pre aRequest!=NULL

	 * @pre aObserver!=NULL

	 *

	 * @param aTransactionId   IN: If the request is ACK, this parameter should

     *                         be a TransactionId of the INVITE transaction.

	 *						   OUT: If the request is not ACK, a new transaction

	 *						   is created and its TransactionId is filled here.

	 * @param aRegistrationId  IN: a registration id by which TU tries to find

	 *                         an outbound proxy for the request.

	 * @param aRequest	       IN: SIP request message. Ownership is transferred.

	 * @param aObserver		   IN: Callback where the transaction will send

	 *						   events. Ownership isn't transferred.	 

	 * @param aRemoteTarget    IN: Remote target of the request.

     * @param aTransportParams IN: Transport parameters to be used when handing

     *                         the request to SIP Connection Mgr.

	 * @param aDeleteRequest   If ETrue, TransactionUser will delete aRequest

	 *						   when the transaction ends. If EFalse, aRequest is

	 *						   not deleted by TransactionUser.

	 */

	virtual void SendL (TTransactionId& aTransactionId,

	                    TRegistrationId aRegistrationId,

					    CSIPRequest* aRequest,

					    MTransactionOwner* aObserver,

						CURIContainer& aRemoteTarget,

                        const TSIPTransportParams& aTransportParams,

					    TBool aDeleteRequest) = 0;

	/**

	 * Send a SIP request message. In case of error, function leaves and 

	 * the ownership of the SIP Request isn't transferred.

	 *

	 * @pre aRequest!=NULL

	 * @pre aObserver!=NULL

	 *

	 * @param aTransactionId   IN: If the request is ACK, this parameter should

     *                         be a TransactionId of the INVITE transaction.

	 *						   OUT: If the request is not ACK, a new transaction

	 *						   is created and its TransactionId is filled here.

	 * @param aRegistrationId  IN: a registration id by which TU tries to find

	 *                         an outbound proxy for the request.

	 * @param aRequest	       IN: SIP request message. Ownership is transferred.

	 * @param aObserver		   IN: Callback where the transaction will send events.

	 *						   Ownership isn't transferred.

	 * @param aRemoteTarget    IN: Remote target of the request.

     * @param aTransportParams IN: Transport parameters to be used when handing

     *                         the request to SIP Connection Mgr.

	 * @param aDeleteRequest   If ETrue, TransactionUser will delete aRequest

	 *						   when the transaction ends. If EFalse, aRequest is

	 *						   not deleted by TransactionUser.

	 * @returns                A pointer to copies of transaction related headers

	 *                         stored and possibly created by transactions.

	 *                         The ownership is transferred.

	 */

	virtual MTransactionHeaders*

        SendAndGetHeadersL (TTransactionId& aTransactionId,

		                    TRegistrationId aRegistrationId,

	                        CSIPRequest* aRequest,

	                        MTransactionOwner* aObserver,

					        CURIContainer& aRemoteTarget,

                            const TSIPTransportParams& aTransportParams,

                            TBool aDeleteRequest) = 0;

	/**

	 * Send a SIP response message, using an existing transaction.

	 * Fills From- and To-header and other transaction related headers

	 * if they are missing. In case of error, function leaves and

	 * the ownership of aResponse is NOT transferred.

	 *

	 * @pre transaction identified by aTransactionId exists,

	 * @pre aResponse!=NULL

	 *

	 * @param aTransactionId   Identifies the transaction

	 * @param aResponse	       IN: SIP response message.

	 *                         The ownership is transferred.

     * @param aTransportParams IN: Transport parameters to be used when handing

     *                         the response to SIP Connection Mgr.

	 */

	virtual void SendL (TTransactionId aTransactionId,

					    CSIPResponse* aResponse,

					    const TSIPTransportParams& aTransportParams) const = 0;

	/**

	 * Send a SIP response using an existing transaction and specify a new

	 * callback for the transaction to use.

	 * Fills From- and To-header and other transaction related headers

	 * if they are missing. In case of error, function leaves and

	 * the ownership of aResponse is NOT transferred.

	 *

	 * @pre transaction identified by aTransactionId exists

	 * @pre aResponse!=NULL

	 * @pre aNewObserver!=NULL

	 *

	 * @param aTransactionId   Identifies the transaction

	 * @param aResponse		   IN: SIP response message. Ownership transferred.

	 * @param aNewObserver     IN: New callback replacing the existing callback

	 *						   used by the the transaction. Ownership isn't

	 *						   transferred.

     * @param aTransportParams IN: Transport parameters to be used when handing

     *                         the response to SIP Connection Mgr.	 

	 */		

	virtual void SendL (TTransactionId aTransactionId,

					    CSIPResponse* aResponse,

					    MTransactionOwner* aNewObserver,

					    const TSIPTransportParams& aTransportParams) const = 0;

	/**

	 * Send a CANCEL request. In case of error, function leaves and 

	 * the ownership of the aCancel isn't transferred. CANCEL can only be sent

	 * when the INVITE client transaction has received a provisional response,

	 * but hasn't yet received a final response.

	 *

	 * @pre aCancel!=NULL

	 * @pre aObserver!=NULL

	 *

	 * @param aInviteTaId	  TransactionId of the INVITE client transaction to

	 *						  be canceled.

	 * @param aCancelTaId	  OUT: TransactionId of the transaction sending

	 *						  CANCEL	 

	 * @param aObserver		  IN: Callback where the CANCEL transaction will

	 *						  send events. Ownership isn't transferred.	 

	 */

	virtual void SendCancelL (TTransactionId aInviteTaId,

							  TTransactionId& aCancelTaId,							  

							  MTransactionOwner* aObserver) = 0;

	/**

	 * The transaction with the specified transaction id clears its

	 * MTransactionOwner callback and won't send any more events.

	 * Transaction won't be stopped prematurely, it runs silently to completion.

	 *

	 * This function doesn't leave in case of error, as it is thought this

	 * function is usually also called from destructors.

	 *	 

	 * @pre aTransactionId != KSIPEmptyTransactionId

	 *

	 * @param aTransactionId Identifies the transaction	 

	 * @returns KErrNone if successful

	 *          KErrNotFound if no such transaction exists

	 */	

	virtual TInt

        ClearTransactionOwner (TTransactionId aTransactionId) const = 0;

	/**

	 * Transactions using the specified callback clear their MTransactionOwner

     * callback and won't send any more events.

	 * Transactions won't be stopped prematurely, they run silently to

	 * completion.

	 *

	 * This function doesn't leave in case of error, as it is thought this

	 * function is usually also called from destructors.

	 *

	 * @pre aObserver != NULL

	 *

	 * @param aObserver	IN: Callback address. Ownership isn't transferred.

	 * @returns KErrNone if successful

	 *          KErrNotFound if no such transaction exists

	 */

	virtual TInt ClearTransactionOwner (MTransactionOwner* aObserver) const = 0;

	/**

	 * Retrieve the transaction related headers of the SIP message that created

	 * the transaction. Leaves if memory allocation for the requested headers

	 * fails.

	 *

	 * @param aTransactionId the transaction whose SIP headers are requested.

	 *

	 * @returns NULL if no such transaction exists,

	 *          otherwise an object implementing MTransactionHeaders interface,

	 *          that contains copies of the transaction related SIP headers.

	 *          Ownership is transferred.

	 */

	virtual MTransactionHeaders*

        TransactionHeadersL (TTransactionId aTransactionId) const = 0;

	/**

	 * Fills the descriptor with random characters.

	 *

	 * @param aTag Descriptor into which the random characters are added.

	 *        The existing characters are not overwritten.

	 *        Adds as many characters as there is space left in the aTag.

	 */

	virtual void MakeTagL (TDes8& aTag) const = 0;

    /**

 	 * Obtain the local address associated with the given IAP identifier.

	 *

	 * @param aIapId IAP identifier

     * @param aAddr Local address will be written here

	 */

    virtual void GetLocalAddress (TUint32 aIapId, TInetAddr& aAddr) const = 0;

    /**

    * Frees all the resources reserved for the observer.

    * @param aSIPNATBindingObserver a observer

    */

    virtual void

    	FreeResources (MSIPNATBindingObserver& aSIPNATBindingObserver) = 0;

    /**

    * Obtains  the next hop address associated with the given transaction id.

	*

    * @param aTransactionId transaction identifier

	*

    * @param aAddr Local address will be written here

	*

	* @returns nex hop IP

    */

    virtual TInt 

    	NextHopIP(const TTransactionId& aTransactionId, TInetAddr& aAddr) = 0;

	};

#endif // MTRANSACTIONUSER_H

// End of File