Mercurialtest / file revision
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
epoc32/include/mw/sipinvitedialogassoc.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 3 e1b950c65cb4
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed. 
     1 /*

     2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name        : sipinvitedialogassoc.h

    16 * Part of     : SIP Client

    17 * Interface   : SDK API, SIP Client API

    18 * Version     : 1.0

    19 *

    20 */

    21 

    22 

    23 

    24 

    25 #ifndef CSIPINVITEDIALOGASSOC_H

    26 #define CSIPINVITEDIALOGASSOC_H

    27 

    28 // INCLUDES

    29 #include "sipdialogassocbase.h"

    30 

    31 // CONSTANTS

    32 

    33 // FORWARD DECLARATIONS

    34 class CUri8;

    35 class CSIPConnection;

    36 class CSIPServerTransaction;

    37 class CSIPFromHeader;

    38 class CSIPToHeader;

    39 class CSIPContactHeader;

    40 class MSIPRegistrationContext;

    41 

    42 // CLASS DECLARATION

    43 

    44 /**

    45 *  @publishedAll

    46 *  @released

    47 *

    48 *  Class for managing SIP dialog association created with INVITE.

    49 *  It provides services for creating, using and

    50 *  terminating SIP INVITE dialog association.

    51 *

    52 *  The user can have only one INVITE dialog association per dialog.

    53 * 

    54 *  @lib sipclient.lib

    55 */

    56 class CSIPInviteDialogAssoc : public CSIPDialogAssocBase

    57 	{

    58 	public: // Constructors and destructor

    59 

    60 		/**

    61 		* Two-phased constructor.

    62 		* @param aDialog a dialog to be associated with

    63         * @return New object, ownership is transferred.

    64 		*/

    65 		IMPORT_C static CSIPInviteDialogAssoc* NewL(CSIPDialog& aDialog);

    66 

    67         /**

    68 		* Two-phased constructor.

    69 		* @param aDialog a dialog to be associated with

    70         * @return New object, ownership is transferred.

    71 		*/

    72 		IMPORT_C static CSIPInviteDialogAssoc* NewLC(CSIPDialog& aDialog);

    73 

    74         /**

    75         * Two-phased constructor.

    76         * Should be used if response to the received SIP request will create

    77         * a SIP dialog association.

    78         * The server transaction must be a INVITE transaction.

    79         * If SIP server transaction was received within an existing SIP dialog

    80         * the created SIP dialog association will be correlated to that SIP

    81         * dialog. Otherwise a new SIP dialog is created.

    82         * @pre aTransaction.State() == CSIPTransactionBase::EProceeding

    83         * @pre aTransaction.Type() == SipStrConsts::EInvite

    84         * @param aTransaction a SIP server transaction 

    85         * @return New object, ownership is transferred.

    86         * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite

    87         * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=

    88         *	CSIPTransactionBase::EProceeding

    89         * @leave KErrSIPResourceNotAvailable if a required SIP Client API

    90 		*	object has been deleted

    91         */

    92         IMPORT_C static CSIPInviteDialogAssoc*

    93             NewL(CSIPServerTransaction& aTransaction);

    94 

    95         /**

    96         * Two-phased constructor.

    97         * Should be used if response to the received SIP request will create a

    98         * SIP dialog association.

    99         * The server transaction must be a INVITE transaction.

   100         * If SIP server transaction was received within the existing SIP dialog

   101         * the created SIP dialog association will be correlated to that

   102         * SIP dialog.  Otherwise a new SIP dialog is created.

   103 		* @pre aTransaction.State() == CSIPTransactionBase::EProceeding

   104 		* @pre aTransaction.Type() == SipStrConsts::EInvite

   105         * @param aTransaction a SIP server transaction

   106         * @return New object, ownership is transferred.

   107         * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite

   108         * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=

   109         *	CSIPTransactionBase::EProceeding

   110         * @leave KErrSIPResourceNotAvailable if a required SIP Client API

   111 		*	object has been deleted

   112         */

   113         IMPORT_C static CSIPInviteDialogAssoc*

   114             NewLC(CSIPServerTransaction& aTransaction);

   115 

   116         /**

   117         * Two-phased constructor.

   118         * Should be used if response to the received SIP request will create

   119         * a SIP dialog association.

   120         * The server transaction must be a INVITE transaction.

   121         * If SIP server transaction was received within an existing SIP dialog

   122         * the created SIP dialog association will be correlated to that SIP

   123         * dialog. Otherwise a new SIP dialog is created.

   124         * @pre aTransaction.State() == CSIPTransactionBase::EProceeding

   125         * @pre aTransaction.Type() == SipStrConsts::EInvite

   126 		* @pre aContext.IsContextActive() == ETrue        

   127         * @param aTransaction a SIP server transaction 

   128         * @param aContext that will be used for populating 

   129         *        the Contact-header of the response to aTransaction

   130         * @return New object, ownership is transferred.

   131         * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite

   132         * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=

   133         *	CSIPTransactionBase::EProceeding

   134         * @leave KErrSIPResourceNotAvailable if a required SIP Client API

   135 		*	object has been deleted

   136         */

   137         IMPORT_C static CSIPInviteDialogAssoc*

   138             NewL(CSIPServerTransaction& aTransaction,

   139                  const MSIPRegistrationContext& aContext);

   140 

   141         /**

   142         * Two-phased constructor.

   143         * Should be used if response to the received SIP request will create a

   144         * SIP dialog association.

   145         * The server transaction must be a INVITE transaction.

   146         * If SIP server transaction was received within the existing SIP dialog

   147         * the created SIP dialog association will be correlated to that

   148         * SIP dialog.  Otherwise a new SIP dialog is created.

   149 		* @pre aTransaction.State() == CSIPTransactionBase::EProceeding

   150 		* @pre aTransaction.Type() == SipStrConsts::EInvite

   151 		* @pre aContext.IsContextActive() == ETrue 

   152         * @param aTransaction a SIP server transaction

   153         * @param aContext that will be used for populating 

   154         *        the Contact-header of the response to aTransaction        

   155         * @return New object, ownership is transferred.

   156         * @leave KErrArgument if aTransaction.Type() != SipStrConsts::EInvite

   157         * @leave KErrSIPInvalidTransactionState if aTransaction.State() !=

   158         *	CSIPTransactionBase::EProceeding

   159         * @leave KErrSIPResourceNotAvailable if a required SIP Client API

   160 		*	object has been deleted

   161         */

   162         IMPORT_C static CSIPInviteDialogAssoc*

   163             NewLC(CSIPServerTransaction& aTransaction,

   164                   const MSIPRegistrationContext& aContext);

   165 

   166         /**

   167         * Two-phased constructor

   168         * @pre aFrom != 0

   169         * @pre aRemoteUri != 0

   170 		* The user of the class must not define tags in From-header

   171 		* and To-header.        

   172         * @param aConnection a SIP connection to be used with

   173         *        dialog association

   174         * @param aFrom originator's address; the ownership is transfered

   175         * @param aRemoteUri a remote target URI that identifies a resource that

   176         *		 the request is addressed to. The ownership is transferred.

   177         * @param aTo logical recipient's address; if not defined

   178         *        the remote target uri will be used for To-header

   179         *        construction; the ownership is transfered

   180         * @param aContact a contact to be used in dialog creation. Must be

   181         *        given only if user intends to re-direct future requests; 

   182         *        the ownership is transfered        

   183         * @return New object, ownership is transferred.

   184         * @leave KErrArgument if aFrom == 0 or aRemoteUri == 0

   185         */

   186         IMPORT_C static CSIPInviteDialogAssoc*

   187             NewL(CSIPConnection& aConnection,

   188                  CSIPFromHeader* aFrom,

   189                  CUri8* aRemoteUri,

   190                  CSIPToHeader* aTo=0,

   191                  CSIPContactHeader* aContact=0);

   192 

   193         /**

   194         * Two-phased constructor

   195         * @pre aFrom != 0

   196         * @pre aRemoteUri != 0

   197 		* The user of the class must not define tags in From-header

   198 		* and To-header.

   199         * @param aSIPConnection a SIP connection to be used with

   200         *        dialog association

   201         * @param aFrom originator's address; the ownership is transfered

   202         * @param aRemoteUri a remote target URI that identifies a resource that

   203         *		 the request is addressed to. The ownership is transferred.

   204         * @param aTo logical recipient's address; if not defined

   205         *        the remote target uri will be used for To-header

   206         *        construction; the ownership is transfered

   207         * @param aContact a contact to be used in dialog creation. Must be

   208         *        given only if user intends to re-direct future requests; 

   209         *        the ownership is transfered

   210         * @return New object, ownership is transferred.

   211         * @leave KErrArgument if aFrom == 0 or aRemoteUri == 0

   212         */

   213         IMPORT_C static CSIPInviteDialogAssoc*

   214             NewLC(CSIPConnection& aConnection,

   215                   CSIPFromHeader* aFrom,

   216                   CUri8* aRemoteUri,

   217                   CSIPToHeader* aTo=0,

   218                   CSIPContactHeader* aContact=0);

   219 

   220         /**

   221         * Two-phased constructor

   222 		* @pre aRemoteUri != 0

   223 		* The user of the class must not define tags in From-header

   224 		* and To-header.

   225         * @pre aContext.IsContextActive() == ETrue

   226         * @param aConnection a SIP connection to be used with

   227         *        dialog association        

   228         * @param aRemoteUri a remote target URI that identifies a resource

   229         *		 that the request is targeted to. The ownership is transferred.

   230         * @param aContext used for selecting outbound 

   231         *        proxy and originator's address (AOR) and contact

   232         * @param aFrom originator's address. If not defined it will

   233         *        constructed using registration context (User's AOR);

   234         *        the ownership is transfered

   235         * @param aTo logical recipient's address; if not defined

   236         *        the remote target uri will be used for To-header

   237         *        construction; the ownership is transfered

   238         * @param aContact a contact to be used in dialog creation. Must be

   239         *        given only if user intends to re-direct future requests; 

   240         *        the ownership is transfered

   241         * @return New object, ownership is transferred.

   242         * @leave KErrArgument if aRemoteUri == 0

   243         * @leave KErrSIPInvalidRegistrationState

   244         *		 if aContext.IsContextActive() == EFalse

   245         */

   246         IMPORT_C static CSIPInviteDialogAssoc*

   247             NewL(CSIPConnection& aConnection,                                    

   248                  CUri8* aRemoteUri,

   249                  const MSIPRegistrationContext& aContext,

   250                  CSIPFromHeader* aFrom=0,

   251 	             CSIPToHeader* aTo=0,

   252 	             CSIPContactHeader* aContact=0);

   253 

   254         /**

   255 		* Two-phased constructor		

   256 		* @pre aRemoteUri != 0

   257 		* The user of the class must not define tags in From-header

   258 		* and To-header.

   259 		* @pre aContext.IsContextActive() == ETrue

   260 		* @param aConnection a SIP connection to be used with

   261 		*        dialog association		

   262 		* @param aRemoteUri a remote target URI that identifies a resource

   263 		*		 that the request is targeted to. The ownership is transferred.

   264         * @param aContext used for selecting outbound 

   265         *        proxy and originator's address (AOR) and contact

   266         * @param aFrom originator's address. If not defined it will

   267         *        constructed using registration context (User's AOR);

   268         *        the ownership is transfered

   269         * @param aTo logical recipient's address; if not defined

   270         *        the remote target uri will be used for To-header

   271         *        construction; the ownership is transfered

   272         * @param aContact a contact to be used in dialog creation. Must be

   273         *        given only if user intends to re-direct future requests; 

   274         *        the ownership is transfered

   275         * @return New object, ownership is transferred.

   276         * @leave KErrArgument if aRemoteUri == 0

   277         * @leave KErrSIPInvalidRegistrationState

   278         *		 if aContext.IsContextActive() == EFalse

   279 		*/

   280         IMPORT_C static CSIPInviteDialogAssoc*

   281             NewLC(CSIPConnection& aConnection,			                        

   282 			      CUri8* aRemoteUri,

   283                   const MSIPRegistrationContext& aContext,

   284                   CSIPFromHeader* aFrom=0,

   285 	              CSIPToHeader* aTo=0,

   286 	              CSIPContactHeader* aContact=0);

   287 

   288 		/**

   289 		* Destructor

   290 		*/

   291 		IMPORT_C ~CSIPInviteDialogAssoc();

   292 			                                  

   293 	public: // New functions

   294 

   295 		/**

   296 		* Creates INVITE and sends it to the remote target.

   297 		* 101-199 or 2xx response will create INVITE dialog association in case

   298 		* of first INVITE within this dialog association. Subsequent INVITE

   299 		* requests are re-INVITEs.

   300 		* @pre Dialog().Connection().State()==EActive

   301 		* @pre Dialog().State()==CSIPDialog::EInit ||

   302 		*      Dialog().State()==CSIPDialog::EConfirmed

   303 		* @param aElements contains user SIP headers and content. Ownership is

   304         *   transferred.

   305 		* @return INVITE SIP transaction. Ownership is transferred.

   306 		* @leave KErrSIPInvalidDialogState if dialog is not in a correct state

   307 		* @leave KErrSIPResourceNotAvailable if a required SIP Client API

   308 		*	object has been deleted

   309 		* @capability NetworkServices

   310 		*/

   311 		IMPORT_C CSIPClientTransaction*

   312             SendInviteL(CSIPMessageElements* aElements=0);

   313 

   314         /**

   315 		* Creates PRACK and sends it to the remote target.		

   316 		* @pre Dialog().Connection().State()==EActive

   317 		* @pre Dialog().State()==CSIPDialog::EEarly || 

   318 		*      Dialog().State()==CSIPDialog::EConfirmed

   319         * @pre aElements must not contain Contact headers

   320 		* @param aElements contains user SIP headers and content. Ownership is

   321         *   transferred.

   322 		* @return PRACK SIP transaction. Ownership is transferred.

   323 		* @leave KErrSIPInvalidDialogState if dialog is not in a correct state

   324 		* @leave KErrSIPResourceNotAvailable if a required SIP Client API

   325 		*	object has been deleted

   326 		* @capability NetworkServices

   327 		*/

   328 		IMPORT_C CSIPClientTransaction*

   329             SendPrackL(CSIPMessageElements* aElements=0);

   330 

   331 	    /**

   332 		* Creates UPDATE and sends it to the remote target.

   333 		* @pre Dialog().Connection().State()==EActive

   334 		* @pre Dialog().State()==CSIPDialog::EEarly || 

   335 		*      Dialog().State()==CSIPDialog::EConfirmed

   336 		* @param aElements contains user SIP headers and content. Ownership is

   337         *   transferred.

   338 		* @return UPDATE SIP transaction. Ownership is transferred.

   339 		* @leave KErrSIPInvalidDialogState if dialog is not in a correct state

   340 		* @leave KErrSIPResourceNotAvailable if a required SIP Client API

   341 		*	object has been deleted

   342 		* @capability NetworkServices

   343 		*/

   344 		IMPORT_C CSIPClientTransaction*

   345             SendUpdateL(CSIPMessageElements* aElements=0);

   346 

   347 		/**

   348 		* Creates SIP ACK request and sends it to the remote target.

   349 		* The client transaction must be an INVITE transaction.

   350 		* @pre Dialog().Connection().State()==EActive

   351 		* @pre Dialog().State()==CSIPDialog::EConfirmed

   352 		* @param aTransaction a SIP INVITE client transaction to acknowledge

   353 		* @param aElements optional SIP message headers and body. Ownership is

   354         *   transferred.

   355         * @leave KErrArgument if aTransaction is not an INVITE transaction.

   356         * @leave KErrSIPInvalidDialogState if ACK can't be sent in the current

   357 		*	dialog state

   358         * @leave KErrSIPResourceNotAvailable if a required SIP Client API

   359 		*	object has been deleted

   360 		* @capability NetworkServices

   361 		*/

   362 		IMPORT_C void SendAckL(const CSIPClientTransaction& aTransaction,

   363 			                   CSIPMessageElements* aElements=0);

   364 

   365 	    /**

   366 		* Creates SIP BYE request and sends it to the remote target.		

   367 		* @pre Dialog().Connection().State()==EActive

   368 		* @pre Dialog().State()==CSIPDialog::EEarly || 

   369 		*      Dialog().State()==CSIPDialog::EConfirmed

   370 		* @param aElements contains user SIP headers and content. Ownership is

   371         *   transferred.

   372 		* @return SIP BYE transaction. Ownership is transferred.

   373 		* @leave KErrSIPInvalidDialogState if BYE can't be sent in the current

   374 		*	dialog state

   375 		* @leave KErrSIPResourceNotAvailable if a required SIP Client API

   376 		*	object has been deleted

   377 		* @capability NetworkServices

   378 		*/		

   379 		IMPORT_C CSIPClientTransaction*

   380             SendByeL(CSIPMessageElements* aElements=0);

   381 

   382 	public: // New functions, for internal use

   383 	

   384         /**

   385 		* Sends initial INVITE creating a dialog and creates a transaction for

   386         * it.

   387 		* @param aElements contains user SIP headers and content. Ownership is

   388         *   transferred.

   389 		* @return INVITE SIP transaction. Ownership is transferred.

   390 		*/

   391         CSIPClientTransaction* DoSendInviteL(CSIPMessageElements* aElements);

   392 

   393         /**

   394 		* Sends ACK		

   395 		* @param aTransaction a SIP INVITE client transaction to acknowledge

   396 		* @param aElements optional SIP message headers and body. Ownership is

   397         *   transferred.

   398 		*/

   399         void DoSendAckL(const CSIPClientTransaction& aTransaction,

   400                         CSIPMessageElements* aElements);

   401 

   402 		CSIPClientTransaction*

   403 			DoSendRequestWithinDialogL(RStringF aMethod,

   404 									   CSIPMessageElements* aElements);

   405 

   406         CSIPClientTransaction* DoSendCancelL(TUint32 aRequestId);

   407 

   408    	private: // Constructors

   409    	   	

   410 		static CSIPInviteDialogAssoc* NewLC(CSIPConnection& aConnection,

   411 								 CUri8* aRemoteUri,

   412 	                             CSIPFromHeader* aFrom,

   413 	                             CSIPToHeader* aTo,

   414 		                         CSIPContactHeader* aContact,

   415 		                         const MSIPRegistrationContext* aContext);

   416 

   417 		CSIPInviteDialogAssoc();

   418 		

   419 		void ConstructL(CSIPServerTransaction& aTransaction,

   420                         const MSIPRegistrationContext* aContext);

   421 	};

   422 

   423 #endif
test