|
1 /* |
|
2 * Copyright (c) 2006 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: Abstract base class for location triggering entries |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef LBTTRIGGERENTRY_H |
|
20 #define LBTTRIGGERENTRY_H |
|
21 |
|
22 #include <lbtcommon.h> |
|
23 #include <lbs.h> |
|
24 |
|
25 class CLbtTriggerConditionBase; |
|
26 |
|
27 /** |
|
28 * Abstract base class for location triggering entries. |
|
29 * |
|
30 * It provides methods to determine the trigger type and to define |
|
31 * basic trigger attributes. The following attributes are defined |
|
32 * in location triggering entries. |
|
33 * |
|
34 * - <B>Id</B> Defines the identity of a trigger. The Id is allocated |
|
35 * by Location Triggering Server and it's unique among all triggers |
|
36 * currently exist in the system. If a trigger is removed from the system, |
|
37 * its Id may be reused by another trigger. |
|
38 * This attribute can not be modified after the trigger is created. |
|
39 * |
|
40 * - <B>Name</B> The name attribute defines a human-readable name for |
|
41 * the trigger. The purpose of the name attribute is mainly for the end |
|
42 * user to be able to identify the trigger in the UI. The maximum length |
|
43 * of the name is @p KLbtMaxNameLength characters. This attribute can |
|
44 * be modified after the trigger is created. |
|
45 * |
|
46 * - <B>State</B> This attribute specifies if the trigger is enabled |
|
47 * or disabled. A disabled trigger is not supervised by the Location |
|
48 * Triggering Server and thus will never be fired. This attribute can |
|
49 * be modified after the trigger is created. |
|
50 * |
|
51 * - <B>Requestors</B> The requestors attribute consists of a requestor stack |
|
52 * with contacts and/or services using the location service. Requestor |
|
53 * information is used for privacy queries when trigger is created |
|
54 * and fired. Requestor information is not allowed to be changed |
|
55 * once the trigger has been created. |
|
56 * |
|
57 * - <B>Manager UI</B>. Manager UI is the UI application that can view, edit |
|
58 * and delete the trigger. Manager UI application shall be provided by the user |
|
59 * of this API. If it's possible, client application must specify the manager |
|
60 * UI application when the trigger is created. Note, Manager UI may be different |
|
61 * from the trigger's owner. Trigger's owner is the process that created the |
|
62 * trigger. Triggers can be directly accessed by the Manager UI application. |
|
63 * Although this attribute is not mandatory when creating a trigger. it's |
|
64 * highly recommended that it is specified. It cannot be modified after the |
|
65 * trigger is created. |
|
66 * |
|
67 * - <B>Trigger condition</B>. Trigger condition specifies in what situation |
|
68 * a trigger shall be fired. Current system supports only basic trigger |
|
69 * condition. Basic trigger condition is defined by a trigger area and |
|
70 * direction of terminal's movement. Only circular area can be used as |
|
71 * trigger area in current system. This attribute can be modified after |
|
72 * the trigger is created. |
|
73 * |
|
74 * @lib lbt.lib |
|
75 * @since S60 5.1 |
|
76 */ |
|
77 class CLbtTriggerEntry : public CBase |
|
78 { |
|
79 public: |
|
80 /** |
|
81 * Trigger type definition. It defines the type of the trigger |
|
82 * entry. |
|
83 */ |
|
84 enum TType |
|
85 { |
|
86 /** |
|
87 * Session trigger |
|
88 */ |
|
89 ETypeSession = 1, |
|
90 /** |
|
91 * Start-up trigger |
|
92 */ |
|
93 ETypeStartup = 2 |
|
94 }; |
|
95 |
|
96 /** |
|
97 * Trigger attributes identifications. |
|
98 * |
|
99 * These ids can be combined and used to form an attribute mask when |
|
100 * retrieving partial attributes from Location Triggering Server. |
|
101 */ |
|
102 enum TAttribute |
|
103 { |
|
104 /** |
|
105 * Trigger Id |
|
106 */ |
|
107 EAttributeId = 0x0001, |
|
108 /** |
|
109 * Trigger name |
|
110 */ |
|
111 EAttributeName = 0x0002, |
|
112 /** |
|
113 * Trigger state |
|
114 */ |
|
115 EAttributeState = 0x0004, |
|
116 /** |
|
117 * Trigger requestor |
|
118 */ |
|
119 EAttributeRequestor = 0x0008, |
|
120 /** |
|
121 * Trigger manager UI |
|
122 */ |
|
123 EAttributeManagerUi = 0x0010, |
|
124 /** |
|
125 * Trigger rearm time |
|
126 */ |
|
127 EAttributeRearmTime = 0x0020, |
|
128 /** |
|
129 * Trigger condition |
|
130 */ |
|
131 EAttributeCondition = 0x0080, |
|
132 /** |
|
133 * Process ID of start-up trigger. It includes |
|
134 * process executable name and process UID type. |
|
135 */ |
|
136 EAttributeStartUpProcessId = 0x0100, |
|
137 /** |
|
138 * Command-line argument string for start-up trigger |
|
139 */ |
|
140 EAttributeStartUpCommandLine = 0x0200, |
|
141 |
|
142 }; |
|
143 |
|
144 |
|
145 /** |
|
146 * Specifies the state of a trigger. |
|
147 */ |
|
148 enum TLbtTriggerState |
|
149 { |
|
150 /** |
|
151 * The trigger is enabled |
|
152 */ |
|
153 EStateEnabled = 1, |
|
154 /** |
|
155 * The trigger is disabled |
|
156 */ |
|
157 EStateDisabled = 2 |
|
158 }; |
|
159 |
|
160 /** |
|
161 * Destructor |
|
162 */ |
|
163 IMPORT_C virtual ~CLbtTriggerEntry(); |
|
164 |
|
165 /** |
|
166 * Gets the type of the trigger. |
|
167 * |
|
168 * @return The type of trigger entry. |
|
169 */ |
|
170 IMPORT_C virtual TType Type() const = 0; |
|
171 |
|
172 /** |
|
173 * Gets the trigger ID. |
|
174 * |
|
175 * The ID is allocated and set by the Location Triggering Server when a |
|
176 * trigger is successfully created. Trigger ID is unique in the system. |
|
177 * This function returns @p KLbtNullTriggerId if the ID is not |
|
178 * set before. |
|
179 * |
|
180 * @return The ID of the trigger entry, or @p KLbtNullTriggerId if the |
|
181 * trigger ID has not been set. |
|
182 */ |
|
183 IMPORT_C const TLbtTriggerId& Id() const; |
|
184 |
|
185 /** |
|
186 * Sets trigger entry id. SetId is not used during trigger creation as it |
|
187 * is auto generated by the LBT server. This information is only used during |
|
188 * deletion / modification of triggers. This information when specified |
|
189 * during trigger creation, will be ignored by LBT server. |
|
190 * |
|
191 * @param[in] aId The ID of the trigger entry, or @p KLbtNullTriggerId. |
|
192 */ |
|
193 IMPORT_C void SetId( TLbtTriggerId aId ); |
|
194 |
|
195 /** |
|
196 * Gets the name of the trigger entry. |
|
197 * |
|
198 * If the name is not set, an empty string is returned. Maximum |
|
199 * length of the name is @p KLbtMaxNameLength. |
|
200 * |
|
201 * @return The name of the trigger entry. |
|
202 */ |
|
203 IMPORT_C const TDesC& Name() const; |
|
204 |
|
205 /** |
|
206 * Sets the name of the trigger entry. |
|
207 * |
|
208 * @param[in] aName The name of the trigger entry. |
|
209 * @leave KErrArgument If the name of the trigger is longer than |
|
210 * @p KLbtMaxNameLength. |
|
211 */ |
|
212 IMPORT_C void SetNameL( const TDesC& aName ); |
|
213 |
|
214 /** |
|
215 * Gets the rearm time interval. |
|
216 * |
|
217 * If no interval is specified for the trigger, this function |
|
218 * returns |
|
219 * @p KLbtDefaultTimeToRearm which is 600s or 10 minutes. |
|
220 * |
|
221 * @return Rearm time interval. |
|
222 */ |
|
223 IMPORT_C TInt TimeToRearm() const; |
|
224 |
|
225 /** |
|
226 * Sets the time interval to reactivate the trigger after the |
|
227 * trigger is fired. |
|
228 * |
|
229 * @param[in] aSeconds The time interval after which the trigger |
|
230 * is set effective by the Location Triggering Server. Client |
|
231 * applications can set 0 to indicate no delay, in which case |
|
232 * the trigger will remain effective through out its life span. |
|
233 * Range is 0 (KLbtMinTimeToRearm) to +2147483647 (KLbtMaxTimeToRearm) |
|
234 * which is +24855 days (approximately 68 years) |
|
235 * @panic KErrArgument If the time set is out of range. |
|
236 */ |
|
237 IMPORT_C void SetTimeToRearm( TInt aSeconds ); |
|
238 |
|
239 /** |
|
240 * Gets trigger entry state. |
|
241 * |
|
242 * If no state has been set for the trigger, this function returns |
|
243 * @p ELbtTriggerEnabled. |
|
244 * |
|
245 * @return The trigger entry state. |
|
246 */ |
|
247 IMPORT_C TLbtTriggerState State() const; |
|
248 |
|
249 /** |
|
250 * Sets the trigger entry state. |
|
251 * |
|
252 * @param[in] aState The trigger entry state. |
|
253 */ |
|
254 IMPORT_C void SetState( TLbtTriggerState aState ); |
|
255 |
|
256 /** |
|
257 * Gets requestors of the trigger entry. |
|
258 * |
|
259 * Requestor information is used by the Location Triggering Server to |
|
260 * verify that the user allows location information to be sent to |
|
261 * the specified requestors when a trigger fires. |
|
262 * |
|
263 * Requestors attribute is a mandatory trigger attribute. If the requestors |
|
264 * attribute is not set when the trigger is created in the server, the |
|
265 * trigger creation will fail. |
|
266 * |
|
267 * If requestors have not been set before, this function returns |
|
268 * an empty requestor stack. |
|
269 * |
|
270 * Refer to Location Acquisition API for detailed information on |
|
271 * requestors. |
|
272 * |
|
273 * @see RLbt::CreateTriggerL() |
|
274 * @see RRequestorStack |
|
275 * |
|
276 * @param[out] aRequestors The requestors of the trigger entry. |
|
277 */ |
|
278 IMPORT_C void GetRequestorsL( RRequestorStack& aRequestors ) const; |
|
279 |
|
280 /** |
|
281 * Sets requestors of trigger entry. |
|
282 * |
|
283 * Requestor information is used by the Location Triggering Server to |
|
284 * verify that the user allows location information to be sent to |
|
285 * the specified requestors when a trigger fires. |
|
286 * |
|
287 * Requestors attribute is a mandatory trigger attribute. If the requestors |
|
288 * attribute is not set when the trigger is created in the server, the |
|
289 * trigger creation will fail. |
|
290 * |
|
291 * Refer to Location Acquisition API for detailed information on |
|
292 * requestors. |
|
293 * |
|
294 * @see RLbt::CreateTriggerL() |
|
295 * |
|
296 * @param[in] aRequestors The requestors of trigger entry. |
|
297 * @leave KErrArgument The stack contains no requestors. |
|
298 */ |
|
299 IMPORT_C void SetRequestorsL( const RRequestorStack& aRequestors ); |
|
300 |
|
301 /** |
|
302 * Sets requestor of trigger entry. |
|
303 * |
|
304 * Requestor information is used by the Location Triggering Server to |
|
305 * verify that the user allows information to be sent to the specified |
|
306 * requestors when a trigger fires. |
|
307 * |
|
308 * Requestors attribute is a mandatory trigger attribute. If the requestors |
|
309 * attribute is not set when the trigger is created in the server, the |
|
310 * trigger creation will fail. |
|
311 * |
|
312 * @see RLbt::CreateTriggerL() |
|
313 * |
|
314 * @param[in] aType identifies the type of requestor, a service or a contact. |
|
315 * @param[in] aFormat determines the type of data held in aData |
|
316 * @param[in] aData is requestor data. Can be a telephone number, a URL etc. |
|
317 */ |
|
318 IMPORT_C void SetRequestorL( |
|
319 CRequestor::TRequestorType aType, |
|
320 CRequestor::TRequestorFormat aFormat, |
|
321 const TDesC& aData ); |
|
322 |
|
323 /** |
|
324 * Gets UID of the manager UI. The UID means |
|
325 * the UID3 value, which identifies the particular application. |
|
326 * If the UID of the manager UI is not set, this function |
|
327 * returns KNullUid. |
|
328 * |
|
329 * @return The UID of manager UI application. KNullUid if the UID |
|
330 * has not been set. |
|
331 */ |
|
332 IMPORT_C TUid ManagerUi() const; |
|
333 |
|
334 /** |
|
335 * Sets UID of the manager UI. |
|
336 * |
|
337 * @param[in] aUid The SID value if available. Else the UID3 value, which is |
|
338 * the idenfifier of the particaular application. KNullUid can be used to |
|
339 * remove previous setting. |
|
340 */ |
|
341 IMPORT_C void SetManagerUi( TUid aUid ); |
|
342 |
|
343 /** |
|
344 * Gets the trigger condition. |
|
345 * |
|
346 * The ownership of the returned trigger condition object is |
|
347 * not transferred to the client. The pointer can be |
|
348 * used to modify the trigger condition. |
|
349 * |
|
350 * @return A non-const pointer to the trigger's |
|
351 * trigger condition. NULL if the trigger condition is not set. |
|
352 */ |
|
353 IMPORT_C CLbtTriggerConditionBase* GetCondition(); |
|
354 |
|
355 /** |
|
356 * Gets the trigger condition. |
|
357 * |
|
358 * The ownership of the returned trigger condition object is |
|
359 * not transferred to the client. The pointer can be |
|
360 * used to modify the trigger condition. |
|
361 * |
|
362 * @return A const pointer to the trigger's |
|
363 * trigger condition. NULL if the trigger condition is not set. |
|
364 */ |
|
365 IMPORT_C const CLbtTriggerConditionBase* GetCondition() const; |
|
366 |
|
367 /** |
|
368 * Sets trigger condition. |
|
369 * |
|
370 * This object takes the ownership of the trigger condition object. |
|
371 * |
|
372 * @param[in] aCondition Pointer to the new trigger condition object. |
|
373 * This object takes the ownership of aCondition. NULL can be used |
|
374 * to remove previous setting. |
|
375 */ |
|
376 IMPORT_C void SetCondition( CLbtTriggerConditionBase* aCondition ); |
|
377 |
|
378 /** |
|
379 * Internalizes the trigger object's details and attributes |
|
380 * from stream. |
|
381 * |
|
382 * The presence of this function means that the standard template |
|
383 * operator>>() ( defined in s32strm.h ) is available to internalize objects |
|
384 * of this class. |
|
385 * |
|
386 * @param[in] aStream Stream from which the object should be internalized. |
|
387 */ |
|
388 IMPORT_C void InternalizeL( RReadStream& aStream ); |
|
389 |
|
390 /** |
|
391 * Externalizes the trigger object's details and attributes |
|
392 * to stream. |
|
393 * |
|
394 * The presence of this function means that the standard template |
|
395 * operator<<() ( defined in s32strm.h ) is available to externalize objects |
|
396 * of this class. |
|
397 * |
|
398 * @param[in] aStream Stream to which the object should be externalized. |
|
399 */ |
|
400 IMPORT_C void ExternalizeL( RWriteStream& aStream ) const; |
|
401 |
|
402 protected: |
|
403 /** |
|
404 * Internalize method that subclass must implement. |
|
405 * @param[in] aStream Stream from which the object should be internalized. |
|
406 */ |
|
407 virtual void DoInternalizeL( RReadStream& aStream ) = 0; |
|
408 |
|
409 /** |
|
410 * Externalize method that subclass must implement. |
|
411 * @param[in] aStream Stream to which the object should be externalized. |
|
412 */ |
|
413 virtual void DoExternalizeL( RWriteStream& aStream ) const = 0; |
|
414 |
|
415 /** |
|
416 * Constructor. |
|
417 */ |
|
418 CLbtTriggerEntry(); |
|
419 |
|
420 private: |
|
421 /** |
|
422 * By default, prohibit copy constructor |
|
423 */ |
|
424 CLbtTriggerEntry( const CLbtTriggerEntry& ); |
|
425 |
|
426 /** |
|
427 * Prohibit assigment operator |
|
428 */ |
|
429 CLbtTriggerEntry& operator= ( const CLbtTriggerEntry& ); |
|
430 |
|
431 private: //data |
|
432 /** |
|
433 * Id |
|
434 */ |
|
435 TLbtTriggerId iId; |
|
436 |
|
437 /** |
|
438 * Name |
|
439 */ |
|
440 HBufC* iName; |
|
441 |
|
442 /** |
|
443 * State |
|
444 */ |
|
445 TLbtTriggerState iState; |
|
446 |
|
447 /** |
|
448 * Rearm time |
|
449 */ |
|
450 TInt iRearmTime; |
|
451 |
|
452 /** |
|
453 * Requestors |
|
454 */ |
|
455 RRequestorStack iRequestor; |
|
456 |
|
457 /** |
|
458 * manager UI |
|
459 */ |
|
460 TUid iManagerUi; |
|
461 |
|
462 /** |
|
463 * Trigger condition |
|
464 */ |
|
465 CLbtTriggerConditionBase* iTriggerCondition; |
|
466 |
|
467 /** |
|
468 * Reserved for schedule information |
|
469 */ |
|
470 TAny* iSchedule; |
|
471 |
|
472 /** |
|
473 * Reserved pointer for future extension |
|
474 */ |
|
475 TAny* iReserved; |
|
476 }; |
|
477 |
|
478 |
|
479 #endif // LBTTRIGGERENTRY_H |