epoc32/include/sipconnection.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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        : sipconnection.h
    16 * Part of     : SIP Client
    17 * Interface   : SDK API, SIP API
    18 * Version     : 1.0
    19 *
    20 */
    21 
    22 
    23 
    24 #ifndef CSIPCONNECTION_H
    25 #define CSIPCONNECTION_H
    26 
    27 // INCLUDES
    28 #include <e32base.h>
    29 #include <in_sock.h>
    30 #include "_sipcodecdefs.h"
    31 
    32 // FORWARD DECLARATIONS
    33 class CSIP;
    34 class MSIPConnectionObserver;
    35 class CSIPClientTransaction;
    36 class MSIPRegistrationContext;
    37 class CSIPRefresh;
    38 class CSIPRequestElements;
    39 class CSIPConnectionImplementation;
    40 
    41 // CONSTANTS
    42 
    43 // CLASS DECLARATION
    44 
    45 /**
    46 * @publishedAll
    47 * @released
    48 *
    49 * Class for monitoring connection's state and sending SIP requests outside
    50 * the dialog associations. Class must not be used
    51 * - for sending requests to which received non-failure response creates a dialog
    52 * - for sending requests that must be sent within SIP dialog
    53 *  
    54 * Note that the user can have only one instance of the class per same IAP-id.
    55 */
    56 class CSIPConnection : public CBase
    57 	{
    58     public:
    59         /** Connection states */
    60         enum TState 
    61             {
    62             /** Connection initializing */
    63 			EInit=1,
    64 			/** Connection active */
    65 			EActive,
    66 			/** Connection suspended */
    67 			ESuspended,
    68 			/** Connection is inactive */
    69 			EInactive,
    70 			/** Connection is permanently unavailable */
    71 			EUnavailable
    72             };
    73 
    74     public:  // Constructors and destructor
    75 
    76 	    /**
    77         * Two-phased constructor.
    78 		* @param aSip a handle to the SIP server
    79 		* @param aIapId IAP-id
    80 		* @param aObserver a observer for receiving asynchonous events on this
    81         *   connection
    82         * @return New object, ownership is transferred
    83         * @capability NetworkServices
    84         */
    85 		IMPORT_C static CSIPConnection*
    86             NewL(CSIP& aSIP,
    87 				 TUint32 aIapId,
    88 				 MSIPConnectionObserver& aObserver);
    89 
    90 	    /**
    91         * Two-phased constructor.
    92 		* Constructs an object and adds the pointer to the cleanup stack;
    93 		* @param aSip a handle to the SIP server
    94 		* @param aIapId IAP-id
    95 		* @param aObserver a observer for receiving asynchonous events on this
    96         *   connection
    97         * @return New object, ownership is transferred
    98         * @capability NetworkServices
    99         */
   100 		IMPORT_C static CSIPConnection*
   101             NewLC(CSIP& aSIP,
   102 				  TUint32 aIapId,
   103 				  MSIPConnectionObserver& aObserver);
   104 
   105 		/**
   106 		* Destructor
   107         * @capability NetworkServices
   108 		*/
   109 		IMPORT_C ~CSIPConnection();
   110 
   111     public: // New functions
   112 
   113         /**
   114 		* Gets current state of the connection        
   115         * @return current state of the connection
   116         */
   117 		IMPORT_C TState State() const;
   118 
   119         /**
   120 		* Creates SIP request and sends it to the given destination.
   121 		* The function must not be used with SIP requests that creates
   122 		* SIP dialog associations or must be sent within SIP dialog
   123 		* association.
   124 		* This provokes the Non-invite state machine.
   125 		* This function must be used if the user has created the
   126 		* registration binding.
   127 		* @pre State() == EActive.
   128 		* @pre aContext.IsContextActive() == ETrue
   129 		* @param aElements contains local and remote addresses,
   130 		*		 optional SIP message headers and body.
   131 		*        The ownership is transferred.
   132 		* @param aContext defines outbound proxy to be used. If the user
   133 		*        does not provide from-address it will be constucted using
   134 		*        user's AOR used during the registration.
   135         * @return SIP client transaction, ownership is transferred
   136         * @leave KErrArgument if aElements == 0
   137         * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()
   138         *	== EFalse
   139 		* @capability NetworkServices
   140         */
   141 		IMPORT_C CSIPClientTransaction*
   142             SendRequestL(CSIPRequestElements* aElements,
   143                          const MSIPRegistrationContext& aContext);
   144 
   145         /**
   146 		* Creates SIP request and sends it to the given destination.
   147 		* The function must not be used with SIP requests that creates
   148 		* SIP dialog associations or must be sent within SIP dialog
   149 		* association.
   150 		* This provokes the Non-invite state machine.
   151 		* This function must be used if the user has created the
   152 		* registration binding.
   153 		* @pre State() == EActive.
   154 		* @pre aContext.IsContextActive() == ETrue
   155 		* @param aElements contains local and remote addresses,
   156 		*		 optional SIP message headers and body.
   157 		*        The ownership is transferred.
   158 		* @param aContext defines outbound proxy to be used. If the user
   159 		*        does not provide from-address it will 
   160 		*        be constucted using user's AOR used during the registration.
   161 		* @param aRefresh defines the refresh interval for this transaction.
   162         * @return SIP client transaction, ownership is transferred
   163         * @leave KErrArgument if aElements == 0
   164         * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()
   165         *	== EFalse
   166         * @capability NetworkServices
   167         */
   168 		IMPORT_C CSIPClientTransaction*
   169             SendRequestL(CSIPRequestElements* aElements,                                        
   170                          const MSIPRegistrationContext& aContext,
   171 						 CSIPRefresh& aRefresh); 
   172 
   173         /**
   174 		* Creates SIP request and sends it to the given destination.
   175 		* The function must not be used with SIP requests that creates SIP
   176 		* dialog associations or must be sent within SIP dialog association.
   177 		* This invokes the Non-invite state machine.
   178 		* @pre State() == EActive.
   179 		* @pre aElements.FromHeader() != 0
   180 		* @param aElements contains local and remote addresses,
   181 		*		 optional SIP message headers and body.
   182 		*        The ownership is transferred.
   183         * @return SIP client transaction, ownership is transferred
   184         * @leave KErrArgument if aElements == 0 or if From-header is not
   185         *	present in aElements
   186         * @capability NetworkServices
   187         */
   188 		IMPORT_C CSIPClientTransaction*
   189             SendRequestL(CSIPRequestElements* aElements);
   190 
   191         /**
   192 		* Creates SIP request and sends it to the given destination.
   193 		* The function must not be used with SIP requests that creates SIP
   194 		* dialog associations or must be sent within SIP dialog association.
   195 		* This invokes the Non-invite state machine.
   196 		* @pre State() == EActive.
   197 		* @pre aElements.FromHeader() != 0
   198 		* @param aElements contains local and remote addresses,
   199 		*		 optional SIP message headers and body.
   200 		*        The ownership is transferred.
   201 		* @param aRefresh indicates that transaction will be refreshed
   202         * @return SIP client transaction, ownership is transferred
   203         * @leave KErrArgument if aElements == 0 or if From-header is not
   204         *	present in aElements
   205         * @capability NetworkServices
   206         */
   207 		IMPORT_C CSIPClientTransaction*
   208             SendRequestL(CSIPRequestElements* aElements,
   209 						 CSIPRefresh& aRefresh);
   210 
   211 		/**
   212 		* Creates SIP REGISTER request and sends it to the given destination.
   213 		* User must no define any Contact or Expires-headers
   214 		* in the provided elements.
   215 		* @pre State() == EActive
   216         * @pre aElements != 0
   217         * @pre aElements->Method().DesC().Length()==0
   218 		* @param aElements contains local and remote addresses, optional SIP
   219         *        message headers and body. User must not set any expires values
   220         *        to aElements. The ownership is transferred.
   221         * @return SIP REGISTER client transaction, ownership is transferred
   222         * @leave KErrArgument if aElements == 0 or if the request method has
   223         *	been defined in aElements
   224         * @capability NetworkServices
   225         */
   226 		IMPORT_C CSIPClientTransaction*
   227             FetchRegistrationsL(CSIPRequestElements* aElements);
   228 
   229 		/**
   230 		* Gets Iap-id used for this connection
   231 		* @return Iap-id
   232 		*/
   233         IMPORT_C TUint32 IapId() const;
   234 
   235 		/**
   236         * Gets SIP server handle
   237         * @return handle to SIP server, or 0-pointer if SIP server does not
   238         *	exist any more
   239         */        
   240         IMPORT_C CSIP* SIP();
   241 
   242         /**
   243         * Gets SIP server handle
   244         * @return handle to SIP server, or 0-pointer if SIP server does not
   245         *	exist any more
   246         */        
   247         IMPORT_C const CSIP* SIP() const;
   248       
   249 		/**
   250 		* Sets a RSocket option used for all the sockets used for sending 
   251 		* SIP requests and responses in this CSIPConnection.
   252 		* @pre State() == EActive
   253 		* @param aOptionName An integer constant which identifies an option.
   254         * @param aOptionLevel An integer constant which identifies 
   255         *        level of an option.
   256         * @param aOption Option value packaged in a descriptor.
   257         * @leave A system-wide error code
   258         * @capability NetworkControl
   259         * @capability NetworkServices
   260         * @capability Location
   261         * @capability ReadDeviceData
   262         * @capability WriteDeviceData        
   263         */        
   264 	    IMPORT_C void SetOptL(TUint aOptionName,
   265 	                      	  TUint aOptionLevel,
   266 	                      	  const TDesC8& aOption=KNullDesC8);
   267 
   268 		/**
   269 		* Sets a RSocket option used for all the sockets used for sending 
   270 		* SIP requests and responses in this CSIPConnection.
   271 		* @pre State() == EActive
   272 		* @param aOptionName An integer constant which identifies an option.
   273         * @param aOptionLevel An integer constant which identifies 
   274         *        level of an option.
   275         * @param aOption Option value as an integer.
   276         * @leave A system-wide error codes
   277         * @capability NetworkControl
   278         * @capability NetworkServices
   279         * @capability Location
   280         * @capability ReadDeviceData
   281         * @capability WriteDeviceData
   282         */ 	                         
   283 	    IMPORT_C void SetOptL(TUint aOptionName,
   284 	                          TUint aOptionLevel,
   285 	                          TInt aOption);
   286 
   287         /**
   288         * Gets the local IP address of this CSIPConnection 
   289         * that is used by the SIP implementation.
   290         * The user should re-new the call whenever the connection state changes
   291         * to the CSIPConnection::EActive in order to verify the correctness of
   292         * the previously retrieved local IP address. The local IP address might
   293         * be different as a result of the connection state change.
   294         * @pre State() == CSIPConnection::EActive
   295         * @param aAddr on return filled with local IP address
   296         * @leave a system-wide error code
   297         */ 	                         
   298 	    IMPORT_C void GetLocalAddrL(TInetAddr& aAddr) const;
   299 	    
   300 	/**
   301 	* Refreshes the connection.
   302 	* This will retrieve the Bearer Monitor Instance if any, is available for this  CSIPConnection and issue a Connection Refresh Request to it.
   303 	* The state of the Connection can be retrieved from State() to check if there is any change after Refreshing the connection.
   304 	* @capability NetworkServices.
   305 	*/
   306 	    
   307 	  IMPORT_C void RefreshConnection() const;
   308 
   309 	public: // New functions, for internal use
   310 	
   311 		/**
   312 		* Returns the implementation instance.
   313 		*
   314  		* @return CSIPConnectionImplementation
   315 		*/
   316 		CSIPConnectionImplementation& Implementation();
   317 
   318     private: // Constructors
   319     
   320         CSIPConnection();
   321 
   322         void ConstructL(CSIP& aSIP,
   323                         TUint32 aIapId,
   324                         MSIPConnectionObserver& aObserver);
   325 
   326 	private: // Data
   327 	
   328 		CSIPConnectionImplementation* iImplementation;
   329 		        
   330 	private: // For testing purposes
   331 	
   332 	    UNIT_TEST(CSIP_Test)
   333         UNIT_TEST(CSIPConnection_Test)
   334         UNIT_TEST(CSIPSubscribeDialogAssoc_Test)
   335         UNIT_TEST(CSIPInviteDialogAssoc_Test)
   336         UNIT_TEST(CSIPReferDialogAssoc_Test)
   337         UNIT_TEST(CSIPNotifyDialogAssoc_Test)
   338         UNIT_TEST(CSIPDialogTrying_Test)
   339         UNIT_TEST(CSIPRegistrationBinding_Test)
   340         
   341         __DECLARE_TEST;
   342 	};
   343 
   344 #endif