1 sipdialog.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        : sipdialog.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 CSIPDIALOG_H

    26 #define CSIPDIALOG_H

    27 

    28 // INCLUDES

    29 #include <e32base.h>

    30 #include <stringpool.h>

    31 #include "_sipcodecdefs.h"

    32 

    33 // FORWARD DECLARATIONS

    34 class CSIPConnection;

    35 class CSIPConnectionImplementation;

    36 class MSIPRegistrationContext;

    37 class CSIPDialogAssocBase;

    38 class CSIPFromHeader;

    39 class CSIPToHeader;

    40 class CSIPCallIDHeader;

    41 class CUri8;

    42 class CSIPDialogImplementation;

    43 

    44 // CLASS DECLARATION

    45 

    46 /**

    47 *  @publishedAll

    48 *  @released

    49 *

    50 *  Class for managing SIP dialogs.

    51 *  It provides services querying dialog state, obtaining the dialog related

    52 *  SIP headers and getting all dialog associations.

    53 *

    54 *  The user of the class cannot instantiate this class.

    55 *  @lib sipclient

    56 */

    57 

    58 class CSIPDialog: public CBase

    59 	{

    60 	public:

    61 		/** Dialog states */

    62 		enum TState

    63 			{

    64 			/** Initiliazed state */

    65 			EInit,

    66 			/** Early state */

    67 			EEarly,

    68 			/** Confirmed state */

    69 			EConfirmed,

    70 			/** Terminated state */

    71 			ETerminated

    72 			};

    73 

    74 	public: //New functions

    75 		/**

    76 		* Gets dialog state		

    77 		* @return dialog state

    78 		*/

    79         IMPORT_C CSIPDialog::TState State() const;

    80 

    81 		/**

    82 		* Gets all dialog associations. 		

    83 		* @return All dialog associations. Ownership of the array or the items

    84         *   inside it, is not transferred.

    85 		*/

    86 		IMPORT_C const RPointerArray<CSIPDialogAssocBase>&

    87 					   SIPDialogAssociations() const;

    88 

    89         /**

    90         * Gets used registration context for this dialog

    91         * @return associated registration or 0-pointer otherwise.

    92         *   Ownership is not transferred.

    93         */

    94         IMPORT_C const MSIPRegistrationContext* RegistrationContext() const;

    95 	

    96         /**

    97 		* Checks if the dialog association belongs to this dialog

    98 		* @param aDialogAssoc a dialog association

    99 		* @return ETrue if belongs, EFalse otherwise

   100 		*/

   101 		IMPORT_C TBool

   102             IsAssociated(const CSIPDialogAssocBase& aDialogAssoc) const;

   103 

   104         /**

   105 		* Gets the SIP connection used for this dialog

   106 		* @return SIP connection used for the dialog, or 0-pointer if the

   107         *   connection has been deleted. Ownership isn't transferred.

   108 		*/

   109         IMPORT_C CSIPConnection* Connection();

   110 

   111         /**

   112 		* Gets the SIP connection used for this dialog.

   113 		* @return SIP connection used for the dialog, or 0-pointer if the

   114         *   connection has been deleted. Ownership isn't transferred.

   115 		*/

   116         IMPORT_C const CSIPConnection* Connection() const;

   117 

   118         /**

   119 		* Gets originator's address

   120 		* @return originator's address (From-header)

   121 		*/

   122 		IMPORT_C const CSIPFromHeader& FromHeader() const;

   123 

   124 		/**

   125 		* Gets recipient's address

   126 		* @return recipient's address (To-header)

   127 		*/

   128 		IMPORT_C const CSIPToHeader& ToHeader() const;

   129 

   130 		/**

   131 		* Gets remote-uri used during dialog creation

   132 		* @return Remote target uri

   133 		*/

   134 		IMPORT_C const CUri8& RemoteURI() const;

   135 

   136 		/**

   137 		* Gets Call-ID of SIP dialog

   138 		* @pre State()==CSIPDialog::EEarly || State()==CSIPDialog::EConfirmed

   139 		* @return Call-ID of SIP dialog

   140 		* @leave KErrSIPInvalidDialogState if dialog doesn't yet have a Call-ID

   141 		*/

   142 		IMPORT_C const CSIPCallIDHeader& CallIdL() const;

   143 

   144         /**

   145 		* Compares this object to another object

   146 		* @param aDialog CSIPDialog object to compare

   147 		* @returns ETrue if the objects are equal, otherwise EFalse

   148 		*/

   149         IMPORT_C TBool operator==(const CSIPDialog& aDialog) const;

   150         

   151         /**

   152         * Sets the dialog to state to CSIPDialog::EInit.

   153         * The local dialog identifier data 

   154         * (Call-ID, CSeq and From-header's tag) will be reused. 

   155         * After calling this function, the dialog that was already terminated 

   156         * can be used for sending the dialog initiating request such as 

   157         * INVITE or SUBSCRIBE reusing the stored Call-ID and From-header's tag

   158         * and the stored CSeq incremented by one.

   159         * @pre State()==CSIPDialog::ETerminated

   160         * @returns KErrNone if succesful and KErrNoMemory if the memory is low.

   161         */

   162         IMPORT_C TInt ReuseInitialRequestData();

   163 

   164 	public: //Constructors and destructor, for internal use

   165 		/**

   166 		* Two-phased constructor. 

   167 		* This constructor should be used if the user has received

   168 		* SIP request that creates a SIP dialog association.

   169         *

   170         * @param aConnImplementation Implementation of the used SIP connection

   171         * @return New object, ownership is transferred.

   172         */

   173 		static CSIPDialog*

   174 			NewL(CSIPConnectionImplementation& aConnImplementation);

   175 

   176 		/**

   177 		* Two-phased constructor

   178 		* This constructor should be used if the user has received

   179 		* SIP request that creates a SIP dialog association.

   180         *

   181 		* @param aConnImplementation Implementation of the used SIP connection

   182         * @return New object, ownership is transferred.

   183        	*/

   184 		static CSIPDialog*

   185 			NewLC(CSIPConnectionImplementation& aConnImplementation);

   186 

   187 		/**

   188 		* Two-phased constructor

   189 		* This constructor should be used if the user has received

   190 		* SIP request that creates a SIP dialog association.

   191         *

   192         * @param aConnImplementation Implementation of the used SIP connection

   193 		* @param aContext Registration context whose outbound proxy and other

   194 		*        parameters are to be used.

   195         * @return New object, ownership is transferred.

   196        	*/

   197 		static CSIPDialog*

   198 			NewL(CSIPConnectionImplementation& aConnImplementation,

   199                  const MSIPRegistrationContext& aContext);

   200 

   201 		/**

   202 		* Two-phased constructor

   203 		* This constructor should be used if the user has received

   204 		* SIP request that creates a SIP dialog association.

   205         *

   206         * @param aConnImplementation Implementation of the used SIP connection

   207 		* @param aContext Registration context whose outbound proxy and other

   208 		*        parameters are to be used.

   209         * @return New object, ownership is transferred.

   210         */

   211 		static CSIPDialog*

   212 			NewLC(CSIPConnectionImplementation& aConnImplementation,

   213                   const MSIPRegistrationContext& aContext);

   214 

   215 		/**

   216 		* Destructor

   217 		*/

   218 		~CSIPDialog();

   219 

   220 	public: // New functions, for internal use

   221 

   222 		/**

   223 		* Returns the CSIPDialogImplementation.

   224  		* @return CSIPDialogImplementation

   225  		*/

   226 		CSIPDialogImplementation& Implementation();

   227 

   228     private: // Constructors

   229 

   230         CSIPDialog();        

   231 

   232         void ConstructL(CSIPConnectionImplementation& aConnImplementation);

   233         

   234         void ConstructL(CSIPConnectionImplementation& aConnImplementation,

   235                    		const MSIPRegistrationContext& aContext);

   236 

   237 private: // Data

   238 

   239 		//Implementation instance, CSIPDialog doesn't own it

   240 		CSIPDialogImplementation* iImplementation;

   241 

   242 private: // For testing purposes

   243 

   244 	    UNIT_TEST(CSIP_Test)

   245         UNIT_TEST(CSIPInviteDialogAssoc_Test)

   246         UNIT_TEST(CSIPSubscribeDialogAssoc_Test)

   247         UNIT_TEST(CSIPReferDialogAssoc_Test)

   248 

   249         __DECLARE_TEST;

   250 	};

   251 

   252 #endif