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