1 sipconnection.h |
1 /* |
|
2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
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". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * Name : sipconnection.h |
|
16 * Part of : SIP Client |
|
17 * Interface : SDK API, SIP API |
|
18 * Version : 1.0 |
|
19 * |
|
20 */ |
|
21 |
|
22 |
|
23 |
|
24 #ifndef CSIPCONNECTION_H |
|
25 #define CSIPCONNECTION_H |
|
26 |
|
27 // INCLUDES |
|
28 #include <e32base.h> |
|
29 #include <in_sock.h> |
|
30 #include "_sipcodecdefs.h" |
|
31 |
|
32 // FORWARD DECLARATIONS |
|
33 class CSIP; |
|
34 class MSIPConnectionObserver; |
|
35 class CSIPClientTransaction; |
|
36 class MSIPRegistrationContext; |
|
37 class CSIPRefresh; |
|
38 class CSIPRequestElements; |
|
39 class CSIPConnectionImplementation; |
|
40 |
|
41 // CONSTANTS |
|
42 |
|
43 // CLASS DECLARATION |
|
44 |
|
45 /** |
|
46 * @publishedAll |
|
47 * @released |
|
48 * |
|
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 |
|
53 * |
|
54 * Note that the user can have only one instance of the class per same IAP-id. |
|
55 */ |
|
56 class CSIPConnection : public CBase |
|
57 { |
|
58 public: |
|
59 /** Connection states */ |
|
60 enum TState |
|
61 { |
|
62 /** Connection initializing */ |
|
63 EInit=1, |
|
64 /** Connection active */ |
|
65 EActive, |
|
66 /** Connection suspended */ |
|
67 ESuspended, |
|
68 /** Connection is inactive */ |
|
69 EInactive, |
|
70 /** Connection is permanently unavailable */ |
|
71 EUnavailable |
|
72 }; |
|
73 |
|
74 public: // Constructors and destructor |
|
75 |
|
76 /** |
|
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 |
|
81 * connection |
|
82 * @return New object, ownership is transferred |
|
83 * @capability NetworkServices |
|
84 */ |
|
85 IMPORT_C static CSIPConnection* |
|
86 NewL(CSIP& aSIP, |
|
87 TUint32 aIapId, |
|
88 MSIPConnectionObserver& aObserver); |
|
89 |
|
90 /** |
|
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 |
|
96 * connection |
|
97 * @return New object, ownership is transferred |
|
98 * @capability NetworkServices |
|
99 */ |
|
100 IMPORT_C static CSIPConnection* |
|
101 NewLC(CSIP& aSIP, |
|
102 TUint32 aIapId, |
|
103 MSIPConnectionObserver& aObserver); |
|
104 |
|
105 /** |
|
106 * Destructor |
|
107 * @capability NetworkServices |
|
108 */ |
|
109 IMPORT_C ~CSIPConnection(); |
|
110 |
|
111 public: // New functions |
|
112 |
|
113 /** |
|
114 * Gets current state of the connection |
|
115 * @return current state of the connection |
|
116 */ |
|
117 IMPORT_C TState State() const; |
|
118 |
|
119 /** |
|
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 |
|
123 * association. |
|
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() |
|
138 * == EFalse |
|
139 * @capability NetworkServices |
|
140 */ |
|
141 IMPORT_C CSIPClientTransaction* |
|
142 SendRequestL(CSIPRequestElements* aElements, |
|
143 const MSIPRegistrationContext& aContext); |
|
144 |
|
145 /** |
|
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 |
|
149 * association. |
|
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() |
|
165 * == EFalse |
|
166 * @capability NetworkServices |
|
167 */ |
|
168 IMPORT_C CSIPClientTransaction* |
|
169 SendRequestL(CSIPRequestElements* aElements, |
|
170 const MSIPRegistrationContext& aContext, |
|
171 CSIPRefresh& aRefresh); |
|
172 |
|
173 /** |
|
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 |
|
187 */ |
|
188 IMPORT_C CSIPClientTransaction* |
|
189 SendRequestL(CSIPRequestElements* aElements); |
|
190 |
|
191 /** |
|
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 |
|
206 */ |
|
207 IMPORT_C CSIPClientTransaction* |
|
208 SendRequestL(CSIPRequestElements* aElements, |
|
209 CSIPRefresh& aRefresh); |
|
210 |
|
211 /** |
|
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 |
|
225 */ |
|
226 IMPORT_C CSIPClientTransaction* |
|
227 FetchRegistrationsL(CSIPRequestElements* aElements); |
|
228 |
|
229 /** |
|
230 * Gets Iap-id used for this connection |
|
231 * @return Iap-id |
|
232 */ |
|
233 IMPORT_C TUint32 IapId() const; |
|
234 |
|
235 /** |
|
236 * Gets SIP server handle |
|
237 * @return handle to SIP server, or 0-pointer if SIP server does not |
|
238 * exist any more |
|
239 */ |
|
240 IMPORT_C CSIP* SIP(); |
|
241 |
|
242 /** |
|
243 * Gets SIP server handle |
|
244 * @return handle to SIP server, or 0-pointer if SIP server does not |
|
245 * exist any more |
|
246 */ |
|
247 IMPORT_C const CSIP* SIP() const; |
|
248 |
|
249 /** |
|
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 |
|
263 */ |
|
264 IMPORT_C void SetOptL(TUint aOptionName, |
|
265 TUint aOptionLevel, |
|
266 const TDesC8& aOption=KNullDesC8); |
|
267 |
|
268 /** |
|
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 |
|
282 */ |
|
283 IMPORT_C void SetOptL(TUint aOptionName, |
|
284 TUint aOptionLevel, |
|
285 TInt aOption); |
|
286 |
|
287 /** |
|
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 |
|
297 */ |
|
298 IMPORT_C void GetLocalAddrL(TInetAddr& aAddr) const; |
|
299 |
|
300 /** |
|
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. |
|
305 */ |
|
306 |
|
307 IMPORT_C void RefreshConnection() const; |
|
308 |
|
309 public: // New functions, for internal use |
|
310 |
|
311 /** |
|
312 * Returns the implementation instance. |
|
313 * |
|
314 * @return CSIPConnectionImplementation |
|
315 */ |
|
316 CSIPConnectionImplementation& Implementation(); |
|
317 |
|
318 private: // Constructors |
|
319 |
|
320 CSIPConnection(); |
|
321 |
|
322 void ConstructL(CSIP& aSIP, |
|
323 TUint32 aIapId, |
|
324 MSIPConnectionObserver& aObserver); |
|
325 |
|
326 private: // Data |
|
327 |
|
328 CSIPConnectionImplementation* iImplementation; |
|
329 |
|
330 private: // For testing purposes |
|
331 |
|
332 UNIT_TEST(CSIP_Test) |
|
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) |
|
340 |
|
341 __DECLARE_TEST; |
|
342 }; |
|
343 |
|
344 #endif |