/*
* 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