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