1 sipreferdialogassoc.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name        : sipreferdialogassoc.h

    16 * Part of     : SIP Client

    17 * Interface   : SDK API, SIP Client API

    18 * Version     : 1.0

    19 *

    20 */

    21 

    22 

    23 

    24 #ifndef CSIPREFERDIALOGASSOC_H

    25 #define CSIPREFERDIALOGASSOC_H

    26 

    27 // INCLUDES

    28 #include "sipdialogassocbase.h"

    29 

    30 // CONSTANTS

    31 

    32 // FORWARD DECLARATIONS

    33 class CUri8;

    34 class CSIPToHeader;

    35 class CSIPFromHeader;

    36 class CSIPContactHeader;

    37 class CSIPReferToHeader;

    38 class MSIPRegistrationContext;

    39 class CSIPConnection;

    40 

    41 // CLASS DECLARATION

    42 

    43 /**

    44 * @publishedAll

    45 * @released

    46 *

    47 * Class for managing SIP REFER dialog associations.

    48 * It provides services for creating, using and terminating SIP REFER

    49 * dialog associations. User can have multiple REFER dialog associations

    50 * per same SIP dialog.

    51 * Implementation handles SUBSCRIBE on the dialog level defined by Call-Id,

    52 * local and remote tags;

    53 * User is responsible for "Refer-to" header semantics.

    54 * @lib sipclient.lib

    55 */

    56 class CSIPReferDialogAssoc: public CSIPDialogAssocBase

    57 	{

    58 	public: // Constructors and destructor

    59 

    60 		/**

    61 		* Two-phased constructor.

    62 		* Should be used if response to the SIP request to be sent

    63 		* will create a SIP dialog association.

    64 		* @pre aReferTo != 0

    65 		* @param aDialog a dialog to be associated with

    66 		* @param aReferTo referred-to resource

    67         * @return New object; the ownership is transferred

    68         * @leave KErrArgument if aReferTo == 0

    69 		*/

    70 		IMPORT_C static CSIPReferDialogAssoc*

    71 			NewL(CSIPDialog& aDialog,

    72 				 CSIPReferToHeader* aReferTo);

    73 

    74 		/**

    75 		* Two-phased constructor.

    76 		* Must be used if response to the SIP request to be sent

    77 		* will create a SIP dialog association.

    78 		* @pre aReferTo != 0

    79 		* @param aDialog a dialog to be associated with

    80 		* @param aReferTo referred-to resource

    81         * @return New object; the ownership is transferred

    82         * @leave KErrArgument if aReferTo == 0

    83 		*/

    84 		IMPORT_C static CSIPReferDialogAssoc*

    85 			NewLC(CSIPDialog& aDialog,

    86 				  CSIPReferToHeader* aReferTo);

    87 

    88        /**

    89         * Two-phased constructor

    90         * @pre aFrom != 0 

    91         * @pre aReferTo != 0

    92 		* @pre aRemoteUri != 0

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

    94 		* and To-header.

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

    96         *        dialog association

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

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

    99         *		 the request is addressed to.

   100 		* @param aReferTo referred-to resource

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

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

   103         *        construction; the ownership is transfered

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

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

   106         *        the ownership is transfered

   107         * @return New object; the ownership is transferred.

   108         * @leave KErrArgument if aFrom == 0 or aRemoteuri == 0 or aReferTo == 0

   109         */

   110         IMPORT_C static CSIPReferDialogAssoc*

   111             NewL(CSIPConnection& aConnection,

   112                  CSIPFromHeader* aFrom,

   113 				 CUri8* aRemoteUri,

   114 				 CSIPReferToHeader* aReferTo,

   115                  CSIPToHeader* aTo=0,                 

   116                  CSIPContactHeader* aContact=0);

   117 

   118        /**

   119         * Two-phased constructor

   120         * @pre aFrom != 0

   121         * @pre aReferTo != 0

   122 		* @pre aRemoteUri != 0

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

   124 		* and To-header.

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

   126         *        dialog association

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

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

   129         *		 the request is addressed to.

   130 		* @param aReferTo referred-to resource

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

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

   133         *        construction; the ownership is transfered

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

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

   136         *        the ownership is transfered

   137         * @return New object; the ownership is transferred.

   138         * @leave KErrArgument if aFrom == 0 or aRemoteuri == 0 or aReferTo == 0

   139         */

   140         IMPORT_C static CSIPReferDialogAssoc*

   141             NewLC(CSIPConnection& aConnection,

   142                   CSIPFromHeader* aFrom,

   143 				  CUri8* aRemoteUri,

   144 				  CSIPReferToHeader* aReferTo,

   145                   CSIPToHeader* aTo=0,                 

   146                   CSIPContactHeader* aContact=0);

   147 

   148        /**

   149         * Two-phased constructor

   150         * @pre aReferTo != 0

   151 		* @pre aRemoteUri != 0

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

   153 		* and To-header.

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

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

   156         *        dialog association 

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

   158         *		 the request is targeted to.

   159         * @param aContext used for selecting outbound 

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

   161         * @param aReferTo referred-to resource

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

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

   164         *        the ownership is transfered

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

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

   167         *        construction; the ownership is transfered

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

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

   170         *        the ownership is transfered

   171         * @return New object: the ownership is transferred.

   172         * @leave KErrArgument if aRemoteuri == 0 or aReferTo == 0

   173         * @leave KErrSIPInvalidRegistrationState

   174         *		 if aContext.IsContextActive() == EFalse

   175         */

   176         IMPORT_C static CSIPReferDialogAssoc*

   177             NewL(CSIPConnection& aConnection,                                    

   178                  CUri8* aRemoteUri,

   179                  const MSIPRegistrationContext& aContext,

   180                  CSIPReferToHeader* aReferTo,

   181                  CSIPFromHeader* aFrom=0,

   182 	             CSIPToHeader* aTo=0,

   183 	             CSIPContactHeader* aContact=0);

   184 

   185        /**

   186         * Two-phased constructor        

   187         * @pre aReferTo != 0

   188 		* @pre aRemoteUri != 0

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

   190 		* and To-header.

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

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

   193         *        dialog association 

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

   195         *		 the request is targeted to.

   196         * @param aContext used for selecting outbound 

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

   198         * @param aReferTo referred-to resource

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

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

   201         *        the ownership is transfered

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

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

   204         *        construction; the ownership is transfered

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

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

   207         *        the ownership is transfered

   208         * @return New object; the ownership is transferred.

   209         * @leave KErrArgument if aRemoteuri == 0 or aReferTo == 0

   210         * @leave KErrSIPInvalidRegistrationState

   211         *		 if aContext.IsContextActive() == EFalse

   212         */

   213         IMPORT_C static CSIPReferDialogAssoc*

   214             NewLC(CSIPConnection& aConnection,                                    

   215                  CUri8* aRemoteUri,

   216                  const MSIPRegistrationContext& aContext,

   217                  CSIPReferToHeader* aReferTo,

   218                  CSIPFromHeader* aFrom=0,

   219 	             CSIPToHeader* aTo=0,

   220 	             CSIPContactHeader* aContact=0);

   221 

   222 		/**

   223 		* Destructor

   224 		*/

   225 		IMPORT_C ~CSIPReferDialogAssoc();

   226 

   227 	public: //New functions

   228 

   229 		/**

   230 		* Creates REFER and sends it to the remote target.

   231 		* leaves on failure.

   232 		* 101-199 or 2xx response will create REFER dialog 

   233 		* association in case of first REFER request within

   234 		* this dialog association.

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

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

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

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

   239         *   transferred.

   240 		* @return REFER SIP transaction. Ownership is transferred.

   241 		* @leave KErrSIPInvalidDialogState if dialog is in wrong state

   242 		* @leave KErrSIPResourceNotAvailable if a required SIP Client API

   243 		*	object has been deleted.

   244 		* @capability NetworkServices

   245 		*/

   246 		IMPORT_C CSIPClientTransaction*

   247             SendReferL(CSIPMessageElements* aElements=0);

   248         

   249         /**

   250         * Gets referred-to resouce

   251         * @return referred-to resource

   252         */

   253         IMPORT_C const CSIPReferToHeader& ReferTo() const;

   254 

   255 	public: // New functions, for internal use

   256 	

   257 		/**

   258 		* Sends a REFER request.

   259 		*

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

   261 		* @param aElements optional SIP message headers and body.

   262 		*	Ownership is transferred.

   263 		* @param aWithinDialog ETrue if REFER is sent within dialog,

   264 		*	EFalse if REFER creates the dialog.

   265 		* @return REFER SIP transaction. Ownership is transferred.

   266 		*/

   267 		CSIPClientTransaction* DoSendReferL(CSIPMessageElements* aElements,

   268 								   			TBool aWithinDialog);

   269 

   270  	private: // Constructors

   271 

   272         CSIPReferDialogAssoc();

   273         

   274         static CSIPReferDialogAssoc* NewLC(CSIPConnection& aConnection,

   275 								CUri8* aRemoteUri,

   276 								CSIPReferToHeader* aReferTo,

   277 								CSIPFromHeader* aFrom,

   278                                 CSIPToHeader* aTo,

   279 			                    CSIPContactHeader* aContact,

   280 			                    const MSIPRegistrationContext* aContext);

   281 

   282     private: // Data

   283 

   284         CSIPReferToHeader* iReferTo;

   285 	};

   286 

   287 #endif