2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * Name : sipconnection.h
16 * Part of : SIP Client
17 * Interface : SDK API, SIP API
24 #ifndef CSIPCONNECTION_H
25 #define CSIPCONNECTION_H
30 #include "_sipcodecdefs.h"
32 // FORWARD DECLARATIONS
34 class MSIPConnectionObserver;
35 class CSIPClientTransaction;
36 class MSIPRegistrationContext;
38 class CSIPRequestElements;
39 class CSIPConnectionImplementation;
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
54 * Note that the user can have only one instance of the class per same IAP-id.
56 class CSIPConnection : public CBase
59 /** Connection states */
62 /** Connection initializing */
64 /** Connection active */
66 /** Connection suspended */
68 /** Connection is inactive */
70 /** Connection is permanently unavailable */
74 public: // Constructors and destructor
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
82 * @return New object, ownership is transferred
83 * @capability NetworkServices
85 IMPORT_C static CSIPConnection*
88 MSIPConnectionObserver& aObserver);
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
97 * @return New object, ownership is transferred
98 * @capability NetworkServices
100 IMPORT_C static CSIPConnection*
103 MSIPConnectionObserver& aObserver);
107 * @capability NetworkServices
109 IMPORT_C ~CSIPConnection();
111 public: // New functions
114 * Gets current state of the connection
115 * @return current state of the connection
117 IMPORT_C TState State() const;
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
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()
139 * @capability NetworkServices
141 IMPORT_C CSIPClientTransaction*
142 SendRequestL(CSIPRequestElements* aElements,
143 const MSIPRegistrationContext& aContext);
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
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()
166 * @capability NetworkServices
168 IMPORT_C CSIPClientTransaction*
169 SendRequestL(CSIPRequestElements* aElements,
170 const MSIPRegistrationContext& aContext,
171 CSIPRefresh& aRefresh);
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
188 IMPORT_C CSIPClientTransaction*
189 SendRequestL(CSIPRequestElements* aElements);
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
207 IMPORT_C CSIPClientTransaction*
208 SendRequestL(CSIPRequestElements* aElements,
209 CSIPRefresh& aRefresh);
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
226 IMPORT_C CSIPClientTransaction*
227 FetchRegistrationsL(CSIPRequestElements* aElements);
230 * Gets Iap-id used for this connection
233 IMPORT_C TUint32 IapId() const;
236 * Gets SIP server handle
237 * @return handle to SIP server, or 0-pointer if SIP server does not
240 IMPORT_C CSIP* SIP();
243 * Gets SIP server handle
244 * @return handle to SIP server, or 0-pointer if SIP server does not
247 IMPORT_C const CSIP* SIP() const;
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
264 IMPORT_C void SetOptL(TUint aOptionName,
266 const TDesC8& aOption=KNullDesC8);
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
283 IMPORT_C void SetOptL(TUint aOptionName,
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
298 IMPORT_C void GetLocalAddrL(TInetAddr& aAddr) const;
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.
307 IMPORT_C void RefreshConnection() const;
309 public: // New functions, for internal use
312 * Returns the implementation instance.
314 * @return CSIPConnectionImplementation
316 CSIPConnectionImplementation& Implementation();
318 private: // Constructors
322 void ConstructL(CSIP& aSIP,
324 MSIPConnectionObserver& aObserver);
328 CSIPConnectionImplementation* iImplementation;
330 private: // For testing purposes
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)