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 "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 triggering server client interface

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef LBT_H

    21 #define LBT_H

    22 

    23 #include <e32std.h>

    24 #include <lbs.h>

    25 #include <lbtserver.h>

    26 #include <lbttriggerentry.h>

    27 #include <lbtcommon.h>

    28 #include <lbttriggerchangeevent.h>

    29 #include <lbttriggeringsystemsettings.h>

    30 #include <lbtlisttriggeroptions.h>

    31 

    32 

    33 class CLbtTriggerEntry;

    34 class CLbtTriggerFilterBase;

    35 class CLbtListTriggerOptions;

    36 class CLbtTriggerInfo;

    37 class CLbtClientRequester;

    38 class CLbtSubSessnPtrHolder;

    39 struct TLbtTriggerCreationInfo;

    40 struct TLbtTriggerUpdationInfo;

    41 struct TLbtTriggerStateInfo;

    42 

    43 

    44 /**

    45  * A handle to Location Triggering Server subsession. This class provides 

    46  * methods to use location triggering service from Location Triggering 

    47  * Server.

    48  * 

    49  * RLbt is used to create subsession with Location Triggering Server for the 

    50  * purpose of using the location triggering service. This class provides 

    51  * mechanisms for creating, listing, modifying and deleting trigger entries in 

    52  * Location Triggering Server. Besides, there are also methods to get 

    53  * trigger change and system settings change events, and session trigger 

    54  * firing event. It also provides method for getting

    55  * location triggering related system settings. 

    56  * 

    57  * Before using any of these services, a connection to Location Triggering

    58  * Server must first be made.

    59  *

    60  * A client can have multiple sessions connected to the Location Triggering 

    61  * Server. There can be multiple subsessions opened from one session. 

    62  * Triggers created from one subsession can be accessed from other 

    63  * subsessions within the same process. Trigger change event, trigger

    64  * firing event and triggering system settings change event are 

    65  * send to all subsessions that have issued notification

    66  * requests to Location Triggering Server.

    67  *

    68  * Client must not issue a notification request while there is 

    69  * a same request still outstanding. An attempt to do so will generate a

    70  * panic with code ELbtDuplicateRequest in category "LocTriggering". This applies 

    71  * to the following functions.

    72  * 

    73  * - NotifyTriggerChangeEvent

    74  * - NotifyTriggerFired

    75  * - NotifyTriggeringSystemSettingChange

    76  *

    77  * Client may get error code KErrInUse if it tries to read, write or delete a 

    78  * trigger while the previous write or delete operation is not completed yet. 

    79  *

    80  * @see RLbtServer

    81  * 

    82  * @lib lbt.lib

    83  *

    84  * @since S60 5.1

    85  */

    86 class RLbt : public RSubSessionBase

    87     {

    88     public:

    89        /**

    90         * Opens a subsession with Location Triggering Server.

    91         *

    92         * A subsession must be opened before any other service can be used.

    93         * 

    94         * @panic LocTriggering ELbtServerBadHandle If a session to Location 

    95         * Triggering Server has not been connected.

    96         *

    97         * @param[in] aServer Reference to the Location Triggering Server 

    98         * session.

    99         *

   100         * @return KErrNone if successful. Otherwise, Symbian standard 

   101         * error code is returned, such as KErrNoMemory, KErrServerBusy, etc.

   102         */

   103         IMPORT_C TInt Open( RLbtServer& aServer );

   104 

   105        /**

   106         * Connect and open a subsession with Location Triggering Server.

   107         *

   108         * Note, this function will connect and create a session to Location

   109         * Triggering Server. Client application shall avoid unnecesary

   110         * session connection to Location Triggering Server. Whenever

   111         * possible, client applicaiton shall reuse same session to

   112         * open a subsession. 

   113         *

   114         * @panic LocTriggering ELbtServerBadHandle If a session to Location 

   115         * Triggering Server has not been connected.

   116         *

   117         * @return KErrNone if successful. Otherwise, Symbian standard 

   118         * error code is returned, such as KErrNoMemory, KErrServerBusy, etc.

   119         */

   120         IMPORT_C TInt Open();

   121     

   122        /**

   123         * Closes the subsession with Location Triggering Server.

   124         *

   125         * Close() must be called when RLbt subsession is no longer required. 

   126         * 

   127         * Before a subsession is closed, the client application must ensure

   128         * that all outstanding notification requests have been cancelled. In

   129         * particular, the application must issue all the appropriate Cancel 

   130         * requests and then wait for a confirmation that the notification has 

   131         * been terminated. A failure to do so results in a panic.

   132         *

   133         * When the subsession is closed, all the session triggers owned by 

   134         * the client application are deleted by Location Triggering Server. 

   135         * Start-up triggers are not affected by this method. 

   136         * 

   137         * @panic LocTriggering ELbtRequestsNotCancelled If client application 

   138         * has requests outstanding with Location Triggering Server.

   139         */

   140         IMPORT_C void Close();

   141     

   142        /**

   143         * Creates a trigger in Location Triggering Server and returns the 

   144         * trigger Id.

   145         *

   146         * Client application may use this method to create a trigger in 

   147         * Location Triggering Server. When a trigger is created, the process 

   148         * of the client application becomes the owner process of the trigger.

   149         *

   150         * Trigger entry shall be a subclass of CLbtTriggerEntry.

   151         *

   152         * Start-up triggers are stored persistently. They can be deleted

   153         * by method RLbt::DeleteTriggerL(). Session triggers remain 

   154         * until DeleteTriggerL() is called or the client's subsession is 

   155         * closed. 

   156         *

   157         * While creating a trigger, the following attributes are mandatory 

   158         * for any type of trigger,

   159         * - Name

   160         * - Requestors

   161         * - Trigger condition

   162         *

   163         * In case of start-up trigger, the following attribute is 

   164         * also mandatory

   165         * - Process Identity

   166         *

   167         * Although manager UI is not a mandatory attribute, it's highly 

   168         * recommended that correct manager UI is specified. 

   169         *

   170         * Currently, the system only supports CLbtTriggerConditionArea

   171         * to be used as trigger condition. Following 

   172         * attributes must be specified,

   173         * - Trigger area 

   174         * - Direction

   175         *

   176         * Currently, only CLbtGeoCircle can be used as trigger area. The

   177         * center of the geographical circle must be specified. 

   178         * 

   179         * If the radius of the trigger area is not specified, minimum 

   180         * size of trigger area will be used in the created trigger entry. 

   181         * 

   182         * The trigger ID attribute is ignored while creating a trigger. If the 

   183         * trigger is successfully created, trigger ID is returned to the 

   184         * client application.  If the trigger is enabled, Location Triggering

   185         * Server will supervise the trigger and fires it when trigger 

   186         * conditions are met.

   187         *

   188         * Creating any type triggers requires @p Location capability. 

   189         * @p WriteUserData capability is required in addition to create start-up 

   190         * triggers. 

   191         *

   192         * @see CLbtTriggerEntry CLbtSessionTrigger CLbtStartupTrigger

   193         * @see CancelCreateTrigger

   194         *

   195         * @panic LocTriggering ELbtServerBadHandle If the subsession is 

   196         * not opened.

   197         *

   198         * @param[in] aTrigger The trigger to be created. Trigger Id attribute

   199         * is ignored by Location Triggering Server.

   200         * @param[out] aTriggerId Contains trigger ID of the created trigger

   201         * When the request is completed. Trigger is is unique among all triggers

   202         * currently exist in the system. If a trigger is removed from the system,

   203         * its Id may be reused by another trigger.

   204         * @param[in] aFireOnCreation The parameter specifies if the trigger

   205         * can be fired right after the creation. 

   206         * - If this parameter is ETrue. For entry type of trigger, 

   207         * if the trigger is created inside the trigger area, it is 

   208         * fired right after it is created. For exit type of trigger, if the

   209         * trigger is created outside of the trigger area, it is

   210         * fired right after it is created. 

   211         * - If this parameter is EFalse. For entry type of 

   212         * trigger, if the trigger is created inside the trigger area, it

   213         * will not be fired immediately. The trigger will be fired when 

   214         * the terminal moves outside of the trigger area and then enters 

   215         * the trigger area again. For exit type of trigger, if the trigger 

   216         * is created outside of trigger area it will be fired immediately. 

   217         * The trigger will be fired when the terminal moves into the trigger 

   218         * area and then  moves out again. 

   219         * @param[out] aStatus Contains the error code when the 

   220         * request is completed.

   221         * - KErrNone. If the trigger is created successfully.

   222         * - KErrArgument. If any of mandatory attributes are not specified, 

   223         * the manager UI is specified but it is not a valid UI application, 

   224         * or the length of the trigger name is zero or larger than 

   225         * @p KLbtMaxNameLength.

   226         * - KErrNotSupported. If the trigger condition is not 

   227         * an instance of @p CLbtTriggerConditionBasic, or if the trigger area is 

   228         * not an instance of CLbtGeoCircle. Also returned if the trigger direction

   229         * is EFireOnExit and the trigger being created is a cell based trigger.

   230         * - KErrAccessDenied. If the requestor attributes are missing, privacy 

   231         * checking by Location Server determines that any of the specified 

   232         * requestors do not have permission to retrieve location information, 

   233         * - KErrPermisionDenied. If the client application does not have 

   234         * enough capabilities to create this trigger.

   235         * - KErrTriggeringAreaTooSmall.  If the specified trigger area is 

   236         * smaller than minimum size of trigger area.

   237         * - KErrLbtMaxTriggerLimitExceeded. If creating startup trigger exceeds

   238         * the system defined limit.

   239         * - KErrDiskFull. Disk full when creating a start-up trigger.

   240         * - Other standard Symbian error code, such as KErrNoMemory, 

   241         * KErrServerBusy, KErrGeneral. If the operation fails. 

   242         */

   243         IMPORT_C void CreateTrigger( 

   244             const CLbtTriggerEntry& aTrigger,

   245             TLbtTriggerId& aTriggerId,

   246             TBool aFireOnCreation,

   247             TRequestStatus& aStatus );

   248             

   249        /**

   250         * Cancel trigger creation.

   251         *

   252         * This function does not require any capabilities. 

   253         *

   254         * @see CreateTriggerL

   255         */

   256         IMPORT_C void CancelCreateTrigger();

   257             

   258        /**

   259         * Deletes a specific trigger from Location Triggering Server.

   260         * 

   261         * Client applications can only delete triggers owned by it. 

   262         *

   263         * Deleting any type triggers requires @p Location capability. 

   264         * @p WriteUserData capability is required in addition to delete start-up 

   265         * triggers. 

   266         *

   267         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   268         *

   269         * @param[in] aId The ID of the trigger to be deleted.

   270         *

   271         * @leave KErrNotFound If the specified trigger is not found or

   272         * it is not owned by the client application.

   273         * @leave KErrInUse If the previous write or delete operation on the

   274         * trigger is not completed yet.

   275         * @leave Other standard Symbian error code, such as KErrNoMemory,

   276         * KErrServerBusy, KErrGeneral, etc.

   277         */

   278         IMPORT_C void DeleteTriggerL( TLbtTriggerId aId );

   279 

   280        /**

   281         * Delete triggers that are owned by the client application and fulfill 

   282         * the specified criteria. 

   283         *

   284         * If none of the triggers that belong to the client application 

   285         * fulfill the specified criteria, the method leaves with KErrNotFound.

   286         *

   287         * If only a part of the triggers that fullfill the criteria belong to 

   288         * the client application, then only those triggers belonging to that 

   289         * client application would be deleted and the method would complete 

   290         * without any leave.

   291         * 

   292         * If no filter is specified, all triggers owned by the client 

   293         * application are deleted.

   294         *

   295         * Deleting any type triggers requires @p Location capability. 

   296         * @p WriteUserData capability is required in addition to delete 

   297         * start-up triggers. 

   298         * 

   299         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

   300         * opened.

   301         *

   302         * @param[in] aFilter Specify the filter for the delete operation. 

   303         * Trigger entries that fulfill the criteria will be deleted 

   304         * from Location Triggering Server. By default, no filter is used.

   305         * In this case, all triggers owned by the client applications 

   306         * will be deleted.

   307         * @leave KErrNotSupported If there is an area filter used and the area

   308         * is not a type of geographical circular or rectangular area.

   309         * @leave KErrNotFound If no trigger belonging to the client application

   310         * fullfills the criteria specified.

   311         * @leave Other standard Symbian error code, such as KErrNoMemory,

   312         * KErrServerBusy, KErrGeneral, etc.

   313         */

   314         IMPORT_C void DeleteTriggersL( 

   315             CLbtTriggerFilterBase* aFilter = NULL );

   316 

   317        /**

   318         * Delete triggers asynchronously. Triggers to be deleted must be owned

   319         * by the client application and fulfill the specified criteria.

   320         *

   321         * If no trigger that belong to the client application fulfills the 

   322         * specified criteria, the method completes the client request

   323         * with KErrNotFound.

   324         *

   325         * If only a part of the triggers that fullfill the criteria belong to 

   326         * the client application, then only those triggers belonging to that 

   327         * client application would be deleted and the method would complete 

   328         * without any error.

   329         *

   330         * If no filter is specified, all triggers owned by the client 

   331         * application are deleted.

   332         *

   333         * Deleting any type triggers requires @p Location capability. 

   334         * @p WriteUserData capability is required in addition to delete start-up 

   335         * triggers. 

   336         * 

   337         * @panic LocTriggering ELbtServerBadHandle If the subsession is not

   338         * opened.

   339         *

   340         * @param[out] aStatus Contains the error code when the 

   341         * request is completed.

   342         * - KErrNone If the operation was successful.

   343         * - KErrNotFound If no trigger belonging to the client application

   344         * fullfills the criteria specified.

   345         * - Other standard Symbian error code, such as KErrNoMemory,

   346         * KErrServerBusy, KErrGeneral, etc.

   347         * @param[in] aFilter Specify the filter for the delete operation. 

   348         * Trigger entries that fulfill the criteria will be deleted 

   349         * from Location Triggering Server. Default value is NULL in which case

   350         * all triggers owned by the client applications will be deleted.

   351         */

   352         IMPORT_C void DeleteTriggers( 

   353             TRequestStatus& aStatus, 

   354             CLbtTriggerFilterBase* aFilter = NULL );

   355 

   356        /**

   357         * Delete triggers based on a list of trigger Ids. The triggers to 

   358         * be deleted must be owned by the client application. 

   359         *

   360         * If none of the triggers to be deleted are owned by the client 

   361         * application then no triggers would be deleted and this method 

   362         * will leave with KErrNotFound.

   363         *

   364         * If the list is empty, no trigger will be deleted and this method 

   365         * completes without any leave. 

   366         * 

   367         * In the case where a list of trigger IDs are mentioned of which only 

   368         * a few of those belong to the client, then only all those triggers 

   369         * that belong to the client will be deleted and the rest ignored. The 

   370         * method will complete without any leave in this case.

   371         * 

   372         * Deleting any type of triggers requires @p Location capability. 

   373         * @p WriteUserData capability is required in addition to delete start-up 

   374         * triggers. 

   375         * 

   376         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   377         *

   378         * @param[in] aTriggerIdList The list contains IDs of the triggers

   379         * that are to be deleted. 

   380         * @leave Other standard Symbian error code, such as KErrNoMemory,

   381         * KErrServerBusy, KErrGeneral, etc.

   382         */

   383         IMPORT_C void DeleteTriggersL( 

   384             const RArray<TLbtTriggerId> &aTriggerIdList );

   385 

   386        /**

   387         * Delete triggers asynchronously based on a list of trigger Ids. 

   388         * The triggers to be deleted must be owned by the client application.

   389         *

   390         * If none of the triggers to be deleted are owned by the client 

   391         * application then no triggers would be deleted and this method 

   392         * will complete the request with KErrNotFound.

   393         * 

   394         * If the list is empty, no trigger will be deleted and this method 

   395         * completes without any error code.

   396         * 

   397         * In the case where a list of trigger IDs are mentioned of which only 

   398         * a few of those belong to the client, then only all those triggers 

   399         * that belong to the client will be deleted and the rest ignored. The 

   400         * method will complete without any leave in this case.

   401         *

   402         * Deleting any type of triggers requires @p Location capability. 

   403         * @p WriteUserData capability is required in addition to delete 

   404         * start-up triggers. 

   405         * 

   406         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

   407         * opened.

   408         *

   409         * @param[in] aTriggerIdList The list contains IDs of the triggers

   410         * that are to be deleted. 

   411         * @param[out] aStatus Contains the error code when the 

   412         * request is completed.

   413         * - KErrNone If the operation was succeed.

   414         * - Other standard Symbian error code, such as KErrNoMemory,

   415         * KErrServerBusy, KErrGeneral, etc.

   416         */

   417         IMPORT_C void DeleteTriggers( 

   418             const RArray<TLbtTriggerId>& aTriggerIdList,

   419             TRequestStatus& aStatus );

   420         

   421        /**

   422         * Cancel delete triggers operation.

   423         *

   424         * This function does not require any capabilities. 

   425         *

   426         * @see DeleteTriggers

   427         */

   428         IMPORT_C void CancelDeleteTriggers();     

   429 

   430        /**

   431         * Gets the specified trigger from Location Triggering Server. 

   432         * 

   433         * Client application takes the ownership ofthe returned trigger object.

   434         * The returned trigger object is left in cleanup stack when the 

   435         * trigger entry is successfully retrieved.

   436         *

   437         * Each trigger entry object consumes about 100 - 200 bytes user heap,

   438         * if all attributes are filled. To save memory usage, 

   439         * client applications can retrieve trigger object with only partial 

   440         * attributes filled. 

   441         *

   442         * This method requires @p Location capability. 

   443         *

   444         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

   445         * opened.

   446         * @param[in] aId The ID of the trigger to be retrieved.

   447         * @param[in] aEntryFieldMask The trigger entry's attribute field mask.

   448         * It specifies what attributes shall be filled in the returned 

   449         * trigger object. The default value is KLbtTriggerAttributeFieldsAll, 

   450         * which means all attributes field will be filled. Wether the trigger ID 

   451         * attribute is specified or not in this mask, the returned 

   452         * trigger object always contains a valid trigger Id.

   453         * @param[in] aDynInfoFieldMask Specifies which dynamic information

   454         * field shall be filled in the returned object. The default value is

   455         * KLbtTriggerDynInfoFieldsAll, which means all dynamic information

   456         * fields will be filled.

   457         * @return The retrieved trigger object. Ownership of the object is

   458         * transferred to the client application.

   459         * @leave KErrNotFound If the specified trigger is not found or it's

   460         * not owned by the client application.

   461         * @leave Other standard Symbian error code, such as KErrNoMemory,

   462         * KErrServerBusy, KErrGeneral, etc.

   463         */

   464         IMPORT_C CLbtTriggerInfo* GetTriggerLC( 

   465             TLbtTriggerId aId,

   466             TLbtTriggerAttributeFieldsMask aEntryFieldMask = 

   467                 KLbtTriggerAttributeFieldsAll,

   468             TLbtTriggerDynamicInfoFieldsMask  aDynInfoFieldMask = 

   469                 KLbtTriggerDynInfoFieldsAll );

   470 

   471        /**

   472         * Changes the attributes of the specified trigger.

   473         *

   474         * Client applications can use this method to change attributes of a

   475         * specified trigger that is owned by it. Client applications can

   476         * only update triggers owned by itself.

   477         *

   478         * Some attributes are not modifiable after the trigger is created. Trying 

   479         * to change the following attributes will generate a leave with 

   480         * error code KErrAccessDenied.

   481         * 

   482         * For any type of the trigger, the following attributes can't be

   483         * modified after the trigger is created.

   484         * - ID

   485         * - Requestor

   486         * - Manager UI

   487         *

   488         * The following attribute can't be modified in addition for 

   489         * start-up triggers.

   490         * - Trigger handling process identity

   491         * - Trigger handling process SID

   492         *

   493         * If the specified trigger does not belong to the client application 

   494         * the method leaves with KErrNotFound.

   495         *

   496         * Updating any type triggers requires @p Location capability. 

   497         * @p WriteUserData capability is required in addition to update start-up 

   498         * triggers. 

   499         *

   500         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   501         *

   502         * @param[in] aTrigger The trigger object to be updated in Location 

   503         * Triggering Server. The trigger ID identifies the trigger to be updated.

   504         * @param[in] aFieldMask Specifies the attribute fields that are valid in 

   505         * the aTrigger and shall be updated to the trigger. Trigger ID

   506         * field in aTrigger is always used regardless whether the trigger ID 

   507         * field is marked or not in the mask. The attribute value in aTrigger 

   508         * is ignored if the attribute field in aFieldMask is not marked.

   509         * @param[in] aFireOnUpdate The parameter specifies if the trigger

   510         * can be fired right after the update operation. 

   511         * - If this parameter is ETrue. For entry type of trigger, 

   512         * if the trigger is updated inside the trigger area, it is 

   513         * fired right after it is updated. For exit type of trigger, if the

   514         * trigger is updated outside of the trigger area, it is

   515         * fired right after it is updated. 

   516         * - If this parameter is EFalse. For entry type of 

   517         * trigger, if the trigger is updated inside the trigger area, it

   518         * will not be fired immediately. The trigger will be fired when 

   519         * the terminal moves outside of the trigger area and then enters 

   520         * the trigger area again. For exit type of trigger, if the trigger 

   521         * is updated outside of trigger area it will be fired immediately. 

   522         * The trigger will be fired when the terminal moves into the trigger 

   523         * area and then  moves out again. 

   524         * @leave KErrNotFound If the specified trigger is not found or it's

   525         * not owned by the client application.

   526         * @leave KErrAccessDenied If the client application tries to change 

   527         * the attributes which are not modifiable.

   528         * @leave KErrArgument If the length of trigger name is zero or 

   529         * larger than @p KLbtMaxNameLength. 

   530         * @leave Other standard Symbian error code, such as KErrNoMemory,

   531         * KErrServerBusy, KErrGeneral, etc.

   532         */

   533         IMPORT_C void UpdateTriggerL( 

   534             const CLbtTriggerEntry& aTrigger,

   535             TLbtTriggerAttributeFieldsMask aFieldMask,

   536             TLbtFireOnUpdate aFireOnUpdate );

   537             

   538             

   539        /**

   540         * Changes the attributes of the specified trigger asynchronously

   541         *

   542         * Client applications can use this method to change attributes of a

   543         * specified trigger that is owned by it. Client applications can

   544         * only update triggers owned by itself.

   545         *

   546         * Some attributes are not modifiable after the trigger is created. Trying 

   547         * to change the following attributes will generate a leave with 

   548         * error code KErrAccessDenied.

   549         * 

   550         * For any type of the trigger, the following attributes can't be

   551         * modified after the trigger is created.

   552         * - ID

   553         * - Requestor

   554         * - Manager UI

   555         *

   556         * The following attribute can't be modified in addition for 

   557         * start-up triggers.

   558         * - Trigger handling process identity

   559         * - Trigger handling process SID

   560         *

   561         * If the specified trigger does not belong to the client application 

   562         * the method leaves with KErrNotFound.

   563         *

   564         * Updating any type triggers requires @p Location capability. 

   565         * @p WriteUserData capability is required in addition to update start-up 

   566         * triggers. 

   567         *

   568         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   569         *

   570         * @param[in] aTrigger The trigger object to be updated in Location 

   571         * Triggering Server. The trigger ID identifies the trigger to be updated.

   572         * @param[in] aFieldMask Specifies the attribute fields that are valid in 

   573         * the aTrigger and shall be updated to the trigger. Trigger ID

   574         * field in aTrigger is always used regardless whether the trigger ID 

   575         * field is marked or not in the mask. The attribute value in aTrigger 

   576         * is ignored if the attribute field in aFieldMask is not marked.

   577         * @param[in] aFireOnUpdate The parameter specifies if the trigger

   578         * can be fired right after the update operation. 

   579         * - If this parameter is ETrue. For entry type of trigger, 

   580         * if the trigger is updated inside the trigger area, it is 

   581         * fired right after it is updated. For exit type of trigger, if the

   582         * trigger is updated outside of the trigger area, it is

   583         * fired right after it is updated. 

   584         * - If this parameter is EFalse. For entry type of 

   585         * trigger, if the trigger is updated inside the trigger area, it

   586         * will not be fired immediately. The trigger will be fired when 

   587         * the terminal moves outside of the trigger area and then enters 

   588         * the trigger area again. For exit type of trigger, if the trigger 

   589         * is updated outside of trigger area it will be fired immediately. 

   590         * The trigger will be fired when the terminal moves into the trigger 

   591         * area and then  moves out again. 

   592         * @leave KErrNotFound If the specified trigger is not found or it's

   593         * not owned by the client application.

   594         * @leave KErrAccessDenied If the client application tries to change 

   595         * the attributes which are not modifiable.

   596         * @leave KErrArgument If the length of trigger name is zero or 

   597         * larger than @p KLbtMaxNameLength. 

   598         * @leave Other standard Symbian error code, such as KErrNoMemory,

   599         * KErrServerBusy, KErrGeneral, etc.

   600         */

   601         IMPORT_C void UpdateTrigger( 

   602             const CLbtTriggerEntry& aTrigger,

   603             TLbtTriggerAttributeFieldsMask aFieldMask,

   604             TLbtFireOnUpdate aFireOnUpdate,

   605             TRequestStatus& aStatus );            

   606     	

   607     	  /**

   608         * Cancel update trigger operation.

   609         *

   610         * This function does not require any capabilities. 

   611         *

   612         * @see UpdateTrigger

   613         */

   614         IMPORT_C void CancelUpdateTrigger();     

   615         

   616        /**

   617         * Sets the state of the specified trigger. Client application can 

   618         * change the state of only triggers owned by it.

   619         * 

   620         * To enable the trigger, set the trigger state to

   621         * @p ELbtTriggerEnabled. To disable the trigger, 

   622         * set the trigger state to @p ELbtTriggerDisabled.

   623         *

   624         * Changing state of any type triggers requires @p Location capability. 

   625         * @p WriteUserData capability is required in addition to change state of 

   626         * start-up triggers. 

   627         *

   628         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   629         *

   630         * @param[in] aId The ID of the trigger whose state will be updated.

   631         * @param[in] aState New state of the specified trigger.

   632         * @param[in] aFireOnUpdate The parameter specifies if the trigger

   633         * can be fired right after the update operation. 

   634         * - If this parameter is ETrue. For entry type of trigger, 

   635         * if the trigger is updated inside the trigger area, it is 

   636         * fired right after it is updated. For exit type of trigger, if the

   637         * trigger is updated outside of the trigger area, it is

   638         * fired right after it is updated. 

   639         * - If this parameter is EFalse. For entry type of 

   640         * trigger, if the trigger is updated inside the trigger area, it

   641         * will not be fired immediately. The trigger will be fired when 

   642         * the terminal moves outside of the trigger area and then enters 

   643         * the trigger area again. For exit type of trigger, if the trigger 

   644         * is updated outside of trigger area it will be fired immediately. 

   645         * The trigger will be fired when the terminal moves into the trigger 

   646         * area and then  moves out again.        

   647         * @leave KErrNotFound If the specified trigger is not found or it's

   648         * not owned by the client application.

   649         * @leave Other standard Symbian error code, such as KErrNoMemory,

   650         * KErrServerBusy, KErrGeneral, etc.

   651         */

   652         IMPORT_C void SetTriggerStateL( 

   653             TLbtTriggerId aId, 

   654             CLbtTriggerEntry::TLbtTriggerState aState,

   655             TLbtFireOnUpdate aFireOnUpdate );

   656 

   657        /**

   658         * Sets state of multiple triggers. Client application can change state

   659         * of only triggers owned by it.

   660         *

   661         * If a filter is specified, all triggers that fulfill the criteria 

   662         * and owned by the requesting client application will be affected.

   663         * 

   664         * If no filter is specified, all triggers owned by the client 

   665         * application will be affected.

   666         *

   667         * If no trigger owned by the client application fulfills the specified 

   668         * criteria, no trigger will be modified and the method leaves with

   669         * KErrNotFound.

   670         *

   671         * Changing state of any type triggers requires @p Location capability. 

   672         * @p WriteUserData capability is required in addition to change state of 

   673         * start-up triggers. 

   674         *

   675         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   676         *

   677         * @param[in] aState New state of the triggers.

   678         * @param[in] aFireOnUpdate The parameter specifies if the trigger

   679         * can be fired right after the update operation. 

   680         * - If this parameter is ETrue. For entry type of trigger, 

   681         * if the trigger is updated inside the trigger area, it is 

   682         * fired right after it is updated. For exit type of trigger, if the

   683         * trigger is updated outside of the trigger area, it is

   684         * fired right after it is updated. 

   685         * - If this parameter is EFalse. For entry type of 

   686         * trigger, if the trigger is updated inside the trigger area, it

   687         * will not be fired immediately. The trigger will be fired when 

   688         * the terminal moves outside of the trigger area and then enters 

   689         * the trigger area again. For exit type of trigger, if the trigger 

   690         * is updated outside of trigger area it will be fired immediately. 

   691         * The trigger will be fired when the terminal moves into the trigger 

   692         * area and then  moves out again.        

   693         * @param[in] aFilter The filter to be used. Triggers that fulfill

   694         * the criteria of the specified filter will be affected. 

   695         * Default value is NULL in which case all triggers owned by the client 

   696         * application will be updated.

   697         * @leave KErrNotSupported If there is an area filter used and the area

   698         * is not a type of geographical circular or rectangular area.

   699         * @leave Other standard Symbian error code, such as KErrNoMemory,

   700         * KErrServerBusy, KErrGeneral, etc.

   701         */

   702         IMPORT_C void SetTriggersStateL( 

   703             CLbtTriggerEntry::TLbtTriggerState aState,

   704             TLbtFireOnUpdate aFireOnUpdate,

   705             CLbtTriggerFilterBase* aFilter = NULL );

   706 

   707        /**

   708         * Sets state of multiple triggers asynchronously.

   709         *

   710         * If a filter is specified, all triggers owned by the client 

   711         * application that fulfill the  criteria will be affected.

   712         *

   713         * If no filter is specified, all triggers owned by the client 

   714         * application will be affected.

   715         *

   716         * If no trigger that are owned by the client application fulfills the

   717         * specified criteria, no trigger will be modified and this completes 

   718         * with KErrNotFound.

   719         *

   720         * Changing state of any type triggers requires @p Location capability. 

   721         * @p WriteUserData capability is required in addition to change state of 

   722         * start-up triggers. 

   723         *

   724         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   725         *

   726         * @param[out] aStatus Contains the error code when the 

   727         * request is completed.

   728         * - KErrNotSupported If there is an area filter used and the area

   729         * is not a type of geographical circular or rectangular area.

   730         * - Other standard Symbian error code, such as KErrNoMemory,

   731         * KErrServerBusy, KErrGeneral, etc.

   732         * @param[in] aState New state of the triggers.

   733         * @param[in] aFireOnUpdate The parameter specifies if the trigger

   734         * can be fired right after the update operation. 

   735         * - If this parameter is ETrue. For entry type of trigger, 

   736         * if the trigger is updated inside the trigger area, it is 

   737         * fired right after it is updated. For exit type of trigger, if the

   738         * trigger is updated outside of the trigger area, it is

   739         * fired right after it is updated. 

   740         * - If this parameter is EFalse. For entry type of 

   741         * trigger, if the trigger is updated inside the trigger area, it

   742         * will not be fired immediately. The trigger will be fired when 

   743         * the terminal moves outside of the trigger area and then enters 

   744         * the trigger area again. For exit type of trigger, if the trigger 

   745         * is updated outside of trigger area it will be fired immediately. 

   746         * The trigger will be fired when the terminal moves into the trigger 

   747         * area and then  moves out again.        

   748         * @param[in] aFilter The filter to be used. Triggers that fulfill

   749         * the criteria of the specified filter will be affected. 

   750         * Default is value is NULL in which case all triggers owned by the 

   751         * client application will be updated.

   752         */

   753         IMPORT_C void SetTriggersState( 

   754             TRequestStatus& aStatus,

   755             CLbtTriggerEntry::TLbtTriggerState aState,

   756             TLbtFireOnUpdate aFireOnUpdate,

   757             CLbtTriggerFilterBase* aFilter = NULL );

   758         

   759        /**

   760         * Cancel set trigger state operation.

   761         *

   762         * This function does not require any capabilities. 

   763         *

   764         * @see SetTriggersState

   765         */

   766         IMPORT_C void CancelSetTriggersState();     

   767 

   768        /**

   769         * Lists IDs of triggers that are owned by the client application.

   770         * 

   771         * Client applications can specify options used in retrieving 

   772         * trigger IDs.

   773         * 

   774         * This method requires @p Location capability. 

   775         *

   776         * @see CLbtListTriggerOptions

   777         *

   778         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   779         *

   780         * @param[out] aTriggerIdList On return, aTriggerIdList contains IDs of

   781         * retrieved triggers. The content of aTriggerIdList will be cleared 

   782         * even if this function fails.

   783         * @param[in] aListOptions Specified the options used for listing 

   784         * triggers. By default, the value is NULL. In this case, all triggers

   785         * owned by the client application will be retrieved. 

   786         * @leave KErrNotSupported If there is an area filter used and the area

   787         * is not a type of geographical circular or rectangular area.

   788         * @leave Other standard Symbian error code, such as KErrNoMemory,

   789         * KErrServerBusy, KErrGeneral, etc.

   790         */

   791         IMPORT_C void ListTriggerIdsL( 

   792             RArray < TLbtTriggerId >& aTriggerIdList,

   793             CLbtListTriggerOptions* aListOptions = NULL );

   794 

   795        /**

   796         * Lists asynchronously IDs of triggers that are owned by the 

   797         * client application.

   798         * 

   799         * Client applications can specify options used in retrieving 

   800         * trigger IDs.

   801         * 

   802         * This method requires @p Location capability. 

   803         *

   804         * @see CLbtListTriggerOptions

   805         *

   806         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

   807         * opened.

   808         *

   809         * @param[out] aStatus Contains the error code when the 

   810         * request is completed. KErrNotSupported is returned if there is an area 

   811         * filter used and the area is not a type of geographical circular or 

   812         * rectangular area.

   813         * - KErrNotSupported If there is an area filter used and the area

   814         * is not a type of geographical circular or rectangular area.

   815         * - Other standard Symbian error code, such as KErrNoMemory,

   816         * KErrServerBusy, KErrGeneral, etc.

   817         * @param[out] aTriggerIdList On return, aTriggerIdList contains IDs of

   818         * retrieved triggers. The content of aTriggerIdList will be cleared 

   819         * even if this function fails.

   820         * @param[in] aListOptions Specified the options used for listing 

   821         * triggers. Default value is NULL in which case all triggers owned by 

   822         * the client application will be retrieved. 

   823         */

   824         IMPORT_C void ListTriggerIds( 

   825             TRequestStatus& aStatus,

   826             RArray < TLbtTriggerId >& aTriggerIdList,

   827             CLbtListTriggerOptions* aListOptions = NULL );

   828             

   829        /**

   830         * Cancel list trigger ids operation.

   831         *

   832         * This function does not require any capabilities. 

   833         *

   834         * @see ListTriggerIds

   835         */

   836         IMPORT_C void CancelListTriggerIds();    

   837 

   838        /**

   839         * Gets triggers from Location Triggering Server. A client application

   840         * can only retrieve triggers owned by it.

   841         * 

   842         * Client applications can specify options used in retrieving triggers.

   843         * Ownership of the returned trigger objects is transferred to 

   844         * the client application.

   845         *

   846         * Note: This function may require large free heap memory from

   847         * the client application depending on the number of triggers to 

   848         * be retrieved and the attributes to be filled.

   849         *

   850         * This method requires @p Location capability. 

   851         *

   852         * @see CLbtListTriggerOptions

   853         *

   854         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

   855         * opened.

   856         *

   857         * @param[out] aTriggerList On return, contains trigger objects retrieved

   858         * from Location Triggering Server. The content of aTriggerList is

   859         * cleared even if this function fails. The ownership of the returned 

   860         * pointers is transfered to the client application. 

   861         * @param[in] aListOptions Specifies the options for listing triggers. 

   862         * By default, the value is NULL. In this case all triggers

   863         * owned by the client application will be retrieved. 

   864         * @leave KErrNotSupported If there is an area filter used and the area

   865         * is not a type of geographical circular or rectangular area.

   866         * @leave Other standard Symbian error code, such as KErrNoMemory,

   867         * KErrServerBusy, KErrGeneral, etc.

   868         */

   869         IMPORT_C void GetTriggersL( 

   870             RPointerArray < CLbtTriggerInfo >& aTriggerList,

   871             CLbtListTriggerOptions* aListOptions = NULL );

   872         

   873        /**

   874         * Gets triggers asynchronously from Location Triggering Server. A 

   875         * client application can only retrieve triggers owned by it.

   876         * 

   877         * Client applications can specify options used in retrieving triggers.

   878         * Ownership of the returned trigger objects is transferred to 

   879         * the client application.

   880         *

   881         * Note: This function may require large free heap memory from

   882         * the client application depending on the number of triggers to 

   883         * be retrieved and the attributes to be filled.

   884         *

   885         * This method requires @p Location capability. 

   886         *

   887         * @see CLbtListTriggerOptions

   888         *

   889         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

   890         *

   891         * @param[out] aStatus Contains the error code when the 

   892         * request is completed. 

   893         * - KErrNotSupported. If there is an area 

   894         * filter used and the area is not a type of geographical circular or 

   895         * rectangular area.

   896         * - Other standard Symbian error code, such as KErrNoMemory,

   897         * KErrServerBusy, KErrGeneral, etc.

   898         * @param[out] aTriggerList On return, contains trigger objects retrieved

   899         * from Location Triggering Server. The content of aTriggerList is

   900         * cleared even if this function fails. The ownership of the returned 

   901         * pointers is transfered to the client application. 

   902         * @param[in] aListOptions Specifies the options for listing triggers. 

   903         * By default, the value is NULL. In this case all triggers

   904         * owned by the client application will be retrieved. 

   905         */

   906         IMPORT_C void GetTriggers( 

   907             TRequestStatus& aStatus,

   908             RPointerArray < CLbtTriggerInfo >& aTriggerList,

   909             CLbtListTriggerOptions* aListOptions = NULL );

   910             

   911        /**

   912         * Cancel get triggers operation.

   913         *

   914         * This function does not require any capabilities. 

   915         *

   916         * @see GetTriggers

   917         */

   918         IMPORT_C void CancelGetTriggers();    

   919 

   920        /**

   921         * Creates an iterator in Location Triggering Server to retrieve

   922         * trigger objects incrementally. 

   923         * 

   924         * An iterator must be created before GetNextTriggerLC() can be called.

   925         * The iterator is constructed in the server side and it is subsession

   926         * specific. Calling this function again will reset the iterator.

   927         * After the iterator is constructed, the client application calls 

   928         * GetNextTriggerLC() repeatedly to retrieve all interested trigger 

   929         * objects. Note, client applications can only get triggers owned by

   930         * itself.

   931         *

   932         * If any trigger is changed during iteration, the client application

   933         * shall call this method again to reset the iterator and get the 

   934         * triggers again incrementally.

   935         *

   936         * This method requires @p Location capability. 

   937         *

   938         * @see CLbtListTriggerOptions

   939         *

   940         * @panic LocTriggering  ELbtServerBadHandle If the subsession is not opened.

   941         *

   942         * @param[in] aListOptions Specifies the options used for listing 

   943         * triggers. Default value is NULL, which will retrieve all triggers

   944         * owned by the client application. 

   945         * @leave KErrNotSupported If there is an area filter used and the area

   946         * is not a type of geographical circular or rectangular area.

   947         * @leave Other standard Symbian error code, such as KErrNoMemory,

   948         * KErrServerBusy, KErrGeneral, etc.

   949         */

   950         IMPORT_C void CreateGetTriggerIteratorL( 

   951             CLbtListTriggerOptions* aListOptions = NULL );

   952 

   953        /**

   954         * Creates an iterator asynchronously in Location Triggering Server 

   955         * to retrieve trigger objects incrementally. 

   956         * 

   957         * An iterator must be created before GetNextTriggerLC() can be called.

   958         * The iterator is constructed in the server side and it is subsession

   959         * specific. Calling this function again will reset the iterator.

   960         * After the iterator is constructed, the client application calls 

   961         * GetNextTriggerLC() repeatedly to retrieve all interested trigger 

   962         * objects. Note, client applications can only get triggers owned by

   963         * itself.

   964         *

   965         * If any trigger is changed during iteration, the client application

   966         * shall call this method again to reset the iterator and get the 

   967         * triggers again incrementally.

   968         *

   969         * This method requires @p Location capability. 

   970         *

   971         * @see CLbtListTriggerOptions

   972         *

   973         * @panic LocTriggering  ELbtServerBadHandle If the subsession is not opened.

   974         *

   975         * @param[out] aStatus Contains the error code when the 

   976         * request is completed. KErrNotSupported is returned if there is an area 

   977         * filter used and the area is not a type of geographical circular or 

   978         * rectangular area.

   979         * @param[in] aListOptions Specifies the options used for listing 

   980         * triggers. Default value is NULL, which will retrieve all triggers

   981         * owned by the client application. 

   982         */

   983         IMPORT_C void CreateGetTriggerIterator( 

   984             TRequestStatus& aStatus,

   985             CLbtListTriggerOptions* aListOptions = NULL );

   986         

   987        /**

   988         * Cancel create trigger iterator operation.

   989         *

   990         * This function does not require any capabilities. 

   991         *

   992         * @see CreateGetTriggerIterator

   993         */

   994         IMPORT_C void CancelCreateTriggerIterator();     

   995 

   996        /**

   997         * Gets trigger objects incrementally.

   998         * 

   999         * This method is used together with CreateGetTriggerIteratorL() to 

  1000         * incrementally retrieve trigger objects owned by the client 

  1001         * application. If the iterator is not created when this function is

  1002         * called, client application gets a panic with code 

  1003         * @p ELbtIteratorNotCreated.

  1004         * 

  1005         * This method returns NULL when all triggers are retrieved. Client

  1006         * application shall call CreateGetTriggerIteratorL() again to

  1007         * reset the iterator.

  1008         * 

  1009         * Client application takes ownership of the returned trigger object. 

  1010         * The returned trigger object is left in cleanup stack when the trigger 

  1011         * object is successfully retrieved.

  1012         *

  1013         * This method requires @p Location capability. 

  1014         *

  1015         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

  1016         * @panic LocTriggering ELbtIteratorNotCreated If the iterator has not been created.

  1017         *

  1018         * @return The retrieved trigger object. Ownership of the returned 

  1019         * object is transferred to the client application. 

  1020         * Returns NULL if all triggers have been retrieved.

  1021         * @leave Other standard Symbian error code, such as KErrNoMemory,

  1022         * KErrServerBusy, KErrGeneral, etc.

  1023         */

  1024         IMPORT_C CLbtTriggerInfo* GetNextTriggerLC();

  1025 

  1026        /**

  1027         * Listens for change events of the triggers owned by the client 

  1028         * application.

  1029         *

  1030         * This method is used by the client application to get change events

  1031         * when one or many of its triggers are changed.

  1032         *

  1033         * Triggers can be deleted and modified not only by the owner process and

  1034         * trigger handling process, but also by other system application, 

  1035         * e.g. system management UI application. 

  1036         *

  1037         * This function is asynchronous and it will complete the request status

  1038         * when an event occurs. Client applications can get detailed information of

  1039         * the change from the retrieved event object. Client application shall

  1040         * call this function again to get further change event.

  1041         *

  1042         * Event listening can be cancelled by calling

  1043         * CancelNotifyTriggerChangeEvent().

  1044         *

  1045         * This method requires @p Location capability. 

  1046         *

  1047         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

  1048         * @panic LocTriggering ELbtDuplicateRequest If the subsession has

  1049         * already an outstanding NotifyTriggerChangeEvent() request.

  1050         *

  1051         * @param[out] aEvent Will contain the event information when an event

  1052         * occurs.

  1053         * @param[out] aStatus Will be completed with @p KErrNone if an event occurs

  1054         *   and an error code(for example, KErrServerBusy, etc.) if some error 

  1055         *   was encountered.

  1056         */

  1057         IMPORT_C void NotifyTriggerChangeEvent( 

  1058             TLbtTriggerChangeEvent& aEvent, 

  1059             TRequestStatus& aStatus );

  1060 

  1061        /**

  1062         * Cancels listening for trigger change event.

  1063         * 

  1064         * This function does not require any capabilities. 

  1065         *

  1066         * @see NotifyTriggerChangeEvent

  1067         */

  1068         IMPORT_C void CancelNotifyTriggerChangeEvent();

  1069 

  1070        /**

  1071         * Listens for the event if any trigger is fired. 

  1072         *

  1073         * Client applications can use this method to get notified 

  1074         * when a trigger (session triggers and start-up triggers) is 

  1075         * fired. The firing information is 

  1076         * returned to the client application. If more that one  

  1077         * trigger is fired, Location Triggers Server will complete 

  1078         * the request and  the first fired trigger is returned. 

  1079         * Client application shall call this method again to get next 

  1080         * trigger firing event. 

  1081         *

  1082         * When a start-up trigger is fired, Location Triggering

  1083         * Server will first launch the specified trigger

  1084         * handling process, and then notify the client application

  1085         * about the firing event.

  1086         *

  1087         * A client application will get firing event of 

  1088         * - triggers that are created by itself(Client application is

  1089         * the owner process of the trigger).

  1090         * - triggers that trigger handling process SID is set and

  1091         * matches SID of the client application's process(Client 

  1092         * application is the triggering handling process of the 

  1093         * trigger, and it can access the trigger). 

  1094         *

  1095         * The request is canceled by CancelNotifyTriggerFired()

  1096         *

  1097         * This method requires @p Location capability. 

  1098         *

  1099         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.

  1100         * @panic LocTriggering ELbtDuplicateRequest If the subsession has

  1101         * already an outstanding NotifyTriggerFired() request.

  1102         *

  1103         * @param[out] aFireInfo On return contains the fired  

  1104         * trigger's firing information.

  1105         * @param[out] aStatus Will be completed with @p KErrNone if an event

  1106         * occurs, and an error code( for example KErrServerBusy, etc.) if some 

  1107         * error encountered.

  1108         */

  1109         IMPORT_C void NotifyTriggerFired( 

  1110             TLbtTriggerFireInfo& aFireInfo, 

  1111             TRequestStatus& aStatus );

  1112 

  1113        /**

  1114         * Cancels listening for the trigger fired event.

  1115         *

  1116         * This function does not require any capabilities. 

  1117         *

  1118         * @see NotifyTriggerFired

  1119         */

  1120         IMPORT_C void CancelNotifyTriggerFired();

  1121 

  1122        /**

  1123         * Gets fired trigger's information. 

  1124         * 

  1125         * This method is used by the client application to get information 

  1126         * of all the fired triggers( session triggers and start-up triggers). 

  1127         * If the same trigger is 

  1128         * fired more than once before the client application retrieves 

  1129         * the firing information, only the most recent fired

  1130         * information is returned. If no trigger has been fired, 

  1131         * an empty list is returned.

  1132         *

  1133         * This method requires @p Location capability. 

  1134         *

  1135         * @panic LocTriggering ELbtServerBadHandle If the subsession is not opened.