|
1 /* |
|
2 * Copyright (c) 2002-2005 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 "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * Interface for WV fundamental services. |
|
16 * The supported features are search and invite. |
|
17 * |
|
18 */ |
|
19 |
|
20 |
|
21 #ifndef CImpsFundCli_H |
|
22 #define CImpsFundCli_H |
|
23 |
|
24 // INCLUDES |
|
25 #include "impsclient.h" |
|
26 #include "impsfundamental.h" |
|
27 |
|
28 // FORWARD DECLARATIONS |
|
29 class CImpsFundCommand2; |
|
30 class MImpsSearchHandler2; |
|
31 class MImpsInviteHandler2; |
|
32 |
|
33 // CLASS DECLARATION |
|
34 |
|
35 /** |
|
36 * RImpsFundClient2 API |
|
37 * |
|
38 * Applications use the subsystem via RImpsFundClient2 class. First, they need |
|
39 * to connect to the server by calling RegisterL() member function. |
|
40 * |
|
41 * When everything is done, call Unregister() to end |
|
42 * the session. |
|
43 * |
|
44 * A user of this API must be aware that raising/releasing |
|
45 * the PDP context may affect the response times of called functions. |
|
46 * |
|
47 * |
|
48 * Observer methods: |
|
49 * ----------------------- |
|
50 * Client can be notified when a certain type of message is received |
|
51 * from the remote server. |
|
52 * Client has to be connected in the server in order to get notify events. |
|
53 * If the client is disconnected by server by calling Unregister(), all notify |
|
54 * requests and possible incoming events are canceled. |
|
55 * |
|
56 * Notify events are session-specific, ie. if you have several RImpsFundClients |
|
57 * connected to the server, each has its own notify requests. |
|
58 * |
|
59 * In order to use search feature, you need to implement MImpsSearchHandler2 |
|
60 * and give a pointer to your class in RegisterL. |
|
61 * Observer method doesn't need to do anything else than your application |
|
62 * needs it to do. |
|
63 * |
|
64 */ |
|
65 |
|
66 |
|
67 class RImpsFundClient2 : public RImpsClient2 |
|
68 { |
|
69 |
|
70 public: // Constructors and destructor |
|
71 |
|
72 /** |
|
73 * C++ default constructor. |
|
74 */ |
|
75 IMPORT_C RImpsFundClient2(); |
|
76 |
|
77 public: // New functions |
|
78 |
|
79 // INITILIZATION AND CONNECT |
|
80 |
|
81 /** |
|
82 * Registers the listener objects for Fundamental events and connects |
|
83 * to the Symbian OS Server. |
|
84 * Leaves with KImpsErrorAlreadyInUse if the client |
|
85 * has already registered. |
|
86 * @param aEngine WV Engine server instance |
|
87 * @param aSearchObs search result observer. May be NULL. |
|
88 * @param aInviteObs invite observer. May be NULL. |
|
89 * @param aClientId Client-Id for requests if non zero length. |
|
90 * @param aReceiveNew determines if new pushed messages are received. |
|
91 * If EFalse then new messages are filtered out and |
|
92 * responses to own requests are deliverd only. |
|
93 * @param aPriority Observer priority. Refers to CActive priority. |
|
94 */ |
|
95 IMPORT_C void RegisterL( RImpsEng& aEngine, |
|
96 MImpsSearchHandler2* aSearchObs, |
|
97 MImpsInviteHandler2* aInviteObs, |
|
98 const TDesC& aClientId, |
|
99 TBool aReceiveNew = ETrue, |
|
100 TInt aPriority = CActive::EPriorityStandard ); |
|
101 |
|
102 /** |
|
103 * Unregisters the listener objects and disconnects from the server. |
|
104 */ |
|
105 IMPORT_C void Unregister(); |
|
106 |
|
107 |
|
108 // Fundamental SERVICES |
|
109 |
|
110 /** |
|
111 * Start search |
|
112 * @param aPairs defines what is to be searched |
|
113 * @param aSearchLimit how many results you want |
|
114 * @return operation-id (positive) |
|
115 */ |
|
116 IMPORT_C TInt SearchFirstL( const CSearchPairs& aPairs, |
|
117 TInt aSearchLimit ); |
|
118 |
|
119 /** |
|
120 * Continue search |
|
121 * @param aSearchID which search is to be continued |
|
122 * @param aIndex from which index the search is continued |
|
123 * @return operation-id (positive) |
|
124 */ |
|
125 IMPORT_C TInt SearchNextL( TInt aSearchID, |
|
126 TInt aIndex ); |
|
127 |
|
128 |
|
129 /** |
|
130 * Stop search |
|
131 * @param aSearchID which search is to be stopped |
|
132 * @return operation-id (positive) |
|
133 */ |
|
134 IMPORT_C TInt StopSearchL( TInt aSearchID ); |
|
135 |
|
136 |
|
137 /* --- Comments on the parameters --- |
|
138 * |
|
139 * - aInviteID |
|
140 * Spec says this must be unique in the context of |
|
141 * the "server domain". |
|
142 * Thus it is possible, though not very likely, that some other |
|
143 * client may send the exact same ID that we did. |
|
144 * |
|
145 * - aUserID, aScreenName & aGroupName |
|
146 * There may be more than one user in more than one group invited |
|
147 * with a single request. The list of the invitees, according to |
|
148 * the spec, can be "any combination of" user IDs and screen names. |
|
149 * What this means in practice is that the users can be identified |
|
150 * either by their user ID or screen name. For this reason, |
|
151 * the indexes of aScreenName and aGroupName |
|
152 * MUST correspond to each other. |
|
153 * For example, if we want to invite the user <SName="Opa"> in |
|
154 * <GroupID="Chess">, <SName="Opa"> in <GroupID="Chess">, |
|
155 * aScreenName[0] must be "Opa" and aUserGroupID[0] "Chess". |
|
156 * Thus, if user ID is specified, the client does not check the array |
|
157 * for screen names on top of that. If, on the other hand, there |
|
158 * is no user ID, BOTH screen name AND group ID MUST be present. |
|
159 * |
|
160 * --- Comments end --- |
|
161 */ |
|
162 |
|
163 /** |
|
164 * Invite users to a group |
|
165 * Primitive: InviteRequest |
|
166 * Note that the aScreenName & aGroupName parameters together form the |
|
167 * actual screen name primitives |
|
168 * @param aInviteID = Invite ID; unique in the context |
|
169 * of the session |
|
170 * @param aUserID = IDs of the users to invite |
|
171 * @param aScreenName = Screen names (<SName>) of the users |
|
172 * to be invited |
|
173 * @param aGroupName = The group (<GroupID>) in which the screen |
|
174 * name is unique |
|
175 * @param aInviteGroup = ID of the group to which the users |
|
176 * are invited to join |
|
177 * @param aOwnScreenName = SName of the inviter |
|
178 * @param aOwnGroupName = The group, in which the inviters |
|
179 * SName is unique |
|
180 * @param aInviteReason = Free text |
|
181 * @param aValidityPeriod = How long is this invitation valid |
|
182 * @return operation-id (positive) |
|
183 */ |
|
184 IMPORT_C TInt GroupInviteL( const TDesC& aInviteID, |
|
185 const MDesCArray* aUserID, |
|
186 const MDesCArray* aScreenName, |
|
187 const MDesCArray* aGroupName, |
|
188 const TDesC& aInviteGroup, |
|
189 const TDesC& aOwnScreenName, |
|
190 const TDesC& aOwnGroupName, |
|
191 const TDesC& aInviteReason, |
|
192 const TInt aValidityPeriod ); |
|
193 |
|
194 /** |
|
195 * Invite user to IM conversation |
|
196 * Primitive: InviteRequest |
|
197 * @param aInviteID = Invite ID; unique in the context |
|
198 * of the session |
|
199 * @param aInviteReason = Free text |
|
200 * @param aValidityPeriod = How long is this invitation valid? |
|
201 * @return operation-id (positive) |
|
202 */ |
|
203 IMPORT_C TInt ImInviteL( const TDesC& aInviteID, |
|
204 const TDesC& aUserID, |
|
205 const TDesC& aInviteReason, |
|
206 const TInt aValidityPeriod ); |
|
207 |
|
208 /** |
|
209 * Cancel an invite |
|
210 * Primitive: CancelInviteRequest |
|
211 * @param aInviteID = Invite to be cancelled |
|
212 * @param aUserID = ID(s) of the user(s) |
|
213 * @param aScreenName = Screen names (<SName>) of the users |
|
214 * @param aGroupName = Name of the group |
|
215 * @param aCancelReason = A short text describing the |
|
216 * reason for the cancelling. |
|
217 * @param aOwnScreenName = Screen name of the canceller |
|
218 * @param aOwnGroupName = Group name of the canceller. |
|
219 * @return operation-id (positive) |
|
220 */ |
|
221 IMPORT_C TInt CancelInviteL( const TDesC& aInviteId, |
|
222 const MDesCArray* aUserID, |
|
223 const MDesCArray* aScreenName, |
|
224 const MDesCArray* aGroupName, |
|
225 const TDesC& aCancelReason, |
|
226 const TDesC& aOwnScreenName, |
|
227 const TDesC& aOwnGroupName ); |
|
228 |
|
229 /** |
|
230 * Send response to invite |
|
231 * Primitive: InviteUserResponse |
|
232 * @param aInviteId = ID of the invite response |
|
233 * @param aAcceptance = Do we meet the claim |
|
234 * @param aInviteResponse = Textual description of the response |
|
235 * @param aOwnScreenName = Screen name of the responding user |
|
236 * @param aOwnGroupName = Group name of the responding user |
|
237 * @return operation-id (positive) |
|
238 */ |
|
239 IMPORT_C TInt InviteResponseL( const TDesC& aInviteId, |
|
240 TBool aAcceptance, |
|
241 const TDesC& aInviteResponse, |
|
242 const TDesC& aOwnScreenName, |
|
243 const TDesC& aOwnGroupName ); |
|
244 |
|
245 |
|
246 /** |
|
247 * Pointer to the search observer handler |
|
248 * @return handler |
|
249 */ |
|
250 inline MImpsSearchHandler2* SearchHandler() const; |
|
251 |
|
252 /** |
|
253 * Pointer to the invite observer handler |
|
254 * @return handler |
|
255 */ |
|
256 inline MImpsInviteHandler2* InviteHandler() const; |
|
257 |
|
258 |
|
259 private: |
|
260 |
|
261 /** |
|
262 * Registers the listener object for Fund events and connects to |
|
263 * the Symbian OS Server. |
|
264 * @param aEngine WV Engine server instance |
|
265 * @param aHandler the observer |
|
266 * @return general error code |
|
267 */ |
|
268 TInt DoRegister( |
|
269 RImpsEng& aEngine, |
|
270 CImpsHandler2* aHandler ); |
|
271 |
|
272 private: // data |
|
273 |
|
274 CImpsFundCommand2* iCommand; |
|
275 MImpsSearchHandler2* iSearchCallBack; |
|
276 MImpsInviteHandler2* iInviteCallBack; |
|
277 |
|
278 |
|
279 private: // friend classes |
|
280 |
|
281 friend class CImpsFundCommand2; |
|
282 |
|
283 }; |
|
284 |
|
285 // CLASS DECLARATION |
|
286 |
|
287 /** |
|
288 * MImpsSearchHandler2 |
|
289 * |
|
290 * Abstract interface for handling the search result events from the server. |
|
291 * User derives his class from this and implements the methods below. |
|
292 */ |
|
293 |
|
294 class MImpsSearchHandler2 |
|
295 { |
|
296 |
|
297 public: // New functions |
|
298 |
|
299 /** |
|
300 * Observer method for search response |
|
301 * Primitive: SearchResponse |
|
302 * @param aId operation id returned by SearchFirstL or SearchNextL. |
|
303 * @param aSearchID search operation id, |
|
304 * used when search is continued or stopped. |
|
305 * @param aIndex indicates the particular index from which the |
|
306 * next search can start. It is 0 in error case. |
|
307 * @param aResultsFound indicates the number of the current findings. |
|
308 * @param aCompleted TRUE if server has completed the search, |
|
309 * FALSE if there are more results available. |
|
310 * @param aType which kind of items there are in aResults parameter |
|
311 * @param aResults list of results, |
|
312 * NULL if none. |
|
313 * @param aCspId CSP session identifier |
|
314 */ |
|
315 virtual void HandleSearchL( TInt aId, |
|
316 TInt aSearchId, |
|
317 TInt aIndex, |
|
318 TInt aResultsFound, |
|
319 TBool aCompleted, |
|
320 TImpsSearchResultType aType, |
|
321 MDesCArray* aResults , |
|
322 TImpsCspIdentifier& aCspId ) = 0; |
|
323 |
|
324 |
|
325 /** |
|
326 * Observer for stopped search |
|
327 * This is called when WV server has stopped the search after StopSearchL. |
|
328 * Notice that a previous search is invalidated |
|
329 * when a new search is started, |
|
330 * but this method is not called in that situation. |
|
331 * @param aId operation id returned by StopSearchL. |
|
332 * @param aSearchID search operation id, |
|
333 * used when search was stopped. |
|
334 * @param aCspId CSP session identifier |
|
335 */ |
|
336 virtual void HandleSearchStoppedL( TInt aId, |
|
337 TInt aSearchId, |
|
338 TImpsCspIdentifier& aCspId ) = 0; |
|
339 |
|
340 }; |
|
341 |
|
342 /** |
|
343 * MImpsInviteHandler2 |
|
344 * |
|
345 * Abstract interface for handling invite events from the server. |
|
346 * User derives from this and implements the pure virtual methods below. |
|
347 */ |
|
348 class MImpsInviteHandler2 |
|
349 { |
|
350 public: |
|
351 |
|
352 /** |
|
353 * Handle invite to a group |
|
354 * Primitive: InviteUserRequest |
|
355 * @param aInviteID = ID of the invite request |
|
356 * @param aUserID = User ID of the inviter |
|
357 * @param aScreenName = SName of the inviter |
|
358 * @param aGroupName = GroupID of the inviter |
|
359 * @param aInviteReason = Textual description of the invitation |
|
360 * @param aValidityPeriod = Time that the invitation is valid |
|
361 * @param aCspId CSP session identifier |
|
362 */ |
|
363 virtual void HandleGroupInviteL( const TDesC& aInviteID, |
|
364 const TDesC& aUserID, |
|
365 const TDesC& aScreenName, |
|
366 const TDesC& aGroupName, |
|
367 const TDesC& aInviteReason, |
|
368 const TInt aValidityPeriod, |
|
369 TImpsCspIdentifier& aCspId ) = 0; |
|
370 |
|
371 /** |
|
372 * Handle invite to a conversation |
|
373 * Primitive: InviteUserRequest |
|
374 * @param aInviteID = ID of the invite request |
|
375 * @param aUserID = User ID of the inviter |
|
376 * @param aInviteReason = Textual description of the invitation |
|
377 * @param aValidityPeriod = Time that the invitation is valid |
|
378 * @param aCspId CSP session identifier |
|
379 */ |
|
380 virtual void HandleImInviteL( const TDesC& aInviteID, |
|
381 const TDesC& aUserID, |
|
382 const TDesC& aInviteReason, |
|
383 const TInt aValidityPeriod, |
|
384 TImpsCspIdentifier& aCspId ) = 0; |
|
385 |
|
386 /** |
|
387 * Meaning of this method is to provide a way that SAP can use to ask |
|
388 * if the user accepts multimedia content in incoming messages. If the |
|
389 * url is something else than a fixed one ( stored in CenRep ) the |
|
390 * client should use browser to message retrieving. If the url is |
|
391 * the fixed one the client should either accept or deny the multimedia |
|
392 * content receiving by sending InviteResponse. |
|
393 * Primitive: InviteUserRequest |
|
394 * @param aInviteID = ID of the invite request |
|
395 * @param aUserID = User ID of the inviter |
|
396 * @param aUrlList = List of url's |
|
397 * @param aInviteReason = Textual description of the invitation |
|
398 * @param aValidityPeriod = Time that the invitation is valid |
|
399 * @param aCspId CSP session identifier |
|
400 */ |
|
401 virtual void HandleContentInviteL( const TDesC& aInviteID, |
|
402 const TDesC& aUserID, |
|
403 MDesCArray* aUrlList, |
|
404 const TDesC& aInviteReason, |
|
405 const TInt aValidityPeriod, |
|
406 TImpsCspIdentifier& aCspId ) = 0; |
|
407 |
|
408 /** |
|
409 * Handle invite response |
|
410 * Primitive: HandleInviteResponse |
|
411 * @param aInviteId = ID of the invite request |
|
412 * @param aAcceptance = Was the invitation accepted or not |
|
413 * @param aUserID = UserID of the responding user |
|
414 * @param aScreenName = SName of the responding user |
|
415 * @param aGroupName = Group ID of the responding user |
|
416 * @param aInviteResponse = Textual description of the response |
|
417 * @param aCspId CSP session identifier |
|
418 */ |
|
419 virtual void HandleInviteResponseL( const TDesC& aInviteID, |
|
420 const TBool aAcceptance, |
|
421 const TDesC& aUserID, |
|
422 const TDesC& aScreenName, |
|
423 const TDesC& aGroupName, |
|
424 const TDesC& aResponse, |
|
425 TImpsCspIdentifier& aCspId ) = 0; |
|
426 |
|
427 /** |
|
428 * Handle cancelled invite |
|
429 * Primitive: CancelInviteUserRequest |
|
430 * @param aInviteID = ID of the invitation request |
|
431 * @param aUserID = ID of the cancelling user |
|
432 * @param aScreenName = SName of the canceller |
|
433 * @param aGroupName = GroupID of the canceller |
|
434 * @param aCancelReason = Textual description of |
|
435 * the cancellation |
|
436 * @param aCspId CSP session identifier |
|
437 */ |
|
438 virtual void HandleInviteCancelL( const TDesC& aInviteID, |
|
439 const TDesC& aUserID, |
|
440 const TDesC& aScreenName, |
|
441 const TDesC& aGroupName, |
|
442 const TDesC& aResponse, |
|
443 TImpsCspIdentifier& aCspId ) = 0; |
|
444 |
|
445 /** |
|
446 * Handle server response after request |
|
447 * @param aOpId operation id to map responses to the requests. |
|
448 * @param aCspId CSP session identifier |
|
449 */ |
|
450 virtual void HandleCompleteL( TInt aOperationId, |
|
451 TImpsCspIdentifier& aCspId ) = 0; |
|
452 }; |
|
453 |
|
454 #include "impsfundcli.inl" |
|
455 |
|
456 #endif |