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