/*

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

#include <lbs.h>

#include <lbtserver.h>

#include <lbttriggerentry.h>

#include <lbtcommon.h>

#include <lbttriggerchangeevent.h>

#include <lbttriggeringsystemsettings.h>

#include <lbtlisttriggeroptions.h>

class CLbtTriggerEntry;

class CLbtTriggerFilterBase;

class CLbtListTriggerOptions;

class CLbtTriggerInfo;

class CLbtClientRequester;

class CLbtSubSessnPtrHolder;

struct TLbtTriggerCreationInfo;

struct TLbtTriggerUpdationInfo;

struct TLbtTriggerStateInfo;

/**

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

 * methods to use location triggering service from Location Triggering 

 * Server.

 * 

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

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

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

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

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

 * firing event. It also provides method for getting

 * location triggering related system settings. 

 * 

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

 * Server must first be made.

 *

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

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

 * Triggers created from one subsession can be accessed from other 

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

 * firing event and triggering system settings change event are 

 * send to all subsessions that have issued notification

 * requests to Location Triggering Server.

 *

 * Client must not issue a notification request while there is 

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

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

 * to the following functions.

 * 

 * - NotifyTriggerChangeEvent

 * - NotifyTriggerFired

 * - NotifyTriggeringSystemSettingChange

 *

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

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

 *

 * @see RLbtServer

 * 

 * @lib lbt.lib

 *

 * @since S60 5.1

 */

class RLbt : public RSubSessionBase

    {

    public:

       /**

        * Opens a subsession with Location Triggering Server.

        *

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

        * 

        * @panic LocTriggering ELbtServerBadHandle If a session to Location 

        * Triggering Server has not been connected.

        *

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

        * session.

        *

        * @return KErrNone if successful. Otherwise, Symbian standard 

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

        */

        IMPORT_C TInt Open( RLbtServer& aServer );

       /**

        * Connect and open a subsession with Location Triggering Server.

        *

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

        * Triggering Server. Client application shall avoid unnecesary

        * session connection to Location Triggering Server. Whenever

        * possible, client applicaiton shall reuse same session to

        * open a subsession. 

        *

        * @panic LocTriggering ELbtServerBadHandle If a session to Location 

        * Triggering Server has not been connected.

        *

        * @return KErrNone if successful. Otherwise, Symbian standard 

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

        */

        IMPORT_C TInt Open();

       /**

        * Closes the subsession with Location Triggering Server.

        *

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

        * 

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

        * that all outstanding notification requests have been cancelled. In

        * particular, the application must issue all the appropriate Cancel 

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

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

        *

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

        * the client application are deleted by Location Triggering Server. 

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

        * 

        * @panic LocTriggering ELbtRequestsNotCancelled If client application 

        * has requests outstanding with Location Triggering Server.

        */

        IMPORT_C void Close();

       /**

        * Creates a trigger in Location Triggering Server and returns the 

        * trigger Id.

        *

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

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

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

        *

        * Trigger entry shall be a subclass of CLbtTriggerEntry.

        *

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

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

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

        * closed. 

        *

        * While creating a trigger, the following attributes are mandatory 

        * for any type of trigger,

        * - Name

        * - Requestors

        * - Trigger condition

        *

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

        * also mandatory

        * - Process Identity

        *

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

        * recommended that correct manager UI is specified. 

        *

        * Currently, the system only supports CLbtTriggerConditionArea

        * to be used as trigger condition. Following 

        * attributes must be specified,

        * - Trigger area 

        * - Direction

        *

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

        * center of the geographical circle must be specified. 

        * 

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

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

        * 

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

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

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

        * Server will supervise the trigger and fires it when trigger 

        * conditions are met.

        *

        * Creating any type triggers requires @p Location capability. 

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

        * triggers. 

        *

        * @see CLbtTriggerEntry CLbtSessionTrigger CLbtStartupTrigger

        * @see CancelCreateTrigger

        *

        * @panic LocTriggering ELbtServerBadHandle If the subsession is 

        * not opened.

        *

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

        * is ignored by Location Triggering Server.

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

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

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

        * its Id may be reused by another trigger.

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

        * can be fired right after the creation. 

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

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

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

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

        * fired right after it is created. 

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

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

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

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

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

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

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

        * area and then  moves out again. 

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

        * request is completed.

        * - KErrNone. If the trigger is created successfully.

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

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

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

        * @p KLbtMaxNameLength.

        * - KErrNotSupported. If the trigger condition is not 

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

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

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

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

        * checking by Location Server determines that any of the specified 

        * requestors do not have permission to retrieve location information, 

        * - KErrPermisionDenied. If the client application does not have 

        * enough capabilities to create this trigger.

        * - KErrTriggeringAreaTooSmall.  If the specified trigger area is 

        * smaller than minimum size of trigger area.

        * - KErrLbtMaxTriggerLimitExceeded. If creating startup trigger exceeds

        * the system defined limit.

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

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

        * KErrServerBusy, KErrGeneral. If the operation fails. 

        */

        IMPORT_C void CreateTrigger( 

            const CLbtTriggerEntry& aTrigger,

            TLbtTriggerId& aTriggerId,

            TBool aFireOnCreation,

            TRequestStatus& aStatus );

       /**

        * Cancel trigger creation.

        *

        * This function does not require any capabilities. 

        *

        * @see CreateTriggerL

        */

        IMPORT_C void CancelCreateTrigger();

       /**

        * Deletes a specific trigger from Location Triggering Server.

        * 

        * Client applications can only delete triggers owned by it. 

        *

        * Deleting any type triggers requires @p Location capability. 

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

        * triggers. 

        *

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

        *

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

        *

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

        * it is not owned by the client application.

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

        * trigger is not completed yet.

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

        * KErrServerBusy, KErrGeneral, etc.

        */

        IMPORT_C void DeleteTriggerL( TLbtTriggerId aId );

       /**

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

        * the specified criteria. 

        *

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

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

        *

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

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

        * client application would be deleted and the method would complete 

        * without any leave.

        * 

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

        * application are deleted.

        *

        * Deleting any type triggers requires @p Location capability. 

        * @p WriteUserData capability is required in addition to delete 

        * start-up triggers. 

        * 

        * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

        * opened.

        *

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

        * Trigger entries that fulfill the criteria will be deleted 

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

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

        * will be deleted.

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

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

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

        * fullfills the criteria specified.

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

        * KErrServerBusy, KErrGeneral, etc.

        */

        IMPORT_C void DeleteTriggersL( 

            CLbtTriggerFilterBase* aFilter = NULL );

       /**

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

        * by the client application and fulfill the specified criteria.

        *

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

        * specified criteria, the method completes the client request

        * with KErrNotFound.

        *

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

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

        * client application would be deleted and the method would complete 

        * without any error.

        *

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

        * application are deleted.

        *

        * Deleting any type triggers requires @p Location capability. 

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

        * triggers. 

        * 

        * @panic LocTriggering ELbtServerBadHandle If the subsession is not

        * opened.

        *

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

        * request is completed.

        * - KErrNone If the operation was successful.

        * - KErrNotFound If no trigger belonging to the client application

        * fullfills the criteria specified.

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

        * KErrServerBusy, KErrGeneral, etc.

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

        * Trigger entries that fulfill the criteria will be deleted 

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

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

        */

        IMPORT_C void DeleteTriggers( 

            TRequestStatus& aStatus, 

            CLbtTriggerFilterBase* aFilter = NULL );

       /**

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

        * be deleted must be owned by the client application. 

        *

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

        * application then no triggers would be deleted and this method 

        * will leave with KErrNotFound.

        *

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

        * completes without any leave. 

        * 

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

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

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

        * method will complete without any leave in this case.

        * 

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

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

        * triggers. 

        * 

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

        *

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

        * that are to be deleted. 

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

        * KErrServerBusy, KErrGeneral, etc.

        */

        IMPORT_C void DeleteTriggersL( 

            const RArray<TLbtTriggerId> &aTriggerIdList );

       /**

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

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

        *

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

        * application then no triggers would be deleted and this method 

        * will complete the request with KErrNotFound.

        * 

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

        * completes without any error code.

        * 

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

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

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

        * method will complete without any leave in this case.

        *

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

        * @p WriteUserData capability is required in addition to delete 

        * start-up triggers. 

        * 

        * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

        * opened.

        *

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

        * that are to be deleted. 

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

        * request is completed.

        * - KErrNone If the operation was succeed.

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

        * KErrServerBusy, KErrGeneral, etc.

        */

        IMPORT_C void DeleteTriggers( 

            const RArray<TLbtTriggerId>& aTriggerIdList,

            TRequestStatus& aStatus );

       /**

        * Cancel delete triggers operation.

        *

        * This function does not require any capabilities. 

        *

        * @see DeleteTriggers

        */

        IMPORT_C void CancelDeleteTriggers();     

       /**

        * Gets the specified trigger from Location Triggering Server. 

        * 

        * Client application takes the ownership ofthe returned trigger object.

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

        * trigger entry is successfully retrieved.

        *

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

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

        * client applications can retrieve trigger object with only partial 

        * attributes filled. 

        *

        * This method requires @p Location capability. 

        *

        * @panic LocTriggering ELbtServerBadHandle If the subsession is not 

        * opened.

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

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

        * It specifies what attributes shall be filled in the returned 

        * trigger object. The default value is KLbtTriggerAttributeFieldsAll, 

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

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

        * trigger object always contains a valid trigger Id.

        * @param[in] aDynInfoFieldMask Specifies which dynamic information

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

        * KLbtTriggerDynInfoFieldsAll, which means all dynamic information

        * fields will be filled.

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

        * transferred to the client application.

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

        * not owned by the client application.

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

        * KErrServerBusy, KErrGeneral, etc.

        */

        IMPORT_C CLbtTriggerInfo* GetTriggerLC( 

            TLbtTriggerId aId,

            TLbtTriggerAttributeFieldsMask aEntryFieldMask = 

                KLbtTriggerAttributeFieldsAll,

            TLbtTriggerDynamicInfoFieldsMask  aDynInfoFieldMask = 

                KLbtTriggerDynInfoFieldsAll );

       /**

        * Changes the attributes of the specified trigger.

        *

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

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

        * only update triggers owned by itself.

        *

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

        * to change the following attributes will generate a leave with 

        * error code KErrAccessDenied.

        * 

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

        * modified after the trigger is created.

        * - ID

        * - Requestor

        * - Manager UI

        *

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

        * start-up triggers.

        * - Trigger handling process identity

        * - Trigger handling process SID

        *

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

        * the method leaves with KErrNotFound.

        *

        * Updating any type triggers requires @p Location capability. 

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

        * triggers. 

        *

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

        *

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

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

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

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

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

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

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

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

        * can be fired right after the update operation. 

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

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

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

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

        * fired right after it is updated. 

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

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

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

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

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

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

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

        * area and then  moves out again. 

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

        * not owned by the client application.

        * @leave KErrAccessDenied If the client application tries to change 

        * the attributes which are not modifiable.

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