1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/sipregistrationbinding.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,336 @@
1.4 +/*
1.5 +* Copyright (c) 2006-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 : sipregistrationbinding.h
1.19 +* Part of : SIP Client
1.20 +* Interface : SDK API, SIP Client API
1.21 +* Version : 1.0
1.22 +*
1.23 +*/
1.24 +
1.25 +
1.26 +
1.27 +#ifndef CSIPREGISTRATIONBINDING_H
1.28 +#define CSIPREGISTRATIONBINDING_H
1.29 +
1.30 +// INCLUDES
1.31 +#include "sipregistrationcontext.h"
1.32 +#include "_sipcodecdefs.h"
1.33 +
1.34 +// FORWARD DECLARATIONS
1.35 +class CUri8;
1.36 +class CSIPToHeader;
1.37 +class CSIPFromHeader;
1.38 +class CSIPContactHeader;
1.39 +class CSIPRouteHeader;
1.40 +class CSIPMessageElements;
1.41 +class CSIPConnection;
1.42 +class CSIPRefresh;
1.43 +class CSIPClientTransaction;
1.44 +class CRegBindingImplementation;
1.45 +
1.46 +// CLASS DECLARATION
1.47 +
1.48 +/**
1.49 +* @publishedAll
1.50 +* @released
1.51 +*
1.52 +* Class for managing SIP registration binding.
1.53 +* Class provides functions for creating and updating SIP registration bindings.
1.54 +*
1.55 +* @lib sipclient.lib
1.56 +*/
1.57 +class CSIPRegistrationBinding :
1.58 + public CBase,
1.59 + public MSIPRegistrationContext
1.60 + {
1.61 + public: // Constructors and destructor
1.62 +
1.63 + /**
1.64 + * Two-phased constructor.
1.65 + * @pre aAor != 0 &&
1.66 + * aContact != 0
1.67 + * @pre "Expires" parameter in aContact must be >= KSIPMinExpirationValue
1.68 + * @param aConnection a SIP connection to be used
1.69 + * @param aAor contains user's address-of-record to register;
1.70 + * the ownership is transfered
1.71 + * @param aContact contact(s) to be registered. The "expires" parameter
1.72 + * indicates how long the client would like the binding to be
1.73 + * valid.
1.74 + * "expires" parameter value must be >= KSIPMinExpirationValue;
1.75 + * the ownership is transfered
1.76 + * @param aRefresh if set, created binding will be refreshed;
1.77 + * the ownership is transfered
1.78 + * @param aOutboundProxy an outbound proxy address;
1.79 + * the ownership is transfered
1.80 + * @param aRemoteUri if set, will be used in request-uri construction;
1.81 + * the ownership is transfered
1.82 + * @param aFrom From header, the ownership is transferred
1.83 + * @return New object, ownership is transferred.
1.84 + * @leave KErrArgument if aAor == 0, aContact == 0 or if "Expires"
1.85 + * parameter in aContact is less than KSIPMinExpirationValue
1.86 + */
1.87 + IMPORT_C static CSIPRegistrationBinding*
1.88 + NewL(CSIPConnection& aConnection,
1.89 + CSIPToHeader* aAor,
1.90 + CSIPContactHeader* aContact,
1.91 + CSIPRefresh* aRefresh=0,
1.92 + CSIPRouteHeader* aOutboundProxy=0,
1.93 + CUri8* aRemoteUri=0,
1.94 + CSIPFromHeader* aFrom=0);
1.95 +
1.96 + /**
1.97 + * Two-phased constructor.
1.98 + * @pre aAor != 0 &&
1.99 + * aContact != 0
1.100 + * @pre "Expires" parameter in aContact must be >= KSIPMinExpirationValue
1.101 + * @param aConnection a SIP connection to be used
1.102 + * @param aAor contains user's address-of-record to register;
1.103 + * the ownership is transfered
1.104 + * @param aContact contact to be registered; The "expires" parameter
1.105 + * indicates how long the client would like the binding to be
1.106 + * valid.
1.107 + * "expires" parameter value must be >= KSIPMinExpirationValue;
1.108 + * the ownership is transfered
1.109 + * @param aRefresh if set, created binding will be refreshed;
1.110 + * the ownership is transfered
1.111 + * @param aOutboundProxy an outbound proxy address;
1.112 + * the ownership is transfered
1.113 + * @param aRemoteUri if set, will be used in request-uri construction;
1.114 + * the ownership is transfered
1.115 + * @param aFrom From header, the ownership is transferred
1.116 + * @return New object, ownership is transferred.
1.117 + * @leave KErrArgument if aAor == 0, aContact == 0 or if "Expires"
1.118 + * parameter in aContact is less than KSIPMinExpirationValue
1.119 + */
1.120 + IMPORT_C static CSIPRegistrationBinding*
1.121 + NewLC(CSIPConnection& aConnection,
1.122 + CSIPToHeader* aAor,
1.123 + CSIPContactHeader* aContact,
1.124 + CSIPRefresh* aRefresh=0,
1.125 + CSIPRouteHeader* aOutboundProxy=0,
1.126 + CUri8* aRemoteUri=0,
1.127 + CSIPFromHeader* aFrom=0);
1.128 +
1.129 + /**
1.130 + * Destructor
1.131 + */
1.132 + IMPORT_C ~CSIPRegistrationBinding();
1.133 +
1.134 + public: //From MSIPRegistrationContext:
1.135 +
1.136 + /**
1.137 + * Checks if the registration context can be
1.138 + * used for creating SIP messages/dialogs
1.139 + * @return ETrue if the registration binding exists; EFalse
1.140 + * otherwise
1.141 + */
1.142 + IMPORT_C TBool IsContextActive() const;
1.143 +
1.144 + /**
1.145 + * Gets the context id
1.146 + * @return context id
1.147 + * For internal use only
1.148 + */
1.149 + IMPORT_C TUint32 ContextId() const;
1.150 +
1.151 + public: // New functions
1.152 + /**
1.153 + * Creates SIP REGISTER request, sends it to the given destination.
1.154 + * Received 2xx response will create at least one registration
1.155 + * binding.
1.156 + * @pre Connection().State()==EActive
1.157 + * @param aElements contains user SIP headers and content; the ownership
1.158 + * is taken
1.159 + * @return SIP REGISTER transaction; the ownership is transfered
1.160 + * @leave KErrSIPMalformedMessage if aElements contains contact or
1.161 + * expires headers
1.162 + * @leave KErrSIPInvalidRegistrationState if already registered or
1.163 + * registering is in progress or deregistering is in progress.
1.164 + * @capability NetworkServices
1.165 + */
1.166 + IMPORT_C CSIPClientTransaction*
1.167 + RegisterL(CSIPMessageElements* aElements=0);
1.168 +
1.169 + /**
1.170 + * Creates SIP (de)REGISTER request, sends it to the given destination.
1.171 + * This function will remove registration binding.
1.172 + * Any SIP response (2xx - 6xx) to this request removes the binding.
1.173 + * Note that deregistration can be done then the 2xx is received to the
1.174 + * initial REGISTER transaction and there is no on-going registration
1.175 + * updates.
1.176 + * @pre Connection().State()==EActive
1.177 + * @pre IsContextActive()==ETrue
1.178 + * @param aElements contains user SIP headers and content; the ownership
1.179 + * is transfered. If set, user SIP headers must not contain any
1.180 + * Contact-header nor Expires-header
1.181 + * @return SIP REGISTER transaction; the ownership is transfered
1.182 + * @leave KErrSIPInvalidRegistrationState if IsContextActive()==EFalse
1.183 + * @capability NetworkServices
1.184 + */
1.185 + IMPORT_C CSIPClientTransaction*
1.186 + DeregisterL(CSIPMessageElements* aElements=0);
1.187 +
1.188 + /**
1.189 + * Updates the registration binding. Note that update can be done
1.190 + * then the 2xx is received to the REGISTER transaction that relates
1.191 + * to the initial registration or to update.
1.192 + * @pre aElements!=0
1.193 + * @pre Connection().State()==EActive
1.194 + * @pre IsContextActive()==ETrue
1.195 + * @param aElements contains user SIP header and content, must not
1.196 + * contain any Contact-header nor Expires-header;
1.197 + * the ownership is transferred.
1.198 + * @return SIP REGISTER transaction; the ownership is transfered
1.199 + * @leave KErrArgument if aElements == NULL
1.200 + * @leave KErrSIPInvalidRegistrationState if IsContextActive()==EFalse
1.201 + * @capability NetworkServices
1.202 + */
1.203 + IMPORT_C CSIPClientTransaction* UpdateL(CSIPMessageElements* aElements);
1.204 +
1.205 + /**
1.206 + * Updates the regisration binding. Note that update can be done
1.207 + * then the 2xx is received to the REGISTER transaction that relates
1.208 + * to the initial registration or to update.
1.209 + * @pre aExpirationValue >= KSIPMinExpirationValue
1.210 + * @pre Connection().State()==EActive
1.211 + * @pre IsContextActive()==ETrue
1.212 + * @param aExpirationValue a new expiration value in seconds
1.213 + * @param aElements contains user SIP headers and content; must not
1.214 + * contain any Contact-header nor Expires-header;
1.215 + * the ownership is transferred.
1.216 + * @return SIP REGISTER transaction; the ownership is transfered
1.217 + * @leave KErrSIPInvalidRegistrationState if IsContextActive()==EFalse
1.218 + * @capability NetworkServices
1.219 + */
1.220 + IMPORT_C CSIPClientTransaction*
1.221 + UpdateL(TUint aExpirationValue, CSIPMessageElements* aElements=0);
1.222 +
1.223 + /**
1.224 + * Gets the SIP connection used for the registration.
1.225 + * @return SIP connection used for the registration, or 0-pointer if the
1.226 + * connection has been deleted. Ownership is not transferred.
1.227 + */
1.228 + IMPORT_C CSIPConnection* Connection();
1.229 +
1.230 + /**
1.231 + * Gets the SIP connection used for the registration.
1.232 + * @return SIP connection used for the registration, or 0-pointer if the
1.233 + * connection has been deleted. Ownership is not transferred.
1.234 + */
1.235 + IMPORT_C const CSIPConnection* Connection() const;
1.236 +
1.237 + /**
1.238 + * Sets/resets outbound proxy.
1.239 + * If a 0-pointer is given the outbound proxy will be reset.
1.240 + * @param aOutboundProxy an outbound proxy. Ownership is transferred.
1.241 + * @leave KErrSIPResourceNotAvailable if a required SIP Client API
1.242 + * object has been deleted
1.243 + */
1.244 + IMPORT_C void SetOutboundProxyL(CSIPRouteHeader* aOutboundProxy);
1.245 +
1.246 + /**
1.247 + * Gets the address-of-record (AOR) used for creating binding
1.248 + * @return address-of-record (AOR)
1.249 + */
1.250 + IMPORT_C const CSIPToHeader& Aor() const;
1.251 +
1.252 + /**
1.253 + * Gets Contact header associated with the registration binding
1.254 + * @return Contact header
1.255 + */
1.256 + IMPORT_C const CSIPContactHeader& ContactHeader() const;
1.257 +
1.258 + /**
1.259 + * Gets Contact header associated with the registration binding
1.260 + * @return Contact header
1.261 + */
1.262 + IMPORT_C CSIPContactHeader& ContactHeader();
1.263 +
1.264 + /**
1.265 + * Gets used outbound proxy
1.266 + * @return outbound proxy or a 0-pointer if not set. Ownership is not
1.267 + * transferred.
1.268 + */
1.269 + IMPORT_C const CSIPRouteHeader* OutboundProxy() const;
1.270 +
1.271 + /**
1.272 + * Gets associated refresh in case the user has requested the refresh of
1.273 + * the registration. Note that client cannot use update or terminate
1.274 + * functions defined in the CSIPRefresh class.
1.275 + * @return Associated refresh or a 0-pointer if the user has not
1.276 + * requested a refresh of registration binding. Ownership is not
1.277 + * transferred.
1.278 + */
1.279 + IMPORT_C const CSIPRefresh* SIPRefresh() const;
1.280 +
1.281 + /**
1.282 + * Gets associated refresh in case the user has requested the refresh of
1.283 + * the registration. Note that client cannot use update or terminate
1.284 + * functions defined in the CSIPRefresh class.
1.285 + * @return Associated refresh or a 0-pointer if the user has not
1.286 + * requested a refresh of registration binding. Ownership is not
1.287 + * transferred.
1.288 + */
1.289 + IMPORT_C CSIPRefresh* SIPRefresh();
1.290 +
1.291 + /**
1.292 + * Compares this object to another object
1.293 + * @param aRegistration CSIPRegistrationBinding object to compare
1.294 + * @return ETrue if the objects are equal, otherwise EFalse
1.295 + */
1.296 + IMPORT_C TBool
1.297 + operator==(const CSIPRegistrationBinding& aRegistration) const;
1.298 +
1.299 + /**
1.300 + * Gets the registered Contact-header received in the 200 OK response.
1.301 + * @return Contact header, or NULL if IsContextActive() is EFalse.
1.302 + * Ownership is not transferred.
1.303 + */
1.304 + IMPORT_C const CSIPContactHeader* RegisteredContact() const;
1.305 +
1.306 + public: // New functions, for internal use
1.307 + /**
1.308 + * Returns the implementation instance.
1.309 + *
1.310 + * @return CRegBindingImplementation
1.311 + */
1.312 + CRegBindingImplementation& Implementation();
1.313 +
1.314 + private: // Constructors
1.315 + CSIPRegistrationBinding();
1.316 +
1.317 + void ConstructL(CSIPConnection& aConnection,
1.318 + CSIPToHeader* aAor,
1.319 + CSIPContactHeader* aContacts,
1.320 + CSIPRefresh* aRefresh,
1.321 + CSIPRouteHeader* aOutboundProxy,
1.322 + CUri8* aRemoteUri,
1.323 + CSIPFromHeader* aFrom);
1.324 +
1.325 + private: // Data
1.326 + CRegBindingImplementation* iImplementation;
1.327 +
1.328 + private: // For testing purposes
1.329 +
1.330 + UNIT_TEST(CSIP_Test)
1.331 + UNIT_TEST(CSIPRegistrationBinding_Test)
1.332 + UNIT_TEST(CSIPInviteDialogAssoc_Test)
1.333 + UNIT_TEST(CSIPSubscribeDialogAssoc_Test)
1.334 + UNIT_TEST(CSIPReferDialogAssoc_Test)
1.335 +
1.336 + __DECLARE_TEST;
1.337 + };
1.338 +
1.339 +#endif