diff -r 000000000000 -r 667063e416a2 locsrv_pub/location_triggering_api/inc/lbt.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/locsrv_pub/location_triggering_api/inc/lbt.h Tue Feb 02 01:06:48 2010 +0200 @@ -0,0 +1,1363 @@ +/* +* 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 "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: location triggering server client interface +* +*/ + + + +#ifndef LBT_H +#define LBT_H + +#include +#include +#include +#include +#include +#include +#include +#include + + +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 &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& 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(); + + /** + * Handles list triggers operation + */ + void HandleListTriggerIdsL(); + + /** + * Handles get triggers operation + */ + + void HandleGetTriggersL(); + + 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& 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 ); + + /** + * Validates geo area information based on type e.g. Coordinate, Cell, WLan, Hybrid. + * + * @panic ELbtErrArgument If invalid. + * + * @param[in] aGeoArea the geographical area + * @leave Other standard Symbian error code, such as KErrNoMemory + */ + void ValidateGeoAreaInformationL( CLbtGeoAreaBase* aGeoArea ); + + /** + * 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 iTriggerList; + + /** + * Iterator flag. + */ + TBool iCreateIteratorFlag; + }; + + +#endif // LBT_H