/*

 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

 * which accompanies this distribution, and is available

 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  location triggering server client interface

 *

 */

 #ifndef LBT_H

 #define LBT_H

 #include <e32std.h>

 #include <lbs.h>

 #include <lbtserver.h>

 #include <lbttriggerentry.h>

 #include <lbtcommon.h>

 #include <lbttriggerchangeevent.h>

 #include <lbttriggeringsystemsettings.h>

 #include <lbtlisttriggeroptions.h>

 class CLbtTriggerEntry;

 class CLbtTriggerFilterBase;

 class CLbtListTriggerOptions;

 class CLbtTriggerInfo;

 class CLbtClientRequester;

 class CLbtSubSessnPtrHolder;

 struct TLbtTriggerCreationInfo;

 struct TLbtTriggerUpdationInfo;

 struct TLbtTriggerStateInfo;

 /**

  * 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. 

  *

  * @see RLbtServer

  * 

  * @lib lbt.lib

  *

  * @since S60 5.1

  */

 class RLbt : public RSubSessionBase

     {

     public:

        /**

         * Opens a subsession with Location Triggering Server.

         *

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

         * 

         * @panic LocTriggering ELbtServerBadHandle If a session to Location 

         * Triggering Server has not been connected.

         *

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

         * session.

         *

         * @return KErrNone if successful. Otherwise, Symbian standard 

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

         */

         IMPORT_C TInt Open( RLbtServer& aServer );

        /**

         * 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. 

         *

         * @panic LocTriggering ELbtServerBadHandle If a session to Location 

         * Triggering Server has not been connected.

         *

         * @return KErrNone if successful. Otherwise, Symbian standard 

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

         */

         IMPORT_C TInt Open();

        /**

         * 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. 

         * 

         * @panic LocTriggering ELbtRequestsNotCancelled If client application 

         * has requests outstanding with Location Triggering Server.

         */

         IMPORT_C void Close();

        /**

         * 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. 

         *

         * While creating a trigger, the following attributes are mandatory 

         * for any type of trigger,

         * - Name

         * - Requestors

         * - Trigger condition

         *

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

         * also mandatory

         * - Process Identity

         *

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

         * recommended that correct manager UI is specified. 

         *

         * Currently, the system only supports CLbtTriggerConditionArea

         * to be used as trigger condition. Following 

         * attributes must be 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 @p Location capability. 

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

         * triggers. 

         *

         * @see CLbtTriggerEntry CLbtSessionTrigger CLbtStartupTrigger

         * @see CancelCreateTrigger

         *

         * @panic LocTriggering ELbtServerBadHandle If the subsession is 

         * not opened.

         *

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

         * is ignored by Location Triggering Server.

         * @param[out] 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.

         * @param[in] 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. 

         * @param[out] 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 

         * @p KLbtMaxNameLength.

         * - KErrNotSupported. If the trigger condition is not 

         * an instance of @p 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. 

         */

         IMPORT_C void CreateTrigger( 

             const CLbtTriggerEntry& aTrigger,

             TLbtTriggerId& aTriggerId,

             TBool aFireOnCreation,

             TRequestStatus& aStatus );

        /**

         * Cancel trigger creation.

         *

         * This function does not require any capabilities. 

         *

         * @see CreateTriggerL

         */

         IMPORT_C void CancelCreateTrigger();

        /**

         * Deletes a specific trigger from Location Triggering Server.

         * 

         * Client applications can only delete triggers owned by it. 

         *

         * Deleting any type triggers requires @p Location capability. 

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

         * triggers. 

         *

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

         *

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

         *

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

         * it is not owned by the client application.

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

         * trigger is not completed yet.

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void DeleteTriggerL( TLbtTriggerId aId );

        /**

         * 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 @p Location capability. 

         * @p WriteUserData capability is required in addition to delete 

         * start-up triggers. 

         * 

         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

         * opened.

         *

         * @param[in] aFilter 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.

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

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

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

         * fullfills the criteria specified.

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void DeleteTriggersL( 

             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 @p Location capability. 

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

         * triggers. 

         * 

         * @panic LocTriggering ELbtServerBadHandle If the subsession is not

         * opened.

         *

         * @param[out] 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.

         * @param[in] aFilter 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( 

             TRequestStatus& aStatus, 

             CLbtTriggerFilterBase* aFilter = NULL );

        /**

         * 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 @p Location capability. 

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

         * triggers. 

         * 

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

         *

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

         * that are to be deleted. 

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void DeleteTriggersL( 

             const RArray<TLbtTriggerId> &aTriggerIdList );

        /**

         * 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 @p Location capability. 

         * @p WriteUserData capability is required in addition to delete 

         * start-up triggers. 

         * 

         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

         * opened.

         *

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

         * that are to be deleted. 

         * @param[out] 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 DeleteTriggers( 

             const RArray<TLbtTriggerId>& aTriggerIdList,

             TRequestStatus& aStatus );

        /**

         * Cancel delete triggers operation.

         *

         * This function does not require any capabilities. 

         *

         * @see DeleteTriggers

         */

         IMPORT_C void CancelDeleteTriggers();     

        /**

         * 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 @p Location capability. 

         *

         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

         * opened.

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

         * @param[in] aEntryFieldMask 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.

         * @param[in] aDynInfoFieldMask 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.

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

         * transferred to the client application.

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

         * not owned by the client application.

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C CLbtTriggerInfo* GetTriggerLC( 

             TLbtTriggerId aId,

             TLbtTriggerAttributeFieldsMask aEntryFieldMask = 

                 KLbtTriggerAttributeFieldsAll,

             TLbtTriggerDynamicInfoFieldsMask  aDynInfoFieldMask = 

                 KLbtTriggerDynInfoFieldsAll );

        /**

         * 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.

         * 

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

         * modified after the trigger is created.

         * - ID

         * - Requestor

         * - Manager UI

         *

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

         * start-up triggers.

         * - 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 @p Location capability. 

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

         * triggers. 

         *

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

         *

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

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

         * @param[in] 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.

         * @param[in] 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. 

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

         * not owned by the client application.

         * @leave KErrAccessDenied If the client application tries to change 

         * the attributes which are not modifiable.

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

         * larger than @p KLbtMaxNameLength. 

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void UpdateTriggerL( 

             const CLbtTriggerEntry& aTrigger,

             TLbtTriggerAttributeFieldsMask aFieldMask,

             TLbtFireOnUpdate aFireOnUpdate );

        /**

         * 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.

         * 

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

         * modified after the trigger is created.

         * - ID

         * - Requestor

         * - Manager UI

         *

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

         * start-up triggers.

         * - 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 @p Location capability. 

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

         * triggers. 

         *

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

         *

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

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

         * @param[in] 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.

         * @param[in] 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. 

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

         * not owned by the client application.

         * @leave KErrAccessDenied If the client application tries to change 

         * the attributes which are not modifiable.

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

         * larger than @p KLbtMaxNameLength. 

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void UpdateTrigger( 

             const CLbtTriggerEntry& aTrigger,

             TLbtTriggerAttributeFieldsMask aFieldMask,

             TLbtFireOnUpdate aFireOnUpdate,

             TRequestStatus& aStatus );            

     	  /**

         * Cancel update trigger operation.

         *

         * This function does not require any capabilities. 

         *

         * @see UpdateTrigger

         */

         IMPORT_C void CancelUpdateTrigger();     

        /**

         * 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

         * @p ELbtTriggerEnabled. To disable the trigger, 

         * set the trigger state to @p ELbtTriggerDisabled.

         *

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

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

         * start-up triggers. 

         *

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

         *

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

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

         * @param[in] 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.        

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

         * not owned by the client application.

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void SetTriggerStateL( 

             TLbtTriggerId aId, 

             CLbtTriggerEntry::TLbtTriggerState aState,

             TLbtFireOnUpdate aFireOnUpdate );

        /**

         * 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 @p Location capability. 

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

         * start-up triggers. 

         *

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

         *

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

         * @param[in] 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.        

         * @param[in] aFilter 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.

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

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

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void SetTriggersStateL( 

             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 @p Location capability. 

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

         * start-up triggers. 

         *

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

         *

         * @param[out] 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.

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

         * @param[in] 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.        

         * @param[in] aFilter 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 SetTriggersState( 

             TRequestStatus& aStatus,

             CLbtTriggerEntry::TLbtTriggerState aState,

             TLbtFireOnUpdate aFireOnUpdate,

             CLbtTriggerFilterBase* aFilter = NULL );

        /**

         * Cancel set trigger state operation.

         *

         * This function does not require any capabilities. 

         *

         * @see SetTriggersState

         */

         IMPORT_C void CancelSetTriggersState();     

        /**

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

         * 

         * Client applications can specify options used in retrieving 

         * trigger IDs.

         * 

         * This method requires @p Location capability. 

         *

         * @see CLbtListTriggerOptions

         *

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

         *

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

         * retrieved triggers. The content of aTriggerIdList will be cleared 

         * even if this function fails.

         * @param[in] aListOptions 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. 

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

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

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void ListTriggerIdsL( 

             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 @p Location capability. 

         *

         * @see CLbtListTriggerOptions

         *

         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

         * opened.

         *

         * @param[out] 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.

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

         * retrieved triggers. The content of aTriggerIdList will be cleared 

         * even if this function fails.

         * @param[in] aListOptions 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 ListTriggerIds( 

             TRequestStatus& aStatus,

             RArray < TLbtTriggerId >& aTriggerIdList,

             CLbtListTriggerOptions* aListOptions = NULL );

        /**

         * Cancel list trigger ids operation.

         *

         * This function does not require any capabilities. 

         *

         * @see ListTriggerIds

         */

         IMPORT_C void CancelListTriggerIds();    

        /**

         * 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 @p Location capability. 

         *

         * @see CLbtListTriggerOptions

         *

         * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

         * opened.

         *

         * @param[out] 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. 

         * @param[in] aListOptions 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. 

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

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

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void GetTriggersL( 

             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 @p Location capability. 

         *

         * @see CLbtListTriggerOptions

         *

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

         *

         * @param[out] 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.

         * @param[out] 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. 

         * @param[in] aListOptions 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. 

         */

         IMPORT_C void GetTriggers( 

             TRequestStatus& aStatus,

             RPointerArray < CLbtTriggerInfo >& aTriggerList,

             CLbtListTriggerOptions* aListOptions = NULL );

        /**

         * Cancel get triggers operation.

         *

         * This function does not require any capabilities. 

         *

         * @see GetTriggers

         */

         IMPORT_C void CancelGetTriggers();    

        /**

         * 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 @p Location capability. 

         *

         * @see CLbtListTriggerOptions

         *

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

         *

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

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

         * owned by the client application. 

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

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

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void CreateGetTriggerIteratorL( 

             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 @p Location capability. 

         *

         * @see CLbtListTriggerOptions

         *

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

         *

         * @param[out] 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.

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

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

         * owned by the client application. 

         */

         IMPORT_C void CreateGetTriggerIterator( 

             TRequestStatus& aStatus,

             CLbtListTriggerOptions* aListOptions = NULL );

        /**

         * Cancel create trigger iterator operation.

         *

         * This function does not require any capabilities. 

         *

         * @see CreateGetTriggerIterator

         */

         IMPORT_C void CancelCreateTriggerIterator();     

        /**

         * 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 

         * @p 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 @p Location capability. 

         *

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

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

         *

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

         * object is transferred to the client application. 

         * Returns NULL if all triggers have been retrieved.

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C CLbtTriggerInfo* GetNextTriggerLC();

        /**

         * 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 @p Location capability. 

         *

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

         * @panic LocTriggering ELbtDuplicateRequest If the subsession has

         * already an outstanding NotifyTriggerChangeEvent() request.

         *

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

         * occurs.

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

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

         *   was encountered.

         */

         IMPORT_C void NotifyTriggerChangeEvent( 

             TLbtTriggerChangeEvent& aEvent, 

             TRequestStatus& aStatus );

        /**

         * Cancels listening for trigger change event.

         * 

         * This function does not require any capabilities. 

         *

         * @see NotifyTriggerChangeEvent

         */

         IMPORT_C void CancelNotifyTriggerChangeEvent();

        /**

         * 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.

         *

         * A client application will get firing event of 

         * - 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 @p Location capability. 

         *

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

         * @panic LocTriggering ELbtDuplicateRequest If the subsession has

         * already an outstanding NotifyTriggerFired() request.

         *

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

         * trigger's firing information.

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

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

         * error encountered.

         */

         IMPORT_C void NotifyTriggerFired( 

             TLbtTriggerFireInfo& aFireInfo, 

             TRequestStatus& aStatus );

        /**

         * Cancels listening for the trigger fired event.

         *

         * This function does not require any capabilities. 

         *

         * @see NotifyTriggerFired

         */

         IMPORT_C void CancelNotifyTriggerFired();

        /**

         * 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 @p Location capability. 

         *

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

         *

         * @param[out] aTriggerInfoList On return contains fired triggers'

         * information.

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

         * KErrServerBusy, KErrGeneral, etc.

         */

         IMPORT_C void GetFiredTriggersL( 

             RArray < TLbtTriggerFireInfo >& aTriggerInfoList );

        /**

         * 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 @p ReadUserData capability. 

         *

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

         * @panic LocTriggering ELbtDuplicateRequest If the subsession has

         * already an outstanding NotifyTriggeringSystemSettingChange() 

         * request.

         *

         * @param[out] aSettings On return contains the new triggering

         * system settings.

         * @param[out] aStatus Will be completed with @p 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 void NotifyTriggeringSystemSettingChange( 

             TLbtTriggeringSystemSettings& aSettings,

             TRequestStatus& aStatus );

        /**

         * Cancels listening for triggering system setting change event.

         *

         * @see NotifyTriggeringSystemSettingChange

         */

         IMPORT_C void CancelNotifyTriggeringSystemSettingChange();

        /**

         * 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 @p ReadUserData capability. 

         *

         * @since S60 5.1

         *

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

         *

         * @param[out] aSetting On return contains triggering system 

         * settings.

         * @leave KErrPermissionDenied if the client application does not 

         * have enough capabilities to retrieve the settings.

         */

         IMPORT_C void GetTriggeringSystemSettingsL( 

             TLbtTriggeringSystemSettings& aSetting );

        /**

         * Cancels all asynchronous operation that has been issued from 

         * this subsession.

         */    

         IMPORT_C void CancelAll();     

        /**

         * Default constructor.

         */

         IMPORT_C RLbt();

        /**

         * Destructor.

         */

         IMPORT_C ~RLbt();

     private:

        /**

         * Helper method for create trigger operation.

         */

         void CreateTriggerL( 

             const CLbtTriggerEntry& aTrigger,

             TLbtTriggerId& aTriggerId,

             TBool aFireOnCreation,

             TRequestStatus& aStatus );

        /**

         * Helper method for delete triggers operation.

         */    

         void DeleteTriggersL( 

             CLbtTriggerFilterBase* aFilter,

             TRequestStatus& aStatus );

        /**

         * Helper method for delete triggers operation.

         */     

         void DeleteTriggersL( 

             const RArray<TLbtTriggerId>& aTriggerIdList,

             TRequestStatus& aStatus );

         /**

          * Helper method for update trigger operation.

          */ 

         void UpdateTriggerL( 

                     const CLbtTriggerEntry& aTrigger,

                     TLbtTriggerAttributeFieldsMask aFieldMask,

                     TLbtFireOnUpdate aFireOnUpdate,

                     TRequestStatus& aStatus ); 

        /**

         * Helper method for set triggers state operation.

         */    

         void SetTriggersStateL( 

             CLbtTriggerEntry::TLbtTriggerState aState,

             CLbtTriggerFilterBase* aFilter,

             TLbtFireOnUpdate aFireOnUpdate,

             TRequestStatus& aStatus );

        /**

         * Helper method for list trigger ids operation.

         */      

         void ListTriggerIdsL( 

             RArray < TLbtTriggerId >& aTriggerIdList,

             CLbtListTriggerOptions* aListOptions,

             TRequestStatus& aStatus );

        /**

         * Helper method for get triggers operation.

         */     

         void GetTriggersL( 

             RPointerArray < CLbtTriggerInfo >& aTriggerList,

             CLbtListTriggerOptions* aListOptions,

             TRequestStatus& aStatus );

        /**

         * Helper method for create trigger iterator operation.

         */     

         void CreateGetTriggerIteratorL( 

             CLbtListTriggerOptions* aListOptions,

             TRequestStatus& aStatus );                       

        /**

         * Helper method for get triggers operation.

         */ 

         void GetTriggersInServerL(CBufFlat* aBuf,CLbtListTriggerOptions* aListOptions,TInt& aBufLength );

        /**

         * Symbian 2nd phase construction.

         */

         void ConstructL();

     private:// data

        /**

         * Subsession pointer holder

         * Own.

         */

         CLbtSubSessnPtrHolder* iPtrHolder;

        /**

         * Pointer to client requestor.  

         * Own.

         */

         CLbtClientRequester* iClientRequester; 

        /**

         * Trigger entry state.

         */

         CLbtTriggerEntry::TLbtTriggerState iState;

        /**

         * Pointer to TLbtTriggerCreationInfo object.

         * Own.

         */

         TLbtTriggerCreationInfo* iTriggerCreationInfo;

        /**

         * Pointer to TLbtTriggerCreationInfo object.

         * Own.

         */

         TLbtTriggerUpdationInfo* iTriggerUpdationInfo; 

         /**

         * Pointer to TLbtTriggerStateInfo object.

         * Own.

         */

         TLbtTriggerStateInfo* iTriggerStateInfo;  

        /**

         * CLbtTriggerInfo pointer array.

         */

         RPointerArray<CLbtTriggerInfo> iTriggerList;

 	   /**

 		* Iterator flag.

 		*/

 		TBool iCreateIteratorFlag;        

     };

 #endif // LBT_H