|
1 /* |
|
2 * Copyright (c) 2007 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: Location Centre API interface. |
|
15 * |
|
16 */ |
|
17 /** |
|
18 * @file lcservice.h |
|
19 * |
|
20 * This file provides the interface class to Location Centre. Using this interface |
|
21 * the client application can operate upon components which have registered with |
|
22 * Location Centre. |
|
23 * The components which can register with Location Centre are of two types |
|
24 * - Applications |
|
25 * - Location based services / contents. |
|
26 * |
|
27 * These Client Applications or Services/Contents which register with Location |
|
28 * Centre will be called Location based Application henceforth. |
|
29 * |
|
30 * @lib lcservice.lib |
|
31 * @since S60 v5.0 |
|
32 */ |
|
33 |
|
34 #ifndef C_LCSERVICE_H |
|
35 #define C_LCSERVICE_H |
|
36 |
|
37 // SYSTEM INCLUDES |
|
38 #include <e32base.h> |
|
39 |
|
40 // USER INCLUDES |
|
41 #include "lclocationappinfo.h" |
|
42 |
|
43 // FORWARD DECLARATIONS |
|
44 class CLcServiceImpl; |
|
45 class MLcAppExitObserver; |
|
46 class MLcNotification; |
|
47 class TLcLocationAppFilter; |
|
48 |
|
49 /** |
|
50 * @class CLcService |
|
51 * Interface to Location Centre. |
|
52 * |
|
53 * This class allows the Client application to incorporate Location Centre |
|
54 * and Location Centre related functionalities into their application. |
|
55 * The following are the functionalities exposed by this API. |
|
56 * |
|
57 * - Get the list of Location based Applications registered with Location Centre. |
|
58 * |
|
59 * - Launch Location Centre with a customized set of Location based Application. |
|
60 * |
|
61 * - Launch a particular Location based Application. |
|
62 * |
|
63 * - Register for notification of changes to the state of the Location |
|
64 * based Applications. |
|
65 * |
|
66 * In additon to the above functions, the user can also customize the list |
|
67 * of Location based Applications using the @ref TLcLocationAppFilter filter. |
|
68 * |
|
69 * Since, this class acts as a Client side interface to the Location Centre |
|
70 * server, it is recommended that the Client application creates the |
|
71 * instance of this class during its construction and delete it only on |
|
72 * Exit. |
|
73 * @lib lcservice.lib |
|
74 * @since S60 v5.0 |
|
75 */ |
|
76 class CLcService : public CBase |
|
77 { |
|
78 public: |
|
79 /** |
|
80 * @class CLcLaunchParam |
|
81 * Contains additional parameters for customized Location Centre |
|
82 * launching. It specifies the Location based Application that needs to be |
|
83 * displayed in Location Centre and the mode of launching for each of |
|
84 * these Location based Application when a User selects any of them. This |
|
85 * array of these structures is to be passed as an input to the |
|
86 * overloaded @ref LaunchLocationCentreL function |
|
87 */ |
|
88 class CLcLaunchParam : public CBase |
|
89 { |
|
90 public: |
|
91 /** |
|
92 * Constructs a new instance of Launch parameter object. |
|
93 * |
|
94 * @since S60 v5.0 |
|
95 * @param[in] aAppId Identifier for the Location based Application. |
|
96 * The identifier string is copied. |
|
97 * @param[in] aLaunchMode Launch mode when the terminal user selects |
|
98 * this Location based Application. The values |
|
99 * which this parameter can assume is defined |
|
100 * by the @ref CLcLocationAppInfo::TLcLaunchMode |
|
101 * enumeration. |
|
102 * If the user doesn't define a value for this |
|
103 * parameter then @ref CLcLocationAppInfo::EDefaultMode |
|
104 * is assumed. |
|
105 * @return The new instance of Launch parameter object. |
|
106 * @leave System wide error code if the object creation fails. |
|
107 */ |
|
108 IMPORT_C static CLcLaunchParam* NewL |
|
109 ( const TDesC& aAppId, |
|
110 CLcLocationAppInfo::TLcLaunchMode aLaunchMode = |
|
111 CLcLocationAppInfo::EDefaultMode ); |
|
112 |
|
113 /** |
|
114 * Constructs a new instance of Launch parameters object. |
|
115 * Leaves the created instance on the cleanup stack. |
|
116 * |
|
117 * @since S60 v5.0 |
|
118 * @param[in] aAppId Identifier for the Location based Application. |
|
119 * The identifier string is copied. |
|
120 * @param[in] aLaunchMode Launch mode when the terminal user selects |
|
121 * this Location based Application. The values |
|
122 * which this parameter can assume is defined |
|
123 * by the @ref CLcLocationAppInfo::TLcLaunchMode |
|
124 * enumeration. |
|
125 * If the user doesn't define a value for this |
|
126 * parameter then @ref CLcLocationAppInfo::EDefaultMode |
|
127 * is assumed. |
|
128 * @return The new instance of Launch parameter object. |
|
129 * @leave System wide error code if the object creation fails. |
|
130 */ |
|
131 IMPORT_C static CLcLaunchParam* NewLC |
|
132 ( const TDesC& aAppId, |
|
133 CLcLocationAppInfo::TLcLaunchMode aLaunchMode = |
|
134 CLcLocationAppInfo::EDefaultMode ); |
|
135 |
|
136 /** |
|
137 * Virtual Destructor |
|
138 */ |
|
139 virtual ~CLcLaunchParam(); |
|
140 |
|
141 public: // Non Exported Methods |
|
142 /** |
|
143 * @internal |
|
144 * Gets the Unique identifier identifying the Location Application. |
|
145 * This identifier is defined by the Location Application on registration |
|
146 * with Location Centre. |
|
147 * This is the identifier that must be used by the client of this API for |
|
148 * any operation on the particular Location Application. |
|
149 * A reference to the object's internal string is returned. |
|
150 * |
|
151 * @since S60 v5.0 |
|
152 * @return Unique identifier identifying the Location Application. If the |
|
153 * value of the identifier has not been set then a NULL string |
|
154 * is returned. |
|
155 */ |
|
156 TPtrC Id() const; |
|
157 |
|
158 /** |
|
159 * @internal |
|
160 * Mode in which the Location Application would be launched. |
|
161 * If the mode defined is @ref CLcLocationAppInfo::EDefaultMode, then |
|
162 * the default mode specified by the application when registering with |
|
163 * Location Centre is used. |
|
164 * |
|
165 * @since S60 v5.0 |
|
166 * @return Mode in which the Location Application would be launched. |
|
167 */ |
|
168 CLcLocationAppInfo::TLcLaunchMode LaunchMode() const; |
|
169 |
|
170 private: |
|
171 /** |
|
172 * C++ Default Constructor |
|
173 */ |
|
174 CLcLaunchParam( CLcLocationAppInfo::TLcLaunchMode aLaunchMode ); |
|
175 |
|
176 /** |
|
177 * Second phase of the Symbian two phase construction. |
|
178 */ |
|
179 void ConstructL( const TDesC& aAppId ); |
|
180 |
|
181 private: |
|
182 /** |
|
183 * System wide unique identifier identifying the Location based |
|
184 * Application. This identifier is defined by the Location based |
|
185 * Application on registration with Location Centre. |
|
186 * Owns |
|
187 */ |
|
188 HBufC* iId; |
|
189 |
|
190 /** |
|
191 * Mode in which the Location based Application would be launched. If |
|
192 * the mode defined is @ref CLcLocationAppInfo::EDefaultMode, then |
|
193 * the mode specified by the Location based Application when |
|
194 * registering with Location Centre is used. |
|
195 * If no value is specified for this paramter then it takes |
|
196 * @ref CLcLocationAppInfo::EDefaultMode as its value. |
|
197 */ |
|
198 CLcLocationAppInfo::TLcLaunchMode iLaunchMode; |
|
199 |
|
200 }; |
|
201 |
|
202 public: // Exported Functions |
|
203 /** |
|
204 * Constructs a new instance of Location Centre interface. |
|
205 * |
|
206 * @return The new instance of Location Centre interface object. |
|
207 * @leave System wide error code if the object creation fails. |
|
208 */ |
|
209 IMPORT_C static CLcService* NewL(); |
|
210 |
|
211 /** |
|
212 * Constructs a new instance of Location Centre interface. |
|
213 * Leaves the created instance on the cleanup stack. |
|
214 * |
|
215 * @return The new instance of Location Centre interface object. |
|
216 * @leave System wide error code if the object creation fails. |
|
217 */ |
|
218 IMPORT_C static CLcService* NewLC(); |
|
219 |
|
220 /** |
|
221 * C++ Destructor. |
|
222 * Frees all the resources associated with this Location Centre |
|
223 * interface. |
|
224 */ |
|
225 virtual ~CLcService(); |
|
226 |
|
227 /** |
|
228 * Launches Location Centre as a pop-up dialog with a list of |
|
229 * Location based Application. |
|
230 * |
|
231 * All Location based Applications which can be launched in the |
|
232 * specified mode are displayed in the Location Centre pop-up |
|
233 * dialog. The user can select any of the Location based |
|
234 * Applications displayed in the pop-up list and the |
|
235 * corresponding Location based Application would be launched |
|
236 * in the specified launching mode. |
|
237 * |
|
238 * @since S60 v5.0 |
|
239 * @param [in] aLaunchMode Mode in which the the Location based |
|
240 * Applications displayed in the pop-up |
|
241 * must be launched. The default mode for |
|
242 * launching is the mode in which the |
|
243 * corresponding Location based Application |
|
244 * has registered with Location Centre. |
|
245 * @param[in] aChainedAppExitObserver Observer for notifications of |
|
246 * chained application termination |
|
247 * incase, the user launches any |
|
248 * Location based Application from the |
|
249 * pop-up in the chained mode. If |
|
250 * the user doesn't specify any value |
|
251 * for the observer then no callback |
|
252 * would be given on chained |
|
253 * application termination. |
|
254 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
255 * @leave KErrNotFound - If no Location based Applications were found |
|
256 * with the required configuration. |
|
257 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
258 * generally occurs when the Client application |
|
259 * does not have a UI context. |
|
260 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
261 * prematurely. In this case, all future |
|
262 * requests to Location Centre would also |
|
263 * fail with the same error code. |
|
264 * @leave System wide error code if the operation fails due to some other |
|
265 * reason. |
|
266 */ |
|
267 IMPORT_C void LaunchLocationCentreL( |
|
268 CLcLocationAppInfo::TLcLaunchMode aLaunchMode = CLcLocationAppInfo::EDefaultMode, |
|
269 MLcAppExitObserver* aChainedAppExitObserver = NULL ); |
|
270 |
|
271 /** |
|
272 * Launches Location Centre as a pop-up dialog with a filtered list of |
|
273 * Location based Application. |
|
274 * |
|
275 * The Client application can configure Location Centre to display |
|
276 * only a subset of Location based Applications. This can be achieved |
|
277 * by passing an object of type @ref TLcLocationAppFilter as the |
|
278 * parameter to this function. Only those Location based Applications |
|
279 * which satisfy the filter conditions and can be launched in the |
|
280 * specified mode are displayed in Location Centre. |
|
281 * The user can select any of the Location based Applications displayed |
|
282 * in the pop-up list and the Location based Application would be |
|
283 * launched in the specified launching mode. |
|
284 * |
|
285 * The ownership of the filter is not transferred to Location Centre. |
|
286 * |
|
287 * @since S60 v5.0 |
|
288 * @param[in] aLocationAppFilter Filter that needs to be applied |
|
289 * to customize the list of Location |
|
290 * based Applications to be displayed in |
|
291 * Location Centre. |
|
292 * @param [in] aLaunchMode Mode in which the the Location based |
|
293 * Applications displayed in the pop-up |
|
294 * must be launched. The default mode for |
|
295 * launching is the mode in which the |
|
296 * corresponding Location based application has |
|
297 * registered with Location Centre. |
|
298 * @param[in] aChainedAppExitObserver Observer for notifications of |
|
299 * chained application termination |
|
300 * incase, the user launches any |
|
301 * Location based Application from the |
|
302 * pop-up in the chained mode. Incase, |
|
303 * the user doesn't specify any value |
|
304 * for the observer then no callback |
|
305 * would be given on ahained |
|
306 * application termination. |
|
307 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
308 * @leave KErrNotFound - If no Location based Applications were found |
|
309 * with the required configuration. |
|
310 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
311 * generally occurs when the Client application |
|
312 * does not have a UI context. |
|
313 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
314 * prematurely. In this case, all future |
|
315 * requests to Location Centre would also |
|
316 * fail with the same error code. |
|
317 * @leave System wide error code if the operation fails due to some other |
|
318 * reason. |
|
319 */ |
|
320 IMPORT_C void LaunchLocationCentreL( |
|
321 const TLcLocationAppFilter& aLocationAppFilter, |
|
322 CLcLocationAppInfo::TLcLaunchMode aLaunchMode = CLcLocationAppInfo::EDefaultMode, |
|
323 MLcAppExitObserver* aChainedAppExitObserver = NULL ); |
|
324 |
|
325 /** |
|
326 * Launches Location Centre with the specified array of Location |
|
327 * based Applications in a pop-up dialog. |
|
328 * |
|
329 * The items of the array are first validated for their registration |
|
330 * with Location Centre and only those Location based Applications which are |
|
331 * registered with Location Centre and which can be launched in the |
|
332 * specified launch mode are displayed. |
|
333 * The user can select any of the Location based Application displayed in the |
|
334 * pop-up list and the corresponding Location based Application would be opened |
|
335 * the mode defined in the corresponding @ref TLcLaunchParam |
|
336 * object. |
|
337 * |
|
338 * The ownership of the specified array is not tranferred to Location |
|
339 * Centre. |
|
340 * |
|
341 * @since S60 v5.0 |
|
342 * @param[in] aIncludeAppArray Array of Location based Applications which |
|
343 * are to be displayed in Location Centre. |
|
344 * @param[in] aChainedAppExitObserver Observer for notifications of |
|
345 * chained application termination |
|
346 * incase, the user launches any |
|
347 * Location based Application from the |
|
348 * pop-up in the chained mode. Incase, |
|
349 * the user doesn't specify any value |
|
350 * for the observer then no callback |
|
351 * would be given on chained |
|
352 * application termination. |
|
353 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
354 * @leave KErrNotFound - If none of the specified Location based |
|
355 * Applications were found registered with |
|
356 * Location Centre. |
|
357 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
358 * generally occurs when the Client application |
|
359 * does not have a UI context. |
|
360 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
361 * prematurely. In this case, all future |
|
362 * requests to Location Centre would also |
|
363 * fail with the same error code. |
|
364 * @leave System wide error code if the operation fails due to some other |
|
365 * reason. |
|
366 */ |
|
367 IMPORT_C void LaunchLocationCentreL( |
|
368 const RPointerArray<CLcLaunchParam>& aIncludeAppArray, |
|
369 MLcAppExitObserver* aChainedAppExitObserver = NULL ); |
|
370 |
|
371 /** |
|
372 * Launches Location Centre without the specified array of |
|
373 * Location based Applications in a pop-up dialog. |
|
374 * |
|
375 * Only those Location based Applications which are not a part of the |
|
376 * specified array and which can be launched in the specified mode |
|
377 * are displayed in Location Centre. |
|
378 * The user can select any of the Location based Application displayed in the |
|
379 * pop-up list and the corresponding Location based Application would be opened |
|
380 * the mode defined in the specified mode. |
|
381 * |
|
382 * The ownership of the specified array is not tranferred to Location |
|
383 * Centre. |
|
384 * |
|
385 * @since S60 v5.0 |
|
386 * @param[in] aExcludeAppArray Array of identifiers of Location based |
|
387 * Application which are not to be displayed |
|
388 * in Location Centre. |
|
389 * These identifiers are to be defined by the |
|
390 * Location based Application on registration with |
|
391 * Location Centre. |
|
392 * @param [in] aLaunchMode Mode in which the all the Location |
|
393 * applications displayed in the pop-up |
|
394 * must be launched. The default mode for |
|
395 * launching is the mode in which the |
|
396 * corresponding application has registered |
|
397 * with Location Centre. |
|
398 * @param[in] aChainedAppExitObserver Observer for notifications of |
|
399 * chained application termination |
|
400 * incase, the user launches any |
|
401 * Location based Application from the |
|
402 * pop-up in the chained mode. Incase, |
|
403 * the user doesn't specify any value |
|
404 * for the observer then no callback |
|
405 * would be given on chained |
|
406 * application termination. |
|
407 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
408 * @leave KErrNotFound - If no Location based Applications were found |
|
409 * with the required configuration. |
|
410 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
411 * generally occurs when the Client application |
|
412 * does not have a UI context. |
|
413 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
414 * prematurely. In this case, all future |
|
415 * requests to Location Centre would also |
|
416 * fail with the same error code. |
|
417 * @leave System wide error code if the operation fails due to some other |
|
418 * reason. |
|
419 */ |
|
420 IMPORT_C void LaunchLocationCentreL( |
|
421 const RArray<TPtrC>& aExcludeAppArray, |
|
422 CLcLocationAppInfo::TLcLaunchMode aLaunchMode = CLcLocationAppInfo::EDefaultMode, |
|
423 MLcAppExitObserver* aChainedAppExitObserver = NULL ); |
|
424 |
|
425 /** |
|
426 * Launches Location Centre as a pop-up dialog with a list of |
|
427 * Location based Applications and the user can select a Location |
|
428 * based Application from the pop-up list displayed. |
|
429 * |
|
430 * @since S60 v5.0 |
|
431 * @return If the terminal User has selected a Location based Application, |
|
432 * Unique identifier identifying the Location based Application |
|
433 * which was selected. |
|
434 * NULL string incase the terminal User cancelled the pop-up dialog. |
|
435 * The string returned is a reference to this object's internal string. Hence, |
|
436 * the Client Application must copy the string if it expects to retain |
|
437 * it. |
|
438 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
439 * @leave KErrNotFound - If no Location based Applications were found. |
|
440 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
441 * generally occurs when the Client application |
|
442 * does not have a UI context. |
|
443 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
444 * prematurely. In this case, all future |
|
445 * requests to Location Centre would also |
|
446 * fail with the same error code. |
|
447 * @leave System wide error code if the operation fails due to some other |
|
448 * reason. |
|
449 */ |
|
450 IMPORT_C TPtrC SelectLocationApplicationL(); |
|
451 |
|
452 /** |
|
453 * Launches Location Centre as a pop-up dialog with a filtered list of |
|
454 * Location based Applications and the user can select a Location |
|
455 * based Application from the pop-up list displayed. |
|
456 * |
|
457 * The Client application can configure Location Centre to display |
|
458 * only a subset of Location based Applications. This can be achieved |
|
459 * by passing an object of type @ref TLcLocationAppFilter as the |
|
460 * parameter to this function. Only those Location based Applications |
|
461 * which satisfy the filter conditions are displayed in Location Centre. |
|
462 * The user can select any of the Location based Applications displayed |
|
463 * in the pop-up list and the identifier corresponding to the selected |
|
464 * Location based Application would be returned back to the user. |
|
465 * |
|
466 * The ownership of the filter is not transferred to Location Centre. |
|
467 * |
|
468 * @since S60 v5.0 |
|
469 * @param[in] aLocationAppFilter Filter that needs to be applied |
|
470 * to customize the list of Location |
|
471 * based Applications to be displayed in |
|
472 * Location Centre. |
|
473 * @return If the terminal User has selected a Location based Application, |
|
474 * Unique identifier identifying the Location based Application |
|
475 * which was selected. |
|
476 * NULL string incase the terminal User cancelled the pop-up dialog. |
|
477 * The string returned is a reference to this object's internal string. Hence, |
|
478 * the Client Application must copy the string if it expects to retain |
|
479 * it. |
|
480 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
481 * @leave KErrNotFound - If no Location based Applications were found. |
|
482 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
483 * generally occurs when the Client application |
|
484 * does not have a UI context. |
|
485 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
486 * prematurely. In this case, all future requests |
|
487 * to Location Centre would also fail with |
|
488 * the same error code. |
|
489 * @leave System wide error code if the operation fails due to some other |
|
490 * reason. |
|
491 */ |
|
492 IMPORT_C TPtrC SelectLocationApplicationL( |
|
493 const TLcLocationAppFilter& aLocationAppFilter ); |
|
494 |
|
495 /** |
|
496 * Launches Location Centre with based Applications in a pop-up |
|
497 * dialog and the user can select a Location based Application |
|
498 * from the pop-up list displayed. |
|
499 * |
|
500 * The Client application can configure Location Centre to either |
|
501 * display only those Location based Applications specified in |
|
502 * the array or to display all Location based Applications other |
|
503 * than those specified in the array. |
|
504 * The user can select any of the Location based Application displayed |
|
505 * in the pop-up list and the identifier corresponding to the selected |
|
506 * Location based Application would be returned back to the user. |
|
507 * |
|
508 * The ownership of the specified array is not tranferred to Location |
|
509 * Centre. |
|
510 * |
|
511 * @since S60 v5.0 |
|
512 * @param[in] aArray Array of Location based Applications which |
|
513 * are to be displayed in Location Centre. |
|
514 * @param[in] aIncludeFlag If the flag value is |
|
515 * - ETrue, then only those Location based |
|
516 * Applications specified in the array would |
|
517 * be displayed in Location Centre. |
|
518 * - EFalse, then all Location based Applications |
|
519 * other than those specified in the array |
|
520 * would be displayed in Location Centre. |
|
521 * @return If the terminal User has selected a Location based Application, |
|
522 * Unique identifier identifying the Location based Application |
|
523 * which was selected. |
|
524 * The string returned is a reference to this object's internal string. Hence, |
|
525 * the Client Application must copy the string if it expects to retain |
|
526 * it. |
|
527 * NULL string incase the terminal User cancelled the pop-up dialog. |
|
528 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
529 * @leave KErrNotFound - If none of the specified Location based |
|
530 * Applications were found registered with |
|
531 * Location Centre. |
|
532 * @leave KErrNotSupported - If Location Centre cannot be launched. This |
|
533 * generally occurs when the Client application |
|
534 * does not have a UI context. |
|
535 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
536 * prematurely. In this case, all future |
|
537 * requests to Location Centre would also |
|
538 * fail with the same error code. |
|
539 * @leave System wide error code if the operation fails due to some other |
|
540 * reason. |
|
541 */ |
|
542 IMPORT_C TPtrC SelectLocationApplicationL( |
|
543 const RArray<TPtrC>& aAppArray, |
|
544 TBool aIncludeFlag ); |
|
545 |
|
546 /** |
|
547 * Gets a list of all Location based Applications. |
|
548 * |
|
549 * This function returns a list of all Location based Applications |
|
550 * to the caller. |
|
551 * |
|
552 * The ownership of the list of Location based Applications is |
|
553 * transferred to the caller. |
|
554 * |
|
555 * @since S60 v5.0 |
|
556 * @param[in] aLocationAppFilter Filter that needs to be applied |
|
557 * to customize the list of Location |
|
558 * Applications to be retrieved from |
|
559 * Location Centre. |
|
560 * @return CLcLocationAppInfoArray object containing a list |
|
561 * of applications registered with Location Centre. |
|
562 * @leave KErrNotFound, If there are no Location based Applications |
|
563 * available. |
|
564 * @leave KErrInUse - If there is an outstanding request present on Location Centre. |
|
565 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
566 * prematurely. In this case, all future |
|
567 * requests to Location Centre would also |
|
568 * fail with the same error code. |
|
569 * @leave System wide error code if the array retrieval fails for |
|
570 * any other reason. |
|
571 */ |
|
572 IMPORT_C CLcLocationAppInfoArray* GetLocationApplicationsL(); |
|
573 |
|
574 /** |
|
575 * Gets a list of all Location based Applications. |
|
576 * |
|
577 * This is an asynchronous version and at any instant of time there |
|
578 * can be only one such request outstanding. |
|
579 * |
|
580 * The ownership of the list of Location based Applications is |
|
581 * transferred to the caller. |
|
582 * |
|
583 * @since S60 v5.0 |
|
584 * @param[out] aStatus Status variable on which the completion of the |
|
585 * request would be communicated. The following |
|
586 * are the values which the variable can assume |
|
587 * on completion of the request. |
|
588 * Since, the CLcService class will use its internal |
|
589 * Active object for interacting with the Location |
|
590 * Centre server and not this aStatus directly, the |
|
591 * Client application must not use User::WaitforRequest |
|
592 * on this status variable. |
|
593 * - KErrNone, If the list of applications was |
|
594 * successfully retrieved. |
|
595 * - KErrInUse, If there is an outstanding |
|
596 * request present on Location Centre. |
|
597 * - KErrNotFound, If there are no Location |
|
598 * based Applications available. |
|
599 * - KErrCancel, If an outstanding request is |
|
600 * Cancelled. |
|
601 * - KErrServerTerminated - If the Location Centre |
|
602 * server terminates prematurely. In this |
|
603 * case, all future requests to Location |
|
604 * Centre would also fail with the same |
|
605 * error code. |
|
606 * - System wide error code if the array retrieval |
|
607 * fails for any other reason. |
|
608 * @param[out] aAppInfoArray Reference to the pointer of Application |
|
609 * information array. This pointer would be |
|
610 * updated with the @ref CLcLocationAppInfoArray |
|
611 * object containing a list of applications |
|
612 * registered with Location Centre on the |
|
613 * asynchronous completion of this function. |
|
614 */ |
|
615 IMPORT_C void GetLocationApplications( |
|
616 TRequestStatus& aStatus, |
|
617 CLcLocationAppInfoArray*& aAppInfoArray ); |
|
618 |
|
619 /** |
|
620 * Gets a filtered list of Location based Applications. |
|
621 * |
|
622 * The Client application can configure the list of Location based |
|
623 * Applications returned. This can be achieved by passing an object |
|
624 * of type @ref TLcLocationAppFilter as the parameter to this function. |
|
625 * |
|
626 * The ownership of the filter is not transferred to Location Centre. |
|
627 * |
|
628 * The ownership of the list of Location based Applications is |
|
629 * transferred to the caller. |
|
630 * |
|
631 * @since S60 v5.0 |
|
632 * @param[in] aLocationAppFilter Filter that needs to be applied |
|
633 * to customize the list of Location |
|
634 * Applications to be retrieved from |
|
635 * Location Centre. |
|
636 * @return CLcLocationAppInfoArray object containing a list |
|
637 * of applications registered with Location Centre. |
|
638 * @leave KErrNotFound If there are no Location based Applications |
|
639 * corresponding to the filter paramter. |
|
640 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
641 * prematurely. In this case, all future |
|
642 * requests to Location Centre would also |
|
643 * fail with the same error code. |
|
644 * @leave System wide error code if the array retrieval fails for |
|
645 * any other reason. |
|
646 */ |
|
647 IMPORT_C CLcLocationAppInfoArray* GetLocationApplicationsL( |
|
648 const TLcLocationAppFilter& aLocationAppFilter ); |
|
649 |
|
650 /** |
|
651 * Gets a filted list of Location based Applications. |
|
652 * |
|
653 * The Client application can configure the list of Location based |
|
654 * Applications returned. This can be achieved by passing an object |
|
655 * of type @ref TLcLocationAppFilter as the parameter to this function. |
|
656 * This is an asynchronous version and at any instant of time there |
|
657 * can be only one such request outstanding. |
|
658 * |
|
659 * The ownership of the filter is not transferred to Location Centre. |
|
660 * |
|
661 * The ownership of the list of Location based Applications is |
|
662 * transferred to the caller. |
|
663 * |
|
664 * @since S60 v5.0 |
|
665 * @param[out] aStatus Status variable on which the completion of the |
|
666 * request would be communicated. The following |
|
667 * are the values which the variable can assume |
|
668 * on completion of the request. |
|
669 * Since, the CLcService class will use its internal |
|
670 * Active object for interacting with the Location |
|
671 * Centre server and not this aStatus directly, the |
|
672 * Client application must not use User::WaitforRequest |
|
673 * on this status variable. |
|
674 * - KErrNone, If the list of applications was |
|
675 * successfully retrieved. |
|
676 * - KErrInUse, If there is an outstanding |
|
677 * request present. |
|
678 * - KErrCancel, If an outstanding request is |
|
679 * Cancelled. |
|
680 * - KErrServerTerminated - If the Location Centre |
|
681 * server terminates prematurely. In |
|
682 * this case, all future requests to |
|
683 * Location Centre would also fail with |
|
684 * the same error code. |
|
685 * - System wide error code if the array retrieval |
|
686 * fails for any other reason. |
|
687 * @param[in] aLocationAppFilter Filter that needs to be applied |
|
688 * to customize the list of Location |
|
689 * Applications to be retrieved from |
|
690 * Location Centre. |
|
691 * @param[out] aAppInfoArray Reference to the pointer of Application |
|
692 * information array. This pointer would be |
|
693 * updated with the @ref CLcLocationAppInfoArray |
|
694 * object containing a list of applications |
|
695 * registered with Location Centre on the |
|
696 * asynchronous completion of this function. |
|
697 */ |
|
698 IMPORT_C void GetLocationApplications( |
|
699 TRequestStatus& aStatus, |
|
700 const TLcLocationAppFilter& aLocationAppFilter, |
|
701 CLcLocationAppInfoArray*& aAppInfoArray ); |
|
702 |
|
703 /** |
|
704 * Cancels an outstanding @ref GetLocationApplications request. |
|
705 */ |
|
706 IMPORT_C void CancelGetLocationApplications(); |
|
707 |
|
708 /** |
|
709 * Launches a Location based Application in the desired mode. |
|
710 * |
|
711 * The identifier passed to te function is first validated for |
|
712 * existence and registration with Location Centre. Incase, the |
|
713 * Location based Application exists and its has already registered with |
|
714 * Location Centre, then the function launches the Location |
|
715 * Application in the desired mode. |
|
716 * |
|
717 * @since S60 v5.0 |
|
718 * @param[in] aAppIdentifier Unique identifier identifying the |
|
719 * Location based Application. |
|
720 * @param [in] aLaunchMode Mode in which the all the Location based |
|
721 * Applications displayed in the pop-up |
|
722 * must be launched. The default mode for |
|
723 * launching is the mode in which the |
|
724 * corresponding Location based Application |
|
725 * has registered with Location Centre. |
|
726 * @param[in] aChainedAppExitObserver Observer for notifications of |
|
727 * chained application termination |
|
728 * incase, the user launches any |
|
729 * Location based Application from the |
|
730 * pop-up in the chained mode. Incase, |
|
731 * the user doesn't specify any value |
|
732 * for the observer then no callback |
|
733 * would be given on chained |
|
734 * application termination. If a value |
|
735 * is specified for the observer for |
|
736 * Stand alone lauunching then the |
|
737 * Observer value would be ignored. |
|
738 * @leave KErrNotFound, If there is no Location based Application |
|
739 * corresponding to the identifer or if the Location |
|
740 * based Application cannot be launched in the |
|
741 * specified mode. |
|
742 * @leave KErrInUse - If there is an outstanding request present on Location |
|
743 * Centre. |
|
744 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
745 * prematurely. In this case, all future |
|
746 * requests to Location Centre would also fail |
|
747 * with the same error code. |
|
748 * @leave System wide error code if the operation fails for any other |
|
749 * reason. |
|
750 */ |
|
751 IMPORT_C void LaunchLocationApplicationL( |
|
752 const TDesC& aAppIdentifier, |
|
753 CLcLocationAppInfo::TLcLaunchMode aLaunchMode = CLcLocationAppInfo::EDefaultMode, |
|
754 MLcAppExitObserver* aChainedAppExitObserver = NULL ); |
|
755 |
|
756 /** |
|
757 * Sets an observer for notifying changes to the Location Centre server. |
|
758 * |
|
759 * The notification can occur under the following conditions |
|
760 * - When a new Location based Application registers into Location Centre. |
|
761 * In this case, the Location based Application would be immediately available |
|
762 * for all Location Centre operations. |
|
763 * - When an already registered Location based Application de-registers. |
|
764 * In this case, the Location based Application will be removed from Location |
|
765 * Centre. Hence, it would not be available for any further Location Centre |
|
766 * operations. |
|
767 * - When a Location based Application is present on a removable media |
|
768 * (like Memory card) and the media is removed. In this case, for all practical |
|
769 * purposes the Location based Application behaves as in the previous context. |
|
770 * The difference being that the Location based Application does not get removed |
|
771 * from Location Centre but is marked as an Absent application. When the |
|
772 * removable media is re-inserted, the Location based Application immediately |
|
773 * becomes available for all Location Centre operations. |
|
774 * - When an removable media containing an Absent Application is re-inserted. In |
|
775 * this case, the Location based Application would be immediately available for |
|
776 * all Location Centre operations. |
|
777 * - When the Location Centre server terminates pre-maturely. In this case, no |
|
778 * further notifications would be given to the Client application and all |
|
779 * further requests to the Location Centre server would fail with |
|
780 * @p KErrServerTerminated. |
|
781 * |
|
782 * @since S60 v5.0 |
|
783 * @param[in] aObserver Observer to which notification would be issued. |
|
784 * @leave KErrAlreadyExists If the observer has already been set. |
|
785 * @leave KErrServerTerminated - If the Location Centre server terminates |
|
786 * prematurely. In this case, all future requests to |
|
787 * Location Centre would also fail with the same |
|
788 * error code. |
|
789 */ |
|
790 IMPORT_C void SetObserverL( MLcNotification& aObserver ); |
|
791 |
|
792 /** |
|
793 * Removes the observer that has already been set using the @ref SetObserverL method. |
|
794 * |
|
795 * @since S60 v5.0 |
|
796 * @return KErrNone, If the observer removal was successful. |
|
797 * KErrNotFound, If no observer was set previously. |
|
798 */ |
|
799 IMPORT_C TInt RemoveObserver(); |
|
800 |
|
801 private: |
|
802 /** |
|
803 * Default C++ Constructor. |
|
804 */ |
|
805 CLcService(); |
|
806 |
|
807 /** |
|
808 * Overloaded Copy Constructor. By default, prohibit copy constructor |
|
809 * |
|
810 * @param[in] aLocationCentre Location Centre interface object from which the new |
|
811 * object should be constructed. |
|
812 */ |
|
813 CLcService( const CLcService& aLocationCentre ); |
|
814 |
|
815 /** |
|
816 * Overloaded Assignment operator. By default, prohibit assignment |
|
817 * operator |
|
818 * |
|
819 * @param[in] aLocationCentre Location Centre interface object from which the new |
|
820 * object should be assigned. |
|
821 * @return the Location Centre interface object after assigment. |
|
822 */ |
|
823 CLcService& operator= ( |
|
824 const CLcService& aLCAppInfo ); |
|
825 |
|
826 /** |
|
827 * Second phase of the two phase constructor. |
|
828 */ |
|
829 void ConstructL(); |
|
830 |
|
831 private: // Data |
|
832 /** |
|
833 * Location Centre Implementation. Hides the actual implementation |
|
834 * of the Location Centre API. |
|
835 * |
|
836 * Owns |
|
837 */ |
|
838 CLcServiceImpl* iImplementation; |
|
839 }; |
|
840 |
|
841 #endif // C_LCSERVICE_H |