1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/sipconnection.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,344 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* 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
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +* Name : sipconnection.h
1.19 +* Part of : SIP Client
1.20 +* Interface : SDK API, SIP API
1.21 +* Version : 1.0
1.22 +*
1.23 +*/
1.24 +
1.25 +
1.26 +
1.27 +#ifndef CSIPCONNECTION_H
1.28 +#define CSIPCONNECTION_H
1.29 +
1.30 +// INCLUDES
1.31 +#include <e32base.h>
1.32 +#include <in_sock.h>
1.33 +#include "_sipcodecdefs.h"
1.34 +
1.35 +// FORWARD DECLARATIONS
1.36 +class CSIP;
1.37 +class MSIPConnectionObserver;
1.38 +class CSIPClientTransaction;
1.39 +class MSIPRegistrationContext;
1.40 +class CSIPRefresh;
1.41 +class CSIPRequestElements;
1.42 +class CSIPConnectionImplementation;
1.43 +
1.44 +// CONSTANTS
1.45 +
1.46 +// CLASS DECLARATION
1.47 +
1.48 +/**
1.49 +* @publishedAll
1.50 +* @released
1.51 +*
1.52 +* Class for monitoring connection's state and sending SIP requests outside
1.53 +* the dialog associations. Class must not be used
1.54 +* - for sending requests to which received non-failure response creates a dialog
1.55 +* - for sending requests that must be sent within SIP dialog
1.56 +*
1.57 +* Note that the user can have only one instance of the class per same IAP-id.
1.58 +*/
1.59 +class CSIPConnection : public CBase
1.60 + {
1.61 + public:
1.62 + /** Connection states */
1.63 + enum TState
1.64 + {
1.65 + /** Connection initializing */
1.66 + EInit=1,
1.67 + /** Connection active */
1.68 + EActive,
1.69 + /** Connection suspended */
1.70 + ESuspended,
1.71 + /** Connection is inactive */
1.72 + EInactive,
1.73 + /** Connection is permanently unavailable */
1.74 + EUnavailable
1.75 + };
1.76 +
1.77 + public: // Constructors and destructor
1.78 +
1.79 + /**
1.80 + * Two-phased constructor.
1.81 + * @param aSip a handle to the SIP server
1.82 + * @param aIapId IAP-id
1.83 + * @param aObserver a observer for receiving asynchonous events on this
1.84 + * connection
1.85 + * @return New object, ownership is transferred
1.86 + * @capability NetworkServices
1.87 + */
1.88 + IMPORT_C static CSIPConnection*
1.89 + NewL(CSIP& aSIP,
1.90 + TUint32 aIapId,
1.91 + MSIPConnectionObserver& aObserver);
1.92 +
1.93 + /**
1.94 + * Two-phased constructor.
1.95 + * Constructs an object and adds the pointer to the cleanup stack;
1.96 + * @param aSip a handle to the SIP server
1.97 + * @param aIapId IAP-id
1.98 + * @param aObserver a observer for receiving asynchonous events on this
1.99 + * connection
1.100 + * @return New object, ownership is transferred
1.101 + * @capability NetworkServices
1.102 + */
1.103 + IMPORT_C static CSIPConnection*
1.104 + NewLC(CSIP& aSIP,
1.105 + TUint32 aIapId,
1.106 + MSIPConnectionObserver& aObserver);
1.107 +
1.108 + /**
1.109 + * Destructor
1.110 + * @capability NetworkServices
1.111 + */
1.112 + IMPORT_C ~CSIPConnection();
1.113 +
1.114 + public: // New functions
1.115 +
1.116 + /**
1.117 + * Gets current state of the connection
1.118 + * @return current state of the connection
1.119 + */
1.120 + IMPORT_C TState State() const;
1.121 +
1.122 + /**
1.123 + * Creates SIP request and sends it to the given destination.
1.124 + * The function must not be used with SIP requests that creates
1.125 + * SIP dialog associations or must be sent within SIP dialog
1.126 + * association.
1.127 + * This provokes the Non-invite state machine.
1.128 + * This function must be used if the user has created the
1.129 + * registration binding.
1.130 + * @pre State() == EActive.
1.131 + * @pre aContext.IsContextActive() == ETrue
1.132 + * @param aElements contains local and remote addresses,
1.133 + * optional SIP message headers and body.
1.134 + * The ownership is transferred.
1.135 + * @param aContext defines outbound proxy to be used. If the user
1.136 + * does not provide from-address it will be constucted using
1.137 + * user's AOR used during the registration.
1.138 + * @return SIP client transaction, ownership is transferred
1.139 + * @leave KErrArgument if aElements == 0
1.140 + * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()
1.141 + * == EFalse
1.142 + * @capability NetworkServices
1.143 + */
1.144 + IMPORT_C CSIPClientTransaction*
1.145 + SendRequestL(CSIPRequestElements* aElements,
1.146 + const MSIPRegistrationContext& aContext);
1.147 +
1.148 + /**
1.149 + * Creates SIP request and sends it to the given destination.
1.150 + * The function must not be used with SIP requests that creates
1.151 + * SIP dialog associations or must be sent within SIP dialog
1.152 + * association.
1.153 + * This provokes the Non-invite state machine.
1.154 + * This function must be used if the user has created the
1.155 + * registration binding.
1.156 + * @pre State() == EActive.
1.157 + * @pre aContext.IsContextActive() == ETrue
1.158 + * @param aElements contains local and remote addresses,
1.159 + * optional SIP message headers and body.
1.160 + * The ownership is transferred.
1.161 + * @param aContext defines outbound proxy to be used. If the user
1.162 + * does not provide from-address it will
1.163 + * be constucted using user's AOR used during the registration.
1.164 + * @param aRefresh defines the refresh interval for this transaction.
1.165 + * @return SIP client transaction, ownership is transferred
1.166 + * @leave KErrArgument if aElements == 0
1.167 + * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()
1.168 + * == EFalse
1.169 + * @capability NetworkServices
1.170 + */
1.171 + IMPORT_C CSIPClientTransaction*
1.172 + SendRequestL(CSIPRequestElements* aElements,
1.173 + const MSIPRegistrationContext& aContext,
1.174 + CSIPRefresh& aRefresh);
1.175 +
1.176 + /**
1.177 + * Creates SIP request and sends it to the given destination.
1.178 + * The function must not be used with SIP requests that creates SIP
1.179 + * dialog associations or must be sent within SIP dialog association.
1.180 + * This invokes the Non-invite state machine.
1.181 + * @pre State() == EActive.
1.182 + * @pre aElements.FromHeader() != 0
1.183 + * @param aElements contains local and remote addresses,
1.184 + * optional SIP message headers and body.
1.185 + * The ownership is transferred.
1.186 + * @return SIP client transaction, ownership is transferred
1.187 + * @leave KErrArgument if aElements == 0 or if From-header is not
1.188 + * present in aElements
1.189 + * @capability NetworkServices
1.190 + */
1.191 + IMPORT_C CSIPClientTransaction*
1.192 + SendRequestL(CSIPRequestElements* aElements);
1.193 +
1.194 + /**
1.195 + * Creates SIP request and sends it to the given destination.
1.196 + * The function must not be used with SIP requests that creates SIP
1.197 + * dialog associations or must be sent within SIP dialog association.
1.198 + * This invokes the Non-invite state machine.
1.199 + * @pre State() == EActive.
1.200 + * @pre aElements.FromHeader() != 0
1.201 + * @param aElements contains local and remote addresses,
1.202 + * optional SIP message headers and body.
1.203 + * The ownership is transferred.
1.204 + * @param aRefresh indicates that transaction will be refreshed
1.205 + * @return SIP client transaction, ownership is transferred
1.206 + * @leave KErrArgument if aElements == 0 or if From-header is not
1.207 + * present in aElements
1.208 + * @capability NetworkServices
1.209 + */
1.210 + IMPORT_C CSIPClientTransaction*
1.211 + SendRequestL(CSIPRequestElements* aElements,
1.212 + CSIPRefresh& aRefresh);
1.213 +
1.214 + /**
1.215 + * Creates SIP REGISTER request and sends it to the given destination.
1.216 + * User must no define any Contact or Expires-headers
1.217 + * in the provided elements.
1.218 + * @pre State() == EActive
1.219 + * @pre aElements != 0
1.220 + * @pre aElements->Method().DesC().Length()==0
1.221 + * @param aElements contains local and remote addresses, optional SIP
1.222 + * message headers and body. User must not set any expires values
1.223 + * to aElements. The ownership is transferred.
1.224 + * @return SIP REGISTER client transaction, ownership is transferred
1.225 + * @leave KErrArgument if aElements == 0 or if the request method has
1.226 + * been defined in aElements
1.227 + * @capability NetworkServices
1.228 + */
1.229 + IMPORT_C CSIPClientTransaction*
1.230 + FetchRegistrationsL(CSIPRequestElements* aElements);
1.231 +
1.232 + /**
1.233 + * Gets Iap-id used for this connection
1.234 + * @return Iap-id
1.235 + */
1.236 + IMPORT_C TUint32 IapId() const;
1.237 +
1.238 + /**
1.239 + * Gets SIP server handle
1.240 + * @return handle to SIP server, or 0-pointer if SIP server does not
1.241 + * exist any more
1.242 + */
1.243 + IMPORT_C CSIP* SIP();
1.244 +
1.245 + /**
1.246 + * Gets SIP server handle
1.247 + * @return handle to SIP server, or 0-pointer if SIP server does not
1.248 + * exist any more
1.249 + */
1.250 + IMPORT_C const CSIP* SIP() const;
1.251 +
1.252 + /**
1.253 + * Sets a RSocket option used for all the sockets used for sending
1.254 + * SIP requests and responses in this CSIPConnection.
1.255 + * @pre State() == EActive
1.256 + * @param aOptionName An integer constant which identifies an option.
1.257 + * @param aOptionLevel An integer constant which identifies
1.258 + * level of an option.
1.259 + * @param aOption Option value packaged in a descriptor.
1.260 + * @leave A system-wide error code
1.261 + * @capability NetworkControl
1.262 + * @capability NetworkServices
1.263 + * @capability Location
1.264 + * @capability ReadDeviceData
1.265 + * @capability WriteDeviceData
1.266 + */
1.267 + IMPORT_C void SetOptL(TUint aOptionName,
1.268 + TUint aOptionLevel,
1.269 + const TDesC8& aOption=KNullDesC8);
1.270 +
1.271 + /**
1.272 + * Sets a RSocket option used for all the sockets used for sending
1.273 + * SIP requests and responses in this CSIPConnection.
1.274 + * @pre State() == EActive
1.275 + * @param aOptionName An integer constant which identifies an option.
1.276 + * @param aOptionLevel An integer constant which identifies
1.277 + * level of an option.
1.278 + * @param aOption Option value as an integer.
1.279 + * @leave A system-wide error codes
1.280 + * @capability NetworkControl
1.281 + * @capability NetworkServices
1.282 + * @capability Location
1.283 + * @capability ReadDeviceData
1.284 + * @capability WriteDeviceData
1.285 + */
1.286 + IMPORT_C void SetOptL(TUint aOptionName,
1.287 + TUint aOptionLevel,
1.288 + TInt aOption);
1.289 +
1.290 + /**
1.291 + * Gets the local IP address of this CSIPConnection
1.292 + * that is used by the SIP implementation.
1.293 + * The user should re-new the call whenever the connection state changes
1.294 + * to the CSIPConnection::EActive in order to verify the correctness of
1.295 + * the previously retrieved local IP address. The local IP address might
1.296 + * be different as a result of the connection state change.
1.297 + * @pre State() == CSIPConnection::EActive
1.298 + * @param aAddr on return filled with local IP address
1.299 + * @leave a system-wide error code
1.300 + */
1.301 + IMPORT_C void GetLocalAddrL(TInetAddr& aAddr) const;
1.302 +
1.303 + /**
1.304 + * Refreshes the connection.
1.305 + * This will retrieve the Bearer Monitor Instance if any, is available for this CSIPConnection and issue a Connection Refresh Request to it.
1.306 + * The state of the Connection can be retrieved from State() to check if there is any change after Refreshing the connection.
1.307 + * @capability NetworkServices.
1.308 + */
1.309 +
1.310 + IMPORT_C void RefreshConnection() const;
1.311 +
1.312 + public: // New functions, for internal use
1.313 +
1.314 + /**
1.315 + * Returns the implementation instance.
1.316 + *
1.317 + * @return CSIPConnectionImplementation
1.318 + */
1.319 + CSIPConnectionImplementation& Implementation();
1.320 +
1.321 + private: // Constructors
1.322 +
1.323 + CSIPConnection();
1.324 +
1.325 + void ConstructL(CSIP& aSIP,
1.326 + TUint32 aIapId,
1.327 + MSIPConnectionObserver& aObserver);
1.328 +
1.329 + private: // Data
1.330 +
1.331 + CSIPConnectionImplementation* iImplementation;
1.332 +
1.333 + private: // For testing purposes
1.334 +
1.335 + UNIT_TEST(CSIP_Test)
1.336 + UNIT_TEST(CSIPConnection_Test)
1.337 + UNIT_TEST(CSIPSubscribeDialogAssoc_Test)
1.338 + UNIT_TEST(CSIPInviteDialogAssoc_Test)
1.339 + UNIT_TEST(CSIPReferDialogAssoc_Test)
1.340 + UNIT_TEST(CSIPNotifyDialogAssoc_Test)
1.341 + UNIT_TEST(CSIPDialogTrying_Test)
1.342 + UNIT_TEST(CSIPRegistrationBinding_Test)
1.343 +
1.344 + __DECLARE_TEST;
1.345 + };
1.346 +
1.347 +#endif