diff -r 2fe1408b6811 -r e1b950c65cb4 epoc32/include/mw/sipinvitedialogassoc.h
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/mw/sipinvitedialogassoc.h Wed Mar 31 12:27:01 2010 +0100
@@ -0,0 +1,423 @@
+/*
+* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+* which accompanies this distribution, and is available
+* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+* Name : sipinvitedialogassoc.h
+* Part of : SIP Client
+* Interface : SDK API, SIP Client API
+* Version : 1.0
+*
+*/
+
+
+
+
+#ifndef CSIPINVITEDIALOGASSOC_H
+#define CSIPINVITEDIALOGASSOC_H
+
+// INCLUDES
+#include "sipdialogassocbase.h"
+
+// CONSTANTS
+
+// FORWARD DECLARATIONS
+class CUri8;
+class CSIPConnection;
+class CSIPServerTransaction;
+class CSIPFromHeader;
+class CSIPToHeader;
+class CSIPContactHeader;
+class MSIPRegistrationContext;
+
+// CLASS DECLARATION
+
+/**
+* @publishedAll
+* @released
+*
+* Class for managing SIP dialog association created with INVITE.
+* It provides services for creating, using and
+* terminating SIP INVITE dialog association.
+*
+* The user can have only one INVITE dialog association per dialog.
+*
+* @lib sipclient.lib
+*/
+class CSIPInviteDialogAssoc : public CSIPDialogAssocBase
+ {
+ public: // Constructors and destructor
+
+ /**
+ * Two-phased constructor.
+ * @param aDialog a dialog to be associated with
+ * @return New object, ownership is transferred.
+ */
+ IMPORT_C static CSIPInviteDialogAssoc* NewL(CSIPDialog& aDialog);
+
+ /**
+ * Two-phased constructor.
+ * @param aDialog a dialog to be associated with
+ * @return New object, ownership is transferred.
+ */
+ IMPORT_C static CSIPInviteDialogAssoc* NewLC(CSIPDialog& aDialog);
+
+ /**
+ * Two-phased constructor.
+ * Should be used if response to the received SIP request will create
+ * a SIP dialog association.
+ * The server transaction must be a INVITE transaction.
+ * If SIP server transaction was received within an existing SIP dialog
+ * the created SIP dialog association will be correlated to that SIP
+ * dialog. Otherwise a new SIP dialog is created.
+ * @pre aTransaction.State() == CSIPTransactionBase::EProceeding
+ * @pre aTransaction.Type() == SipStrConsts::EInvite
+ * @param aTransaction a SIP server transaction
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite
+ * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=
+ * CSIPTransactionBase::EProceeding
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewL(CSIPServerTransaction& aTransaction);
+
+ /**
+ * Two-phased constructor.
+ * Should be used if response to the received SIP request will create a
+ * SIP dialog association.
+ * The server transaction must be a INVITE transaction.
+ * If SIP server transaction was received within the existing SIP dialog
+ * the created SIP dialog association will be correlated to that
+ * SIP dialog. Otherwise a new SIP dialog is created.
+ * @pre aTransaction.State() == CSIPTransactionBase::EProceeding
+ * @pre aTransaction.Type() == SipStrConsts::EInvite
+ * @param aTransaction a SIP server transaction
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite
+ * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=
+ * CSIPTransactionBase::EProceeding
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewLC(CSIPServerTransaction& aTransaction);
+
+ /**
+ * Two-phased constructor.
+ * Should be used if response to the received SIP request will create
+ * a SIP dialog association.
+ * The server transaction must be a INVITE transaction.
+ * If SIP server transaction was received within an existing SIP dialog
+ * the created SIP dialog association will be correlated to that SIP
+ * dialog. Otherwise a new SIP dialog is created.
+ * @pre aTransaction.State() == CSIPTransactionBase::EProceeding
+ * @pre aTransaction.Type() == SipStrConsts::EInvite
+ * @pre aContext.IsContextActive() == ETrue
+ * @param aTransaction a SIP server transaction
+ * @param aContext that will be used for populating
+ * the Contact-header of the response to aTransaction
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite
+ * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=
+ * CSIPTransactionBase::EProceeding
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewL(CSIPServerTransaction& aTransaction,
+ const MSIPRegistrationContext& aContext);
+
+ /**
+ * Two-phased constructor.
+ * Should be used if response to the received SIP request will create a
+ * SIP dialog association.
+ * The server transaction must be a INVITE transaction.
+ * If SIP server transaction was received within the existing SIP dialog
+ * the created SIP dialog association will be correlated to that
+ * SIP dialog. Otherwise a new SIP dialog is created.
+ * @pre aTransaction.State() == CSIPTransactionBase::EProceeding
+ * @pre aTransaction.Type() == SipStrConsts::EInvite
+ * @pre aContext.IsContextActive() == ETrue
+ * @param aTransaction a SIP server transaction
+ * @param aContext that will be used for populating
+ * the Contact-header of the response to aTransaction
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite
+ * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=
+ * CSIPTransactionBase::EProceeding
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewLC(CSIPServerTransaction& aTransaction,
+ const MSIPRegistrationContext& aContext);
+
+ /**
+ * Two-phased constructor
+ * @pre aFrom != 0
+ * @pre aRemoteUri != 0
+ * The user of the class must not define tags in From-header
+ * and To-header.
+ * @param aConnection a SIP connection to be used with
+ * dialog association
+ * @param aFrom originator's address; the ownership is transfered
+ * @param aRemoteUri a remote target URI that identifies a resource that
+ * the request is addressed to. The ownership is transferred.
+ * @param aTo logical recipient's address; if not defined
+ * the remote target uri will be used for To-header
+ * construction; the ownership is transfered
+ * @param aContact a contact to be used in dialog creation. Must be
+ * given only if user intends to re-direct future requests;
+ * the ownership is transfered
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aFrom == 0 or aRemoteUri == 0
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewL(CSIPConnection& aConnection,
+ CSIPFromHeader* aFrom,
+ CUri8* aRemoteUri,
+ CSIPToHeader* aTo=0,
+ CSIPContactHeader* aContact=0);
+
+ /**
+ * Two-phased constructor
+ * @pre aFrom != 0
+ * @pre aRemoteUri != 0
+ * The user of the class must not define tags in From-header
+ * and To-header.
+ * @param aSIPConnection a SIP connection to be used with
+ * dialog association
+ * @param aFrom originator's address; the ownership is transfered
+ * @param aRemoteUri a remote target URI that identifies a resource that
+ * the request is addressed to. The ownership is transferred.
+ * @param aTo logical recipient's address; if not defined
+ * the remote target uri will be used for To-header
+ * construction; the ownership is transfered
+ * @param aContact a contact to be used in dialog creation. Must be
+ * given only if user intends to re-direct future requests;
+ * the ownership is transfered
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aFrom == 0 or aRemoteUri == 0
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewLC(CSIPConnection& aConnection,
+ CSIPFromHeader* aFrom,
+ CUri8* aRemoteUri,
+ CSIPToHeader* aTo=0,
+ CSIPContactHeader* aContact=0);
+
+ /**
+ * Two-phased constructor
+ * @pre aRemoteUri != 0
+ * The user of the class must not define tags in From-header
+ * and To-header.
+ * @pre aContext.IsContextActive() == ETrue
+ * @param aConnection a SIP connection to be used with
+ * dialog association
+ * @param aRemoteUri a remote target URI that identifies a resource
+ * that the request is targeted to. The ownership is transferred.
+ * @param aContext used for selecting outbound
+ * proxy and originator's address (AOR) and contact
+ * @param aFrom originator's address. If not defined it will
+ * constructed using registration context (User's AOR);
+ * the ownership is transfered
+ * @param aTo logical recipient's address; if not defined
+ * the remote target uri will be used for To-header
+ * construction; the ownership is transfered
+ * @param aContact a contact to be used in dialog creation. Must be
+ * given only if user intends to re-direct future requests;
+ * the ownership is transfered
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aRemoteUri == 0
+ * @leave KErrSIPInvalidRegistrationState
+ * if aContext.IsContextActive() == EFalse
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewL(CSIPConnection& aConnection,
+ CUri8* aRemoteUri,
+ const MSIPRegistrationContext& aContext,
+ CSIPFromHeader* aFrom=0,
+ CSIPToHeader* aTo=0,
+ CSIPContactHeader* aContact=0);
+
+ /**
+ * Two-phased constructor
+ * @pre aRemoteUri != 0
+ * The user of the class must not define tags in From-header
+ * and To-header.
+ * @pre aContext.IsContextActive() == ETrue
+ * @param aConnection a SIP connection to be used with
+ * dialog association
+ * @param aRemoteUri a remote target URI that identifies a resource
+ * that the request is targeted to. The ownership is transferred.
+ * @param aContext used for selecting outbound
+ * proxy and originator's address (AOR) and contact
+ * @param aFrom originator's address. If not defined it will
+ * constructed using registration context (User's AOR);
+ * the ownership is transfered
+ * @param aTo logical recipient's address; if not defined
+ * the remote target uri will be used for To-header
+ * construction; the ownership is transfered
+ * @param aContact a contact to be used in dialog creation. Must be
+ * given only if user intends to re-direct future requests;
+ * the ownership is transfered
+ * @return New object, ownership is transferred.
+ * @leave KErrArgument if aRemoteUri == 0
+ * @leave KErrSIPInvalidRegistrationState
+ * if aContext.IsContextActive() == EFalse
+ */
+ IMPORT_C static CSIPInviteDialogAssoc*
+ NewLC(CSIPConnection& aConnection,
+ CUri8* aRemoteUri,
+ const MSIPRegistrationContext& aContext,
+ CSIPFromHeader* aFrom=0,
+ CSIPToHeader* aTo=0,
+ CSIPContactHeader* aContact=0);
+
+ /**
+ * Destructor
+ */
+ IMPORT_C ~CSIPInviteDialogAssoc();
+
+ public: // New functions
+
+ /**
+ * Creates INVITE and sends it to the remote target.
+ * 101-199 or 2xx response will create INVITE dialog association in case
+ * of first INVITE within this dialog association. Subsequent INVITE
+ * requests are re-INVITEs.
+ * @pre Dialog().Connection().State()==EActive
+ * @pre Dialog().State()==CSIPDialog::EInit ||
+ * Dialog().State()==CSIPDialog::EConfirmed
+ * @param aElements contains user SIP headers and content. Ownership is
+ * transferred.
+ * @return INVITE SIP transaction. Ownership is transferred.
+ * @leave KErrSIPInvalidDialogState if dialog is not in a correct state
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ * @capability NetworkServices
+ */
+ IMPORT_C CSIPClientTransaction*
+ SendInviteL(CSIPMessageElements* aElements=0);
+
+ /**
+ * Creates PRACK and sends it to the remote target.
+ * @pre Dialog().Connection().State()==EActive
+ * @pre Dialog().State()==CSIPDialog::EEarly ||
+ * Dialog().State()==CSIPDialog::EConfirmed
+ * @pre aElements must not contain Contact headers
+ * @param aElements contains user SIP headers and content. Ownership is
+ * transferred.
+ * @return PRACK SIP transaction. Ownership is transferred.
+ * @leave KErrSIPInvalidDialogState if dialog is not in a correct state
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ * @capability NetworkServices
+ */
+ IMPORT_C CSIPClientTransaction*
+ SendPrackL(CSIPMessageElements* aElements=0);
+
+ /**
+ * Creates UPDATE and sends it to the remote target.
+ * @pre Dialog().Connection().State()==EActive
+ * @pre Dialog().State()==CSIPDialog::EEarly ||
+ * Dialog().State()==CSIPDialog::EConfirmed
+ * @param aElements contains user SIP headers and content. Ownership is
+ * transferred.
+ * @return UPDATE SIP transaction. Ownership is transferred.
+ * @leave KErrSIPInvalidDialogState if dialog is not in a correct state
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ * @capability NetworkServices
+ */
+ IMPORT_C CSIPClientTransaction*
+ SendUpdateL(CSIPMessageElements* aElements=0);
+
+ /**
+ * Creates SIP ACK request and sends it to the remote target.
+ * The client transaction must be an INVITE transaction.
+ * @pre Dialog().Connection().State()==EActive
+ * @pre Dialog().State()==CSIPDialog::EConfirmed
+ * @param aTransaction a SIP INVITE client transaction to acknowledge
+ * @param aElements optional SIP message headers and body. Ownership is
+ * transferred.
+ * @leave KErrArgument if aTransaction is not an INVITE transaction.
+ * @leave KErrSIPInvalidDialogState if ACK can't be sent in the current
+ * dialog state
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ * @capability NetworkServices
+ */
+ IMPORT_C void SendAckL(const CSIPClientTransaction& aTransaction,
+ CSIPMessageElements* aElements=0);
+
+ /**
+ * Creates SIP BYE request and sends it to the remote target.
+ * @pre Dialog().Connection().State()==EActive
+ * @pre Dialog().State()==CSIPDialog::EEarly ||
+ * Dialog().State()==CSIPDialog::EConfirmed
+ * @param aElements contains user SIP headers and content. Ownership is
+ * transferred.
+ * @return SIP BYE transaction. Ownership is transferred.
+ * @leave KErrSIPInvalidDialogState if BYE can't be sent in the current
+ * dialog state
+ * @leave KErrSIPResourceNotAvailable if a required SIP Client API
+ * object has been deleted
+ * @capability NetworkServices
+ */
+ IMPORT_C CSIPClientTransaction*
+ SendByeL(CSIPMessageElements* aElements=0);
+
+ public: // New functions, for internal use
+
+ /**
+ * Sends initial INVITE creating a dialog and creates a transaction for
+ * it.
+ * @param aElements contains user SIP headers and content. Ownership is
+ * transferred.
+ * @return INVITE SIP transaction. Ownership is transferred.
+ */
+ CSIPClientTransaction* DoSendInviteL(CSIPMessageElements* aElements);
+
+ /**
+ * Sends ACK
+ * @param aTransaction a SIP INVITE client transaction to acknowledge
+ * @param aElements optional SIP message headers and body. Ownership is
+ * transferred.
+ */
+ void DoSendAckL(const CSIPClientTransaction& aTransaction,
+ CSIPMessageElements* aElements);
+
+ CSIPClientTransaction*
+ DoSendRequestWithinDialogL(RStringF aMethod,
+ CSIPMessageElements* aElements);
+
+ CSIPClientTransaction* DoSendCancelL(TUint32 aRequestId);
+
+ private: // Constructors
+
+ static CSIPInviteDialogAssoc* NewLC(CSIPConnection& aConnection,
+ CUri8* aRemoteUri,
+ CSIPFromHeader* aFrom,
+ CSIPToHeader* aTo,
+ CSIPContactHeader* aContact,
+ const MSIPRegistrationContext* aContext);
+
+ CSIPInviteDialogAssoc();
+
+ void ConstructL(CSIPServerTransaction& aTransaction,
+ const MSIPRegistrationContext* aContext);
+ };
+
+#endif