/*

* 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:  Abstract base class for location triggering entries

*

*/

#ifndef LBTTRIGGERENTRY_H

#define LBTTRIGGERENTRY_H

#include <lbtcommon.h>

#include <lbs.h>

class CLbtTriggerConditionBase;

/**

 *  Abstract base class for location triggering entries.

 *

 *  It provides methods to determine the trigger type and to define

 *  basic trigger attributes. The following attributes are defined

 *  in location triggering entries.

 * 

 *  -  <B>Id</B> Defines the identity of a trigger. The Id is allocated 

 *  by Location Triggering Server and it's 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. 

 *  This attribute can not be modified after the trigger is created.

 *

 *  -  <B>Name</B> The name attribute defines a human-readable name for 

 *  the trigger. The purpose of the name attribute is mainly for the end 

 *  user to be able to identify the trigger in the UI. The maximum length 

 *  of the name is @p KLbtMaxNameLength characters. This attribute can 

 *  be modified after the trigger is created.

 *

 *  -  <B>State</B> This attribute specifies if the trigger is enabled 

 *  or disabled. A disabled trigger is not supervised by the Location 

 *  Triggering Server and thus will never be fired. This attribute can 

 *  be modified after the trigger is created. 

 *  

 *  -  <B>Requestors</B> The requestors attribute consists of a requestor stack

 *  with contacts and/or services using the location service. Requestor 

 *  information is used for privacy queries when trigger is created 

 *  and fired. Requestor information is not allowed to be changed

 *  once the trigger has been created. 

 *

 *  -  <B>Manager UI</B>. Manager UI is the UI application that can view, edit 

 * and delete the trigger. Manager UI application shall be provided by the user 

 * of this API. If it's possible, client application must specify the manager 

 * UI application when the trigger is created. Note, Manager UI may be different 

 * from the trigger's owner. Trigger's owner is the process that created the 

 * trigger. Triggers can be directly accessed by the Manager UI application. 

 * Although this attribute is not mandatory when creating a trigger. it's 

 * highly recommended that it is specified. It cannot be modified after the 

 * trigger is created.

 *

 *  -  <B>Trigger condition</B>. Trigger condition specifies in what situation

 *  a trigger shall be fired. Current system supports only basic trigger 

 *  condition. Basic trigger condition is defined by a trigger area and 

 *  direction of terminal's movement. Only circular area can be used as 

 *  trigger area in current system. This attribute can be modified after 

 *  the trigger is created.

 *

 *  @lib lbt.lib

 *  @since S60 5.1

 */

class CLbtTriggerEntry : public CBase

    {

public:

    /**

     * Trigger type definition. It defines the type of the trigger

     * entry.

     */

    enum TType

        {

        /**

         * Session trigger 

         */  

        ETypeSession = 1, 

        /**

         * Start-up trigger

         */

        ETypeStartup = 2

        };

    /**

     * Trigger attributes identifications. 

     *

     * These ids can be combined and used to form an attribute mask when

     * retrieving partial attributes from Location Triggering Server.

     */

    enum TAttribute

        {

        /**

         * Trigger Id

         */

        EAttributeId = 0x0001, 

        /**

         * Trigger name

         */

        EAttributeName = 0x0002, 

        /**

         * Trigger state

         */

        EAttributeState = 0x0004, 

        /**

         * Trigger requestor

         */

        EAttributeRequestor = 0x0008, 

        /**

         * Trigger manager UI

         */

        EAttributeManagerUi = 0x0010, 

        /**

         * Trigger rearm time

         */

        EAttributeRearmTime = 0x0020, 

        /**

         * Trigger condition

         */

        EAttributeCondition = 0x0080,

        /**

         * Process ID of start-up trigger. It includes

         * process executable name and process UID type.

         */

        EAttributeStartUpProcessId = 0x0100,

        /**

         * Command-line argument string for start-up trigger

         */

        EAttributeStartUpCommandLine = 0x0200,

        };

    /**

     * Specifies the state of a trigger.

     */

    enum TLbtTriggerState

        {

        /** 

         * The trigger is enabled

         */ 

        EStateEnabled = 1,    

        /**

         * The trigger is disabled

         */

        EStateDisabled = 2     

        };

    /**

     * Destructor

     */

    IMPORT_C virtual ~CLbtTriggerEntry();

    /**

     * Gets the type of the trigger.

     *

     * @return The type of trigger entry.

     */

    IMPORT_C virtual TType Type() const = 0;

    /**

     * Gets the trigger ID.

     *

     * The ID is allocated and set by the Location Triggering Server when a

     * trigger is successfully created. Trigger ID is unique in the system.

     * This function returns @p KLbtNullTriggerId if the ID is not 

     * set before.

     *

     * @return The ID of the trigger entry, or @p KLbtNullTriggerId if the

     *   trigger ID has not been set.

     */

    IMPORT_C const TLbtTriggerId& Id() const;

    /**

     * Sets trigger entry id. SetId is not used during trigger creation as it 

     * is auto generated by the LBT server. This information is only used during 

     * deletion / modification of triggers. This information when specified 

     * during trigger creation, will be ignored by LBT server. 

     *

     * @param[in] aId The ID of the trigger entry, or @p KLbtNullTriggerId. 

     */

    IMPORT_C void SetId( TLbtTriggerId aId );

    /**

     * Gets the name of the trigger entry.

     * 

     * If the name is not set, an empty string is returned. Maximum 

     * length of the name is @p KLbtMaxNameLength.

     *

     * @return The name of the trigger entry.

     */

    IMPORT_C const TDesC& Name() const;

    /**

     * Sets the name of the trigger entry. 

     *

     * @param[in] aName The name of the trigger entry.

     * @leave KErrArgument If the name of the trigger is longer than

     *   @p KLbtMaxNameLength.

     */

    IMPORT_C void SetNameL( const TDesC& aName );

    /**

     * Gets the rearm time interval.

     *

     * If no interval is specified for the trigger, this function

     * returns

     * @p KLbtDefaultTimeToRearm which is 600s or 10 minutes.

     *

     * @return Rearm time interval.

     */

    IMPORT_C TInt TimeToRearm() const;

    /**

     * Sets the time interval to reactivate the trigger after the

     * trigger is fired.

     *

     * @param[in] aSeconds The time interval after which the trigger

     * is set effective by the Location Triggering Server. Client

     * applications can set 0 to indicate no delay, in which case

     * the trigger will remain effective through out its life span.

     * Range is 0 (KLbtMinTimeToRearm) to +2147483647 (KLbtMaxTimeToRearm) 

     * which is +24855 days (approximately 68 years)

     * @panic KErrArgument If the time set is out of range.

     */

    IMPORT_C void SetTimeToRearm( TInt aSeconds );

    /**

     * Gets trigger entry state.

     *

     * If no state has been set for the trigger, this function returns

     * @p ELbtTriggerEnabled.

     *

     * @return The trigger entry state.

     */

    IMPORT_C TLbtTriggerState State() const;

    /**

     * Sets the trigger entry state.

     *

     * @param[in] aState The trigger entry state.

     */

    IMPORT_C void SetState( TLbtTriggerState aState );

    /**

     * Gets requestors of the trigger entry.

     * 

     * Requestor information is used by the Location Triggering Server to

     * verify that the user allows location information to be sent to 

     * the specified requestors when a trigger fires.

     *

     * Requestors attribute is a mandatory trigger attribute. If the requestors

     * attribute is not set when the trigger is created in the server, the

     * trigger creation will fail.

     *

     * If requestors have not been set before, this function returns

     * an empty requestor stack.

     *

     * Refer to Location Acquisition API for detailed information on 

     * requestors.

     *

     * @see RLbt::CreateTriggerL()

     * @see RRequestorStack

     *

     * @param[out] aRequestors The requestors of the trigger entry.

     */

    IMPORT_C void GetRequestorsL( RRequestorStack& aRequestors ) const;

    /**

     * Sets requestors of trigger entry.

     *

     * Requestor information is used by the Location Triggering Server to

     * verify that the user allows location information to be sent to 

     * the specified requestors when a trigger fires.

     *

     * Requestors attribute is a mandatory trigger attribute. If the requestors

     * attribute is not set when the trigger is created in the server, the

     * trigger creation will fail.

     *

     * Refer to Location Acquisition API for detailed information on 

     * requestors.

     *

     * @see RLbt::CreateTriggerL()

     *

     * @param[in] aRequestors The requestors of trigger entry.

     * @leave KErrArgument The stack contains no requestors.

     */

    IMPORT_C void SetRequestorsL( const RRequestorStack& aRequestors );

    /**

     * Sets requestor of trigger entry.

     *

     * Requestor information is used by the Location Triggering Server to

     * verify that the user allows information to be sent to the specified

     * requestors when a trigger fires.

     *

     * Requestors attribute is a mandatory trigger attribute. If the requestors

     * attribute is not set when the trigger is created in the server, the

     * trigger creation will fail.

     *

     * @see RLbt::CreateTriggerL()

     *

     * @param[in] aType identifies the type of requestor, a service or a contact.

     * @param[in] aFormat determines the type of data held in aData

     * @param[in] aData is requestor data. Can be a telephone number, a URL etc.

     */

    IMPORT_C void SetRequestorL( 

        CRequestor::TRequestorType aType,

        CRequestor::TRequestorFormat aFormat,

        const TDesC& aData );

    /**

     * Gets UID of the manager UI. The UID means 

     * the UID3 value, which identifies the particular application. 

     * If the UID of the manager UI is not set, this function 

     * returns KNullUid. 

     *

     * @return The UID of manager UI application. KNullUid if the UID

     * has not been set.

     */

    IMPORT_C TUid ManagerUi() const;

    /**

     * Sets UID of the manager UI.

     * 

     * @param[in] aUid The SID value if available. Else the UID3 value, which is 

     * the idenfifier of the particaular application. KNullUid can be used to 

     * remove previous setting.

     */

    IMPORT_C void SetManagerUi( TUid aUid );

    /**

     * Gets the trigger condition.

     *

     * The ownership of the returned trigger condition object is 

     * not transferred to the client. The pointer can be 

     * used to modify the trigger condition.

     *

     * @return A non-const pointer to the trigger's 

     * trigger condition. NULL if the trigger condition is not set. 

     */

    IMPORT_C CLbtTriggerConditionBase* GetCondition();

    /**

     * Gets the trigger condition.

     * 

     * The ownership of the returned trigger condition object is 

     * not transferred to the client. The pointer can be 

     * used to modify the trigger condition.

     *

     * @return A const pointer to the trigger's 

     * trigger condition. NULL if the trigger condition is not set. 

     */

    IMPORT_C const CLbtTriggerConditionBase* GetCondition() const;

    /**

     * Sets trigger condition.

     *

     * This object takes the ownership of the trigger condition object.

     * 

     * @param[in] aCondition Pointer to the new trigger condition object.

     * This object takes the ownership of aCondition. NULL can be used

     * to remove previous setting. 

     */

    IMPORT_C void SetCondition( CLbtTriggerConditionBase* aCondition );

    /**

     * Internalizes the trigger object's details and attributes 

     * from stream.

     *

     * The presence of this function means that the standard template 

     * operator>>() ( defined in s32strm.h ) is available to internalize objects 

     * of this class.

     *

     * @param[in] aStream Stream from which the object should be internalized.

     */

    IMPORT_C void InternalizeL( RReadStream& aStream );

    /**

     * Externalizes the trigger object's details and attributes

     * to stream.

     *

     * The presence of this function means that the standard template 

     * operator<<() ( defined in s32strm.h ) is available to externalize objects 

     * of this class.

     *

     * @param[in] aStream Stream to which the object should be externalized.

     */

    IMPORT_C void ExternalizeL( RWriteStream& aStream ) const;

protected:

    /**

     * Internalize method that subclass must implement.

     * @param[in] aStream Stream from which the object should be internalized.

     */

    virtual void DoInternalizeL( RReadStream& aStream ) = 0;

    /**

     * Externalize method that subclass must implement.

     * @param[in] aStream Stream to which the object should be externalized.

     */

    virtual void DoExternalizeL( RWriteStream& aStream ) const = 0;

    /**

     * Constructor.

     */

    CLbtTriggerEntry();

private:

    /**

     * By default, prohibit copy constructor

     */

    CLbtTriggerEntry( const CLbtTriggerEntry& );

    /**

     * Prohibit assigment operator

     */

    CLbtTriggerEntry& operator= ( const CLbtTriggerEntry& );

private: //data

    /**

     * Id

     */

    TLbtTriggerId iId;

    /**

     * Name

     */

    HBufC* iName;

    /**

     * State

     */

    TLbtTriggerState iState; 

    /**

     * Rearm time

     */

    TInt iRearmTime;

    /**

     * Requestors

     */

    RRequestorStack iRequestor;

    /**

     * manager UI

     */

    TUid iManagerUi;

    /**

     * Trigger condition

     */

    CLbtTriggerConditionBase* iTriggerCondition;

    /**

     * Reserved for schedule information

     */

    TAny* iSchedule; 

    /**

     * Reserved pointer for future extension

     */

    TAny* iReserved;

    };

#endif // LBTTRIGGERENTRY_H