| class RLbt : public RSubSessionBase |
A handle to Location Triggering Server subsession. This class provides methods to use location triggering service from Location Triggering Server.
RLbt is used to create subsession with Location Triggering Server for the purpose of using the location triggering service. This class provides mechanisms for creating, listing, modifying and deleting trigger entries in Location Triggering Server. Besides, there are also methods to get trigger change and system settings change events, and session trigger firing event. It also provides method for getting location triggering related system settings.
Before using any of these services, a connection to Location Triggering Server must first be made.
A client can have multiple sessions connected to the Location Triggering Server. There can be multiple subsessions opened from one session. Triggers created from one subsession can be accessed from other subsessions within the same process. Trigger change event, trigger firing event and triggering system settings change event are send to all subsessions that have issued notification requests to Location Triggering Server.
Client must not issue a notification request while there is a same request still outstanding. An attempt to do so will generate a panic with code ELbtDuplicateRequest in category "LocTriggering". This applies to the following functions.
NotifyTriggerChangeEvent
NotifyTriggerFired
NotifyTriggeringSystemSettingChange
Client may get error code KErrInUse if it tries to read, write or delete a trigger while the previous write or delete operation is not completed yet.
RLbtServerlbt.lib
| Private Member Functions | |
|---|---|
| void | ConstructL() |
| void | CreateGetTriggerIteratorL(CLbtListTriggerOptions *, TRequestStatus &) |
| void | CreateTriggerL(const CLbtTriggerEntry &, TLbtTriggerId &, TBool, TRequestStatus &) |
| void | DeleteTriggersL(CLbtTriggerFilterBase *, TRequestStatus &) |
| void | DeleteTriggersL(const RArray< TLbtTriggerId > &, TRequestStatus &) |
| void | GetTriggersInServerL(CBufFlat *, CLbtListTriggerOptions *, TInt &) |
| void | GetTriggersL(RPointerArray< CLbtTriggerInfo > &, CLbtListTriggerOptions *, TRequestStatus &) |
| void | ListTriggerIdsL(RArray< TLbtTriggerId > &, CLbtListTriggerOptions *, TRequestStatus &) |
| void | SetTriggersStateL(CLbtTriggerEntry::TLbtTriggerState, CLbtTriggerFilterBase *, TLbtFireOnUpdate, TRequestStatus &) |
| void | UpdateTriggerL(const CLbtTriggerEntry &, TLbtTriggerAttributeFieldsMask, TLbtFireOnUpdate, TRequestStatus &) |
| void | ValidateGeoAreaInformationL(CLbtGeoAreaBase *) |
| IMPORT_C void | CancelAll | ( | ) |
Cancels all asynchronous operation that has been issued from this subsession.
| IMPORT_C void | CancelCreateTriggerIterator | ( | ) |
Cancel create trigger iterator operation.
This function does not require any capabilities.
| IMPORT_C void | CancelNotifyTriggerChangeEvent | ( | ) |
Cancels listening for trigger change event.
This function does not require any capabilities.
| IMPORT_C void | CancelNotifyTriggerFired | ( | ) |
Cancels listening for the trigger fired event.
This function does not require any capabilities.
| IMPORT_C void | CancelNotifyTriggeringSystemSettingChange | ( | ) |
Cancels listening for triggering system setting change event.
| IMPORT_C void | CancelSetTriggersState | ( | ) |
Cancel set trigger state operation.
This function does not require any capabilities.
| IMPORT_C void | Close | ( | ) |
Closes the subsession with Location Triggering Server.
Close() must be called when RLbt subsession is no longer required.
Before a subsession is closed, the client application must ensure that all outstanding notification requests have been cancelled. In particular, the application must issue all the appropriate Cancel requests and then wait for a confirmation that the notification has been terminated. A failure to do so results in a panic.
When the subsession is closed, all the session triggers owned by the client application are deleted by Location Triggering Server. Start-up triggers are not affected by this method.
| IMPORT_C void | CreateGetTriggerIterator | ( | TRequestStatus & | aStatus, |
| CLbtListTriggerOptions * | aListOptions = NULL | |||
| ) | ||||
Creates an iterator asynchronously in Location Triggering Server to retrieve trigger objects incrementally.
An iterator must be created before GetNextTriggerLC() can be called. The iterator is constructed in the server side and it is subsession specific. Calling this function again will reset the iterator. After the iterator is constructed, the client application calls GetNextTriggerLC() repeatedly to retrieve all interested trigger objects. Note, client applications can only get triggers owned by itself.
If any trigger is changed during iteration, the client application shall call this method again to reset the iterator and get the triggers again incrementally.
This method requires Location capability.
| TRequestStatus & aStatus | Contains the error code when the request is completed. KErrNotSupported is returned if there is an area filter used and the area is not a type of geographical circular or rectangular area. |
| CLbtListTriggerOptions * aListOptions = NULL | Specifies the options used for listing triggers. Default value is NULL, which will retrieve all triggers owned by the client application. |
| IMPORT_C void | CreateGetTriggerIteratorL | ( | CLbtListTriggerOptions * | aListOptions = NULL | ) |
Creates an iterator in Location Triggering Server to retrieve trigger objects incrementally.
An iterator must be created before GetNextTriggerLC() can be called. The iterator is constructed in the server side and it is subsession specific. Calling this function again will reset the iterator. After the iterator is constructed, the client application calls GetNextTriggerLC() repeatedly to retrieve all interested trigger objects. Note, client applications can only get triggers owned by itself.
If any trigger is changed during iteration, the client application shall call this method again to reset the iterator and get the triggers again incrementally.
This method requires Location capability.
| CLbtListTriggerOptions * aListOptions = NULL | Specifies the options used for listing triggers. Default value is NULL, which will retrieve all triggers owned by the client application. |
| void | CreateGetTriggerIteratorL | ( | CLbtListTriggerOptions * | aListOptions, |
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for create trigger iterator operation.
| CLbtListTriggerOptions * aListOptions | |
| TRequestStatus & aStatus |
| IMPORT_C void | CreateTrigger | ( | const CLbtTriggerEntry & | aTrigger, |
| TLbtTriggerId & | aTriggerId, | |||
| TBool | aFireOnCreation, | |||
| TRequestStatus & | aStatus | |||
| ) | ||||
Creates a trigger in Location Triggering Server and returns the trigger Id.
Client application may use this method to create a trigger in Location Triggering Server. When a trigger is created, the process of the client application becomes the owner process of the trigger.
Trigger entry shall be a subclass of CLbtTriggerEntry.
Start-up triggers are stored persistently. They can be deleted by method RLbt::DeleteTriggerL(). Session triggers remain until DeleteTriggerL() is called or the client's subsession is closed.
Name
Requestors
Trigger condition
Process Identity
Although manager UI is not a mandatory attribute, it's highly recommended that correct manager UI is specified.
Trigger area
Direction
Currently, only CLbtGeoCircle can be used as trigger area. The center of the geographical circle must be specified.
If the radius of the trigger area is not specified, minimum size of trigger area will be used in the created trigger entry.
The trigger ID attribute is ignored while creating a trigger. If the trigger is successfully created, trigger ID is returned to the client application. If the trigger is enabled, Location Triggering Server will supervise the trigger and fires it when trigger conditions are met.
Creating any type triggers requires Location capability. WriteUserData capability is required in addition to create start-up triggers.
| const CLbtTriggerEntry & aTrigger | The trigger to be created. Trigger Id attribute is ignored by Location Triggering Server. |
| TLbtTriggerId & aTriggerId | Contains trigger ID of the created trigger When the request is completed. Trigger is is unique among all triggers currently exist in the system. If a trigger is removed from the system, its Id may be reused by another trigger. |
| TBool aFireOnCreation | The parameter specifies if the trigger can be fired right after the creation.If this parameter is ETrue. For entry type of trigger, if the trigger is created inside the trigger area, it is fired right after it is created. For exit type of trigger, if the trigger is created outside of the trigger area, it is fired right after it is created.If this parameter is EFalse. For entry type of trigger, if the trigger is created inside the trigger area, it will not be fired immediately. The trigger will be fired when the terminal moves outside of the trigger area and then enters the trigger area again. For exit type of trigger, if the trigger is created outside of trigger area it will be fired immediately. The trigger will be fired when the terminal moves into the trigger area and then moves out again. |
| TRequestStatus & aStatus | Contains the error code when the request is completed.KErrNone. If the trigger is created successfully.KErrArgument. If any of mandatory attributes are not specified, the manager UI is specified but it is not a valid UI application, or the length of the trigger name is zero or larger than KLbtMaxNameLength.KErrNotSupported. If the trigger condition is not an instance of CLbtTriggerConditionBasic, or if the trigger area is not an instance of CLbtGeoCircle. Also returned if the trigger direction is EFireOnExit and the trigger being created is a cell based trigger.KErrAccessDenied. If the requestor attributes are missing, privacy checking by Location Server determines that any of the specified requestors do not have permission to retrieve location information,KErrPermisionDenied. If the client application does not have enough capabilities to create this trigger.KErrTriggeringAreaTooSmall. If the specified trigger area is smaller than minimum size of trigger area.KErrLbtMaxTriggerLimitExceeded. If creating startup trigger exceeds the system defined limit.KErrDiskFull. Disk full when creating a start-up trigger.Other standard Symbian error code, such as KErrNoMemory, KErrServerBusy, KErrGeneral. If the operation fails. |
| void | CreateTriggerL | ( | const CLbtTriggerEntry & | aTrigger, |
| TLbtTriggerId & | aTriggerId, | |||
| TBool | aFireOnCreation, | |||
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for create trigger operation.
| const CLbtTriggerEntry & aTrigger | |
| TLbtTriggerId & aTriggerId | |
| TBool aFireOnCreation | |
| TRequestStatus & aStatus |
| IMPORT_C void | DeleteTriggerL | ( | TLbtTriggerId | aId | ) |
Deletes a specific trigger from Location Triggering Server.
Client applications can only delete triggers owned by it.
Deleting any type triggers requires Location capability. WriteUserData capability is required in addition to delete start-up triggers.
| TLbtTriggerId aId | The ID of the trigger to be deleted. |
| IMPORT_C void | DeleteTriggers | ( | TRequestStatus & | aStatus, |
| CLbtTriggerFilterBase * | aFilter = NULL | |||
| ) | ||||
Delete triggers asynchronously. Triggers to be deleted must be owned by the client application and fulfill the specified criteria.
If no trigger that belong to the client application fulfills the specified criteria, the method completes the client request with KErrNotFound.
If only a part of the triggers that fullfill the criteria belong to the client application, then only those triggers belonging to that client application would be deleted and the method would complete without any error.
If no filter is specified, all triggers owned by the client application are deleted.
Deleting any type triggers requires Location capability. WriteUserData capability is required in addition to delete start-up triggers.
| TRequestStatus & aStatus | Contains the error code when the request is completed.KErrNone If the operation was successful.KErrNotFound If no trigger belonging to the client application fullfills the criteria specified.Other standard Symbian error code, such as KErrNoMemory, KErrServerBusy, KErrGeneral, etc. |
| CLbtTriggerFilterBase * aFilter = NULL | Specify the filter for the delete operation. Trigger entries that fulfill the criteria will be deleted from Location Triggering Server. Default value is NULL in which case all triggers owned by the client applications will be deleted. |
| IMPORT_C void | DeleteTriggers | ( | const RArray< TLbtTriggerId > & | aTriggerIdList, |
| TRequestStatus & | aStatus | |||
| ) | ||||
Delete triggers asynchronously based on a list of trigger Ids. The triggers to be deleted must be owned by the client application.
If none of the triggers to be deleted are owned by the client application then no triggers would be deleted and this method will complete the request with KErrNotFound.
If the list is empty, no trigger will be deleted and this method completes without any error code.
In the case where a list of trigger IDs are mentioned of which only a few of those belong to the client, then only all those triggers that belong to the client will be deleted and the rest ignored. The method will complete without any leave in this case.
Deleting any type of triggers requires Location capability. WriteUserData capability is required in addition to delete start-up triggers.
| const RArray< TLbtTriggerId > & aTriggerIdList | The list contains IDs of the triggers that are to be deleted. |
| TRequestStatus & aStatus | Contains the error code when the request is completed.KErrNone If the operation was succeed.Other standard Symbian error code, such as KErrNoMemory, KErrServerBusy, KErrGeneral, etc. |
| IMPORT_C void | DeleteTriggersL | ( | CLbtTriggerFilterBase * | aFilter = NULL | ) |
Delete triggers that are owned by the client application and fulfill the specified criteria.
If none of the triggers that belong to the client application fulfill the specified criteria, the method leaves with KErrNotFound.
If only a part of the triggers that fullfill the criteria belong to the client application, then only those triggers belonging to that client application would be deleted and the method would complete without any leave.
If no filter is specified, all triggers owned by the client application are deleted.
Deleting any type triggers requires Location capability. WriteUserData capability is required in addition to delete start-up triggers.
| CLbtTriggerFilterBase * aFilter = NULL | Specify the filter for the delete operation. Trigger entries that fulfill the criteria will be deleted from Location Triggering Server. By default, no filter is used. In this case, all triggers owned by the client applications will be deleted. |
| IMPORT_C void | DeleteTriggersL | ( | const RArray< TLbtTriggerId > & | aTriggerIdList | ) |
Delete triggers based on a list of trigger Ids. The triggers to be deleted must be owned by the client application.
If none of the triggers to be deleted are owned by the client application then no triggers would be deleted and this method will leave with KErrNotFound.
If the list is empty, no trigger will be deleted and this method completes without any leave.
In the case where a list of trigger IDs are mentioned of which only a few of those belong to the client, then only all those triggers that belong to the client will be deleted and the rest ignored. The method will complete without any leave in this case.
Deleting any type of triggers requires Location capability. WriteUserData capability is required in addition to delete start-up triggers.
| const RArray< TLbtTriggerId > & aTriggerIdList | The list contains IDs of the triggers that are to be deleted. |
| void | DeleteTriggersL | ( | CLbtTriggerFilterBase * | aFilter, |
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for delete triggers operation.
| CLbtTriggerFilterBase * aFilter | |
| TRequestStatus & aStatus |
| void | DeleteTriggersL | ( | const RArray< TLbtTriggerId > & | aTriggerIdList, |
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for delete triggers operation.
| const RArray< TLbtTriggerId > & aTriggerIdList | |
| TRequestStatus & aStatus |
| IMPORT_C void | GetFiredTriggersL | ( | RArray< TLbtTriggerFireInfo > & | aTriggerInfoList | ) |
Gets fired trigger's information.
This method is used by the client application to get information of all the fired triggers( session triggers and start-up triggers). If the same trigger is fired more than once before the client application retrieves the firing information, only the most recent fired information is returned. If no trigger has been fired, an empty list is returned.
This method requires Location capability.
| RArray< TLbtTriggerFireInfo > & aTriggerInfoList | On return contains fired triggers' information. |
| IMPORT_C CLbtTriggerInfo * | GetNextTriggerLC | ( | ) |
Gets trigger objects incrementally.
This method is used together with CreateGetTriggerIteratorL() to incrementally retrieve trigger objects owned by the client application. If the iterator is not created when this function is called, client application gets a panic with code ELbtIteratorNotCreated.
This method returns NULL when all triggers are retrieved. Client application shall call CreateGetTriggerIteratorL() again to reset the iterator.
Client application takes ownership of the returned trigger object. The returned trigger object is left in cleanup stack when the trigger object is successfully retrieved.
This method requires Location capability.
| IMPORT_C CLbtTriggerInfo * | GetTriggerLC | ( | TLbtTriggerId | aId, |
| TLbtTriggerAttributeFieldsMask | aEntryFieldMask = KLbtTriggerAttributeFieldsAll , | |||
| TLbtTriggerDynamicInfoFieldsMask | aDynInfoFieldMask = KLbtTriggerDynInfoFieldsAll | |||
| ) | ||||
Gets the specified trigger from Location Triggering Server.
Client application takes the ownership ofthe returned trigger object. The returned trigger object is left in cleanup stack when the trigger entry is successfully retrieved.
Each trigger entry object consumes about 100 - 200 bytes user heap, if all attributes are filled. To save memory usage, client applications can retrieve trigger object with only partial attributes filled.
This method requires Location capability.
| TLbtTriggerId aId | The ID of the trigger to be retrieved. |
| TLbtTriggerAttributeFieldsMask aEntryFieldMask = KLbtTriggerAttributeFieldsAll | The trigger entry's attribute field mask. It specifies what attributes shall be filled in the returned trigger object. The default value is KLbtTriggerAttributeFieldsAll, which means all attributes field will be filled. Wether the trigger ID attribute is specified or not in this mask, the returned trigger object always contains a valid trigger Id. |
| TLbtTriggerDynamicInfoFieldsMask aDynInfoFieldMask = KLbtTriggerDynInfoFieldsAll | Specifies which dynamic information field shall be filled in the returned object. The default value is KLbtTriggerDynInfoFieldsAll, which means all dynamic information fields will be filled. |
| IMPORT_C void | GetTriggeringSystemSettingsL | ( | TLbtTriggeringSystemSettings & | aSetting | ) |
Gets triggering system setting.
This method is used by the client application to get triggering system settings. Client applications can use NotifyTriggeringSystemSettingChange() get the change event of the triggering system settings.
This function requires ReadUserData capability.
| TLbtTriggeringSystemSettings & aSetting | On return contains triggering system settings. |
| IMPORT_C void | GetTriggers | ( | TRequestStatus & | aStatus, |
| RPointerArray< CLbtTriggerInfo > & | aTriggerList, | |||
| CLbtListTriggerOptions * | aListOptions = NULL | |||
| ) | ||||
Gets triggers asynchronously from Location Triggering Server. A client application can only retrieve triggers owned by it.
Client applications can specify options used in retrieving triggers. Ownership of the returned trigger objects is transferred to the client application.
Note: This function may require large free heap memory from the client application depending on the number of triggers to be retrieved and the attributes to be filled.
This method requires Location capability.
| TRequestStatus & aStatus | Contains the error code when the request is completed.KErrNotSupported. If there is an area filter used and the area is not a type of geographical circular or rectangular area.Other standard Symbian error code, such as KErrNoMemory, KErrServerBusy, KErrGeneral, etc. |
| RPointerArray< CLbtTriggerInfo > & aTriggerList | On return, contains trigger objects retrieved from Location Triggering Server. The content of aTriggerList is cleared even if this function fails. The ownership of the returned pointers is transfered to the client application. |
| CLbtListTriggerOptions * aListOptions = NULL | Specifies the options for listing triggers. By default, the value is NULL. In this case all triggers owned by the client application will be retrieved. |
| void | GetTriggersInServerL | ( | CBufFlat * | aBuf, |
| CLbtListTriggerOptions * | aListOptions, | |||
| TInt & | aBufLength | |||
| ) | [private] | |||
Helper method for get triggers operation.
| CBufFlat * aBuf | |
| CLbtListTriggerOptions * aListOptions | |
| TInt & aBufLength |
| IMPORT_C void | GetTriggersL | ( | RPointerArray< CLbtTriggerInfo > & | aTriggerList, |
| CLbtListTriggerOptions * | aListOptions = NULL | |||
| ) | ||||
Gets triggers from Location Triggering Server. A client application can only retrieve triggers owned by it.
Client applications can specify options used in retrieving triggers. Ownership of the returned trigger objects is transferred to the client application.
Note: This function may require large free heap memory from the client application depending on the number of triggers to be retrieved and the attributes to be filled.
This method requires Location capability.
| RPointerArray< CLbtTriggerInfo > & aTriggerList | On return, contains trigger objects retrieved from Location Triggering Server. The content of aTriggerList is cleared even if this function fails. The ownership of the returned pointers is transfered to the client application. |
| CLbtListTriggerOptions * aListOptions = NULL | Specifies the options for listing triggers. By default, the value is NULL. In this case all triggers owned by the client application will be retrieved. |
| void | GetTriggersL | ( | RPointerArray< CLbtTriggerInfo > & | aTriggerList, |
| CLbtListTriggerOptions * | aListOptions, | |||
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for get triggers operation.
| RPointerArray< CLbtTriggerInfo > & aTriggerList | |
| CLbtListTriggerOptions * aListOptions | |
| TRequestStatus & aStatus |
| IMPORT_C void | ListTriggerIds | ( | TRequestStatus & | aStatus, |
| RArray< TLbtTriggerId > & | aTriggerIdList, | |||
| CLbtListTriggerOptions * | aListOptions = NULL | |||
| ) | ||||
Lists asynchronously IDs of triggers that are owned by the client application.
Client applications can specify options used in retrieving trigger IDs.
This method requires Location capability.
| TRequestStatus & aStatus | Contains the error code when the request is completed. KErrNotSupported is returned if there is an area filter used and the area is not a type of geographical circular or rectangular area.KErrNotSupported If there is an area filter used and the area is not a type of geographical circular or rectangular area.Other standard Symbian error code, such as KErrNoMemory, KErrServerBusy, KErrGeneral, etc. |
| RArray< TLbtTriggerId > & aTriggerIdList | On return, aTriggerIdList contains IDs of retrieved triggers. The content of aTriggerIdList will be cleared even if this function fails. |
| CLbtListTriggerOptions * aListOptions = NULL | Specified the options used for listing triggers. Default value is NULL in which case all triggers owned by the client application will be retrieved. |
| IMPORT_C void | ListTriggerIdsL | ( | RArray< TLbtTriggerId > & | aTriggerIdList, |
| CLbtListTriggerOptions * | aListOptions = NULL | |||
| ) | ||||
Lists IDs of triggers that are owned by the client application.
Client applications can specify options used in retrieving trigger IDs.
This method requires Location capability.
| RArray< TLbtTriggerId > & aTriggerIdList | On return, aTriggerIdList contains IDs of retrieved triggers. The content of aTriggerIdList will be cleared even if this function fails. |
| CLbtListTriggerOptions * aListOptions = NULL | Specified the options used for listing triggers. By default, the value is NULL. In this case, all triggers owned by the client application will be retrieved. |
| void | ListTriggerIdsL | ( | RArray< TLbtTriggerId > & | aTriggerIdList, |
| CLbtListTriggerOptions * | aListOptions, | |||
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for list trigger ids operation.
| RArray< TLbtTriggerId > & aTriggerIdList | |
| CLbtListTriggerOptions * aListOptions | |
| TRequestStatus & aStatus |
| IMPORT_C void | NotifyTriggerChangeEvent | ( | TLbtTriggerChangeEvent & | aEvent, |
| TRequestStatus & | aStatus | |||
| ) | ||||
Listens for change events of the triggers owned by the client application.
This method is used by the client application to get change events when one or many of its triggers are changed.
Triggers can be deleted and modified not only by the owner process and trigger handling process, but also by other system application, e.g. system management UI application.
This function is asynchronous and it will complete the request status when an event occurs. Client applications can get detailed information of the change from the retrieved event object. Client application shall call this function again to get further change event.
Event listening can be cancelled by calling CancelNotifyTriggerChangeEvent().
This method requires Location capability.
| TLbtTriggerChangeEvent & aEvent | Will contain the event information when an event occurs. |
| TRequestStatus & aStatus | Will be completed with KErrNone if an event occurs and an error code(for example, KErrServerBusy, etc.) if some error was encountered. |
| IMPORT_C void | NotifyTriggerFired | ( | TLbtTriggerFireInfo & | aFireInfo, |
| TRequestStatus & | aStatus | |||
| ) | ||||
Listens for the event if any trigger is fired.
Client applications can use this method to get notified when a trigger (session triggers and start-up triggers) is fired. The firing information is returned to the client application. If more that one trigger is fired, Location Triggers Server will complete the request and the first fired trigger is returned. Client application shall call this method again to get next trigger firing event.
When a start-up trigger is fired, Location Triggering Server will first launch the specified trigger handling process, and then notify the client application about the firing event.
triggers that are created by itself(Client application is the owner process of the trigger).
triggers that trigger handling process SID is set and matches SID of the client application's process(Client application is the triggering handling process of the trigger, and it can access the trigger).
The request is canceled by CancelNotifyTriggerFired()
This method requires Location capability.
| TLbtTriggerFireInfo & aFireInfo | On return contains the fired trigger's firing information. |
| TRequestStatus & aStatus | Will be completed with KErrNone if an event occurs, and an error code( for example KErrServerBusy, etc.) if some error encountered. |
| IMPORT_C void | NotifyTriggeringSystemSettingChange | ( | TLbtTriggeringSystemSettings & | aSettings, |
| TRequestStatus & | aStatus | |||
| ) | ||||
Listens for the change event of triggering system settings.
This function is asynchronous and it will complete the request status when triggering system settings are changed. Client applications can get detailed information of triggering system setting from method GetTriggeringSystemSettingL(). Client application shall call this function again to get further change event.
Event listening can be cancelled by calling CancelNotifyTriggeringSystemSettingChange().
This function requires ReadUserData capability.
| TLbtTriggeringSystemSettings & aSettings | On return contains the new triggering system settings. |
| TRequestStatus & aStatus | Will be completed with KErrNone if an event occurs and an error code( for example, KErrServerBusy, etc.) if some error was encountered. aStatus will be completed with KErrPermissionDenied if the client application does not have enough capability. |
| IMPORT_C TInt | Open | ( | RLbtServer & | aServer | ) |
Opens a subsession with Location Triggering Server.
A subsession must be opened before any other service can be used.
| RLbtServer & aServer | Reference to the Location Triggering Server session. |
| IMPORT_C TInt | Open | ( | ) |
Connect and open a subsession with Location Triggering Server.
Note, this function will connect and create a session to Location Triggering Server. Client application shall avoid unnecesary session connection to Location Triggering Server. Whenever possible, client applicaiton shall reuse same session to open a subsession.
| IMPORT_C void | SetTriggerStateL | ( | TLbtTriggerId | aId, |
| CLbtTriggerEntry::TLbtTriggerState | aState, | |||
| TLbtFireOnUpdate | aFireOnUpdate | |||
| ) | ||||
Sets the state of the specified trigger. Client application can change the state of only triggers owned by it.
To enable the trigger, set the trigger state to ELbtTriggerEnabled. To disable the trigger, set the trigger state to ELbtTriggerDisabled.
Changing state of any type triggers requires Location capability. WriteUserData capability is required in addition to change state of start-up triggers.
| TLbtTriggerId aId | The ID of the trigger whose state will be updated. |
| CLbtTriggerEntry::TLbtTriggerState aState | New state of the specified trigger. |
| TLbtFireOnUpdate aFireOnUpdate | The parameter specifies if the trigger can be fired right after the update operation.If this parameter is ETrue. For entry type of trigger, if the trigger is updated inside the trigger area, it is fired right after it is updated. For exit type of trigger, if the trigger is updated outside of the trigger area, it is fired right after it is updated.If this parameter is EFalse. For entry type of trigger, if the trigger is updated inside the trigger area, it will not be fired immediately. The trigger will be fired when the terminal moves outside of the trigger area and then enters the trigger area again. For exit type of trigger, if the trigger is updated outside of trigger area it will be fired immediately. The trigger will be fired when the terminal moves into the trigger area and then moves out again. |
| IMPORT_C void | SetTriggersState | ( | TRequestStatus & | aStatus, |
| CLbtTriggerEntry::TLbtTriggerState | aState, | |||
| TLbtFireOnUpdate | aFireOnUpdate, | |||
| CLbtTriggerFilterBase * | aFilter = NULL | |||
| ) | ||||
Sets state of multiple triggers asynchronously.
If a filter is specified, all triggers owned by the client application that fulfill the criteria will be affected.
If no filter is specified, all triggers owned by the client application will be affected.
If no trigger that are owned by the client application fulfills the specified criteria, no trigger will be modified and this completes with KErrNotFound.
Changing state of any type triggers requires Location capability. WriteUserData capability is required in addition to change state of start-up triggers.
| TRequestStatus & aStatus | Contains the error code when the request is completed.KErrNotSupported If there is an area filter used and the area is not a type of geographical circular or rectangular area.Other standard Symbian error code, such as KErrNoMemory, KErrServerBusy, KErrGeneral, etc. |
| CLbtTriggerEntry::TLbtTriggerState aState | New state of the triggers. |
| TLbtFireOnUpdate aFireOnUpdate | The parameter specifies if the trigger can be fired right after the update operation.If this parameter is ETrue. For entry type of trigger, if the trigger is updated inside the trigger area, it is fired right after it is updated. For exit type of trigger, if the trigger is updated outside of the trigger area, it is fired right after it is updated.If this parameter is EFalse. For entry type of trigger, if the trigger is updated inside the trigger area, it will not be fired immediately. The trigger will be fired when the terminal moves outside of the trigger area and then enters the trigger area again. For exit type of trigger, if the trigger is updated outside of trigger area it will be fired immediately. The trigger will be fired when the terminal moves into the trigger area and then moves out again. |
| CLbtTriggerFilterBase * aFilter = NULL | The filter to be used. Triggers that fulfill the criteria of the specified filter will be affected. Default is value is NULL in which case all triggers owned by the client application will be updated. |
| IMPORT_C void | SetTriggersStateL | ( | CLbtTriggerEntry::TLbtTriggerState | aState, |
| TLbtFireOnUpdate | aFireOnUpdate, | |||
| CLbtTriggerFilterBase * | aFilter = NULL | |||
| ) | ||||
Sets state of multiple triggers. Client application can change state of only triggers owned by it.
If a filter is specified, all triggers that fulfill the criteria and owned by the requesting client application will be affected.
If no filter is specified, all triggers owned by the client application will be affected.
If no trigger owned by the client application fulfills the specified criteria, no trigger will be modified and the method leaves with KErrNotFound.
Changing state of any type triggers requires Location capability. WriteUserData capability is required in addition to change state of start-up triggers.
| CLbtTriggerEntry::TLbtTriggerState aState | New state of the triggers. |
| TLbtFireOnUpdate aFireOnUpdate | The parameter specifies if the trigger can be fired right after the update operation.If this parameter is ETrue. For entry type of trigger, if the trigger is updated inside the trigger area, it is fired right after it is updated. For exit type of trigger, if the trigger is updated outside of the trigger area, it is fired right after it is updated.If this parameter is EFalse. For entry type of trigger, if the trigger is updated inside the trigger area, it will not be fired immediately. The trigger will be fired when the terminal moves outside of the trigger area and then enters the trigger area again. For exit type of trigger, if the trigger is updated outside of trigger area it will be fired immediately. The trigger will be fired when the terminal moves into the trigger area and then moves out again. |
| CLbtTriggerFilterBase * aFilter = NULL | The filter to be used. Triggers that fulfill the criteria of the specified filter will be affected. Default value is NULL in which case all triggers owned by the client application will be updated. |
| void | SetTriggersStateL | ( | CLbtTriggerEntry::TLbtTriggerState | aState, |
| CLbtTriggerFilterBase * | aFilter, | |||
| TLbtFireOnUpdate | aFireOnUpdate, | |||
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for set triggers state operation.
| CLbtTriggerEntry::TLbtTriggerState aState | |
| CLbtTriggerFilterBase * aFilter | |
| TLbtFireOnUpdate aFireOnUpdate | |
| TRequestStatus & aStatus |
| IMPORT_C void | UpdateTrigger | ( | const CLbtTriggerEntry & | aTrigger, |
| TLbtTriggerAttributeFieldsMask | aFieldMask, | |||
| TLbtFireOnUpdate | aFireOnUpdate, | |||
| TRequestStatus & | aStatus | |||
| ) | ||||
Changes the attributes of the specified trigger asynchronously
Client applications can use this method to change attributes of a specified trigger that is owned by it. Client applications can only update triggers owned by itself.
Some attributes are not modifiable after the trigger is created. Trying to change the following attributes will generate a leave with error code KErrAccessDenied.
ID
Requestor
Manager UI
Trigger handling process identity
Trigger handling process SID
If the specified trigger does not belong to the client application the method leaves with KErrNotFound.
Updating any type triggers requires Location capability. WriteUserData capability is required in addition to update start-up triggers.
| const CLbtTriggerEntry & aTrigger | The trigger object to be updated in Location Triggering Server. The trigger ID identifies the trigger to be updated. |
| TLbtTriggerAttributeFieldsMask aFieldMask | Specifies the attribute fields that are valid in the aTrigger and shall be updated to the trigger. Trigger ID field in aTrigger is always used regardless whether the trigger ID field is marked or not in the mask. The attribute value in aTrigger is ignored if the attribute field in aFieldMask is not marked. |
| TLbtFireOnUpdate aFireOnUpdate | The parameter specifies if the trigger can be fired right after the update operation.If this parameter is ETrue. For entry type of trigger, if the trigger is updated inside the trigger area, it is fired right after it is updated. For exit type of trigger, if the trigger is updated outside of the trigger area, it is fired right after it is updated.If this parameter is EFalse. For entry type of trigger, if the trigger is updated inside the trigger area, it will not be fired immediately. The trigger will be fired when the terminal moves outside of the trigger area and then enters the trigger area again. For exit type of trigger, if the trigger is updated outside of trigger area it will be fired immediately. The trigger will be fired when the terminal moves into the trigger area and then moves out again. |
| TRequestStatus & aStatus |
| IMPORT_C void | UpdateTriggerL | ( | const CLbtTriggerEntry & | aTrigger, |
| TLbtTriggerAttributeFieldsMask | aFieldMask, | |||
| TLbtFireOnUpdate | aFireOnUpdate | |||
| ) | ||||
Changes the attributes of the specified trigger.
Client applications can use this method to change attributes of a specified trigger that is owned by it. Client applications can only update triggers owned by itself.
Some attributes are not modifiable after the trigger is created. Trying to change the following attributes will generate a leave with error code KErrAccessDenied.
ID
Requestor
Manager UI
Trigger handling process identity
Trigger handling process SID
If the specified trigger does not belong to the client application the method leaves with KErrNotFound.
Updating any type triggers requires Location capability. WriteUserData capability is required in addition to update start-up triggers.
| const CLbtTriggerEntry & aTrigger | The trigger object to be updated in Location Triggering Server. The trigger ID identifies the trigger to be updated. |
| TLbtTriggerAttributeFieldsMask aFieldMask | Specifies the attribute fields that are valid in the aTrigger and shall be updated to the trigger. Trigger ID field in aTrigger is always used regardless whether the trigger ID field is marked or not in the mask. The attribute value in aTrigger is ignored if the attribute field in aFieldMask is not marked. |
| TLbtFireOnUpdate aFireOnUpdate | The parameter specifies if the trigger can be fired right after the update operation.If this parameter is ETrue. For entry type of trigger, if the trigger is updated inside the trigger area, it is fired right after it is updated. For exit type of trigger, if the trigger is updated outside of the trigger area, it is fired right after it is updated.If this parameter is EFalse. For entry type of trigger, if the trigger is updated inside the trigger area, it will not be fired immediately. The trigger will be fired when the terminal moves outside of the trigger area and then enters the trigger area again. For exit type of trigger, if the trigger is updated outside of trigger area it will be fired immediately. The trigger will be fired when the terminal moves into the trigger area and then moves out again. |
| void | UpdateTriggerL | ( | const CLbtTriggerEntry & | aTrigger, |
| TLbtTriggerAttributeFieldsMask | aFieldMask, | |||
| TLbtFireOnUpdate | aFireOnUpdate, | |||
| TRequestStatus & | aStatus | |||
| ) | [private] | |||
Helper method for update trigger operation.
| const CLbtTriggerEntry & aTrigger | |
| TLbtTriggerAttributeFieldsMask aFieldMask | |
| TLbtFireOnUpdate aFireOnUpdate | |
| TRequestStatus & aStatus |
| void | ValidateGeoAreaInformationL | ( | CLbtGeoAreaBase * | aGeoArea | ) | [private] |
Validates geo area information based on type e.g. Coordinate, Cell, WLan, Hybrid.
| CLbtGeoAreaBase * aGeoArea | the geographical area |
| CLbtClientRequester * | iClientRequester | [private] |
Pointer to client requestor. Own.
| CLbtSubSessnPtrHolder * | iPtrHolder | [private] |
Subsession pointer holder Own.
| CLbtTriggerEntry::TLbtTriggerState | iState | [private] |
Trigger entry state.
| TLbtTriggerCreationInfo * | iTriggerCreationInfo | [private] |
Pointer to TLbtTriggerCreationInfo object. Own.
| RPointerArray< CLbtTriggerInfo > | iTriggerList | [private] |
CLbtTriggerInfo pointer array.
| TLbtTriggerStateInfo * | iTriggerStateInfo | [private] |
Pointer to TLbtTriggerStateInfo object. Own.
| TLbtTriggerUpdationInfo * | iTriggerUpdationInfo | [private] |
Pointer to TLbtTriggerCreationInfo object. Own.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.