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@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Abstract base class for location triggering entries
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef LBTTRIGGERENTRY_H
williamr@2: #define LBTTRIGGERENTRY_H
williamr@2: 
williamr@2: #include <lbtcommon.h>
williamr@2: #include <lbs.h>
williamr@2: 
williamr@2: class CLbtTriggerConditionBase;
williamr@2: 
williamr@2: /**
williamr@2:  *  Abstract base class for location triggering entries.
williamr@2:  *
williamr@2:  *  It provides methods to determine the trigger type and to define
williamr@2:  *  basic trigger attributes. The following attributes are defined
williamr@2:  *  in location triggering entries.
williamr@2:  * 
williamr@2:  *  -  <B>Id</B> Defines the identity of a trigger. The Id is allocated 
williamr@2:  *  by Location Triggering Server and it's 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:  *  This attribute can not be modified after the trigger is created.
williamr@2:  *
williamr@2:  *  -  <B>Name</B> The name attribute defines a human-readable name for 
williamr@2:  *  the trigger. The purpose of the name attribute is mainly for the end 
williamr@2:  *  user to be able to identify the trigger in the UI. The maximum length 
williamr@2:  *  of the name is @p KLbtMaxNameLength characters. This attribute can 
williamr@2:  *  be modified after the trigger is created.
williamr@2:  *
williamr@2:  *  -  <B>State</B> This attribute specifies if the trigger is enabled 
williamr@2:  *  or disabled. A disabled trigger is not supervised by the Location 
williamr@2:  *  Triggering Server and thus will never be fired. This attribute can 
williamr@2:  *  be modified after the trigger is created. 
williamr@2:  *  
williamr@2:  *  -  <B>Requestors</B> The requestors attribute consists of a requestor stack
williamr@2:  *  with contacts and/or services using the location service. Requestor 
williamr@2:  *  information is used for privacy queries when trigger is created 
williamr@2:  *  and fired. Requestor information is not allowed to be changed
williamr@2:  *  once the trigger has been created. 
williamr@2:  *
williamr@2:  *  -  <B>Manager UI</B>. Manager UI is the UI application that can view, edit 
williamr@2:  * and delete the trigger. Manager UI application shall be provided by the user 
williamr@2:  * of this API. If it's possible, client application must specify the manager 
williamr@2:  * UI application when the trigger is created. Note, Manager UI may be different 
williamr@2:  * from the trigger's owner. Trigger's owner is the process that created the 
williamr@2:  * trigger. Triggers can be directly accessed by the Manager UI application. 
williamr@2:  * Although this attribute is not mandatory when creating a trigger. it's 
williamr@2:  * highly recommended that it is specified. It cannot be modified after the 
williamr@2:  * trigger is created.
williamr@2:  *
williamr@2:  *  -  <B>Trigger condition</B>. Trigger condition specifies in what situation
williamr@2:  *  a trigger shall be fired. Current system supports only basic trigger 
williamr@2:  *  condition. Basic trigger condition is defined by a trigger area and 
williamr@2:  *  direction of terminal's movement. Only circular area can be used as 
williamr@2:  *  trigger area in current system. This attribute can be modified after 
williamr@2:  *  the trigger is created.
williamr@2:  *
williamr@2:  *  @lib lbt.lib
williamr@2:  *  @since S60 5.1
williamr@2:  */
williamr@2: class CLbtTriggerEntry : public CBase
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * Trigger type definition. It defines the type of the trigger
williamr@2:      * entry.
williamr@2:      */
williamr@2:     enum TType
williamr@2:         {
williamr@2:         /**
williamr@2:          * Session trigger 
williamr@2:          */  
williamr@2:         ETypeSession = 1, 
williamr@2:         /**
williamr@2:          * Start-up trigger
williamr@2:          */
williamr@2:         ETypeStartup = 2
williamr@2:         };
williamr@2:         
williamr@2:     /**
williamr@2:      * Trigger attributes identifications. 
williamr@2:      *
williamr@2:      * These ids can be combined and used to form an attribute mask when
williamr@2:      * retrieving partial attributes from Location Triggering Server.
williamr@2:      */
williamr@2:     enum TAttribute
williamr@2:         {
williamr@2:         /**
williamr@2:          * Trigger Id
williamr@2:          */
williamr@2:         EAttributeId = 0x0001, 
williamr@2:         /**
williamr@2:          * Trigger name
williamr@2:          */
williamr@2:         EAttributeName = 0x0002, 
williamr@2:         /**
williamr@2:          * Trigger state
williamr@2:          */
williamr@2:         EAttributeState = 0x0004, 
williamr@2:         /**
williamr@2:          * Trigger requestor
williamr@2:          */
williamr@2:         EAttributeRequestor = 0x0008, 
williamr@2:         /**
williamr@2:          * Trigger manager UI
williamr@2:          */
williamr@2:         EAttributeManagerUi = 0x0010, 
williamr@2:         /**
williamr@2:          * Trigger rearm time
williamr@2:          */
williamr@2:         EAttributeRearmTime = 0x0020, 
williamr@2:         /**
williamr@2:          * Trigger condition
williamr@2:          */
williamr@2:         EAttributeCondition = 0x0080,
williamr@2:         /**
williamr@2:          * Process ID of start-up trigger. It includes
williamr@2:          * process executable name and process UID type.
williamr@2:          */
williamr@2:         EAttributeStartUpProcessId = 0x0100,
williamr@2:         /**
williamr@2:          * Command-line argument string for start-up trigger
williamr@2:          */
williamr@2:         EAttributeStartUpCommandLine = 0x0200,
williamr@2: 
williamr@2:         };
williamr@2: 
williamr@2: 
williamr@2:     /**
williamr@2:      * Specifies the state of a trigger.
williamr@2:      */
williamr@2:     enum TLbtTriggerState
williamr@2:         {
williamr@2:         /** 
williamr@2:          * The trigger is enabled
williamr@2:          */ 
williamr@2:         EStateEnabled = 1,    
williamr@2:         /**
williamr@2:          * The trigger is disabled
williamr@2:          */
williamr@2:         EStateDisabled = 2     
williamr@2:         };
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor
williamr@2:      */
williamr@2:     IMPORT_C virtual ~CLbtTriggerEntry();
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the type of the trigger.
williamr@2:      *
williamr@2:      * @return The type of trigger entry.
williamr@2:      */
williamr@2:     IMPORT_C virtual TType Type() const = 0;
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the trigger ID.
williamr@2:      *
williamr@2:      * The ID is allocated and set by the Location Triggering Server when a
williamr@2:      * trigger is successfully created. Trigger ID is unique in the system.
williamr@2:      * This function returns @p KLbtNullTriggerId if the ID is not 
williamr@2:      * set before.
williamr@2:      *
williamr@2:      * @return The ID of the trigger entry, or @p KLbtNullTriggerId if the
williamr@2:      *   trigger ID has not been set.
williamr@2:      */
williamr@2:     IMPORT_C const TLbtTriggerId& Id() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets trigger entry id. SetId is not used during trigger creation as it 
williamr@2:      * is auto generated by the LBT server. This information is only used during 
williamr@2:      * deletion / modification of triggers. This information when specified 
williamr@2:      * during trigger creation, will be ignored by LBT server. 
williamr@2:      *
williamr@2:      * @param[in] aId The ID of the trigger entry, or @p KLbtNullTriggerId. 
williamr@2:      */
williamr@2:     IMPORT_C void SetId( TLbtTriggerId aId );
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the name of the trigger entry.
williamr@2:      * 
williamr@2:      * If the name is not set, an empty string is returned. Maximum 
williamr@2:      * length of the name is @p KLbtMaxNameLength.
williamr@2:      *
williamr@2:      * @return The name of the trigger entry.
williamr@2:      */
williamr@2:     IMPORT_C const TDesC& Name() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the name of the trigger entry. 
williamr@2:      *
williamr@2:      * @param[in] aName The name of the trigger entry.
williamr@2:      * @leave KErrArgument If the name of the trigger is longer than
williamr@2:      *   @p KLbtMaxNameLength.
williamr@2:      */
williamr@2:     IMPORT_C void SetNameL( const TDesC& aName );
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the rearm time interval.
williamr@2:      *
williamr@2:      * If no interval is specified for the trigger, this function
williamr@2:      * returns
williamr@2:      * @p KLbtDefaultTimeToRearm which is 600s or 10 minutes.
williamr@2:      *
williamr@2:      * @return Rearm time interval.
williamr@2:      */
williamr@2:     IMPORT_C TInt TimeToRearm() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the time interval to reactivate the trigger after the
williamr@2:      * trigger is fired.
williamr@2:      *
williamr@2:      * @param[in] aSeconds The time interval after which the trigger
williamr@2:      * is set effective by the Location Triggering Server. Client
williamr@2:      * applications can set 0 to indicate no delay, in which case
williamr@2:      * the trigger will remain effective through out its life span.
williamr@2:      * Range is 0 (KLbtMinTimeToRearm) to +2147483647 (KLbtMaxTimeToRearm) 
williamr@2:      * which is +24855 days (approximately 68 years)
williamr@2:      * @panic KErrArgument If the time set is out of range.
williamr@2:      */
williamr@2:     IMPORT_C void SetTimeToRearm( TInt aSeconds );
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets trigger entry state.
williamr@2:      *
williamr@2:      * If no state has been set for the trigger, this function returns
williamr@2:      * @p ELbtTriggerEnabled.
williamr@2:      *
williamr@2:      * @return The trigger entry state.
williamr@2:      */
williamr@2:     IMPORT_C TLbtTriggerState State() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the trigger entry state.
williamr@2:      *
williamr@2:      * @param[in] aState The trigger entry state.
williamr@2:      */
williamr@2:     IMPORT_C void SetState( TLbtTriggerState aState );
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets requestors of the trigger entry.
williamr@2:      * 
williamr@2:      * Requestor information is used by the Location Triggering Server to
williamr@2:      * verify that the user allows location information to be sent to 
williamr@2:      * the specified requestors when a trigger fires.
williamr@2:      *
williamr@2:      * Requestors attribute is a mandatory trigger attribute. If the requestors
williamr@2:      * attribute is not set when the trigger is created in the server, the
williamr@2:      * trigger creation will fail.
williamr@2:      *
williamr@2:      * If requestors have not been set before, this function returns
williamr@2:      * an empty requestor stack.
williamr@2:      *
williamr@2:      * Refer to Location Acquisition API for detailed information on 
williamr@2:      * requestors.
williamr@2:      *
williamr@2:      * @see RLbt::CreateTriggerL()
williamr@2:      * @see RRequestorStack
williamr@2:      *
williamr@2:      * @param[out] aRequestors The requestors of the trigger entry.
williamr@2:      */
williamr@2:     IMPORT_C void GetRequestorsL( RRequestorStack& aRequestors ) const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets requestors of trigger entry.
williamr@2:      *
williamr@2:      * Requestor information is used by the Location Triggering Server to
williamr@2:      * verify that the user allows location information to be sent to 
williamr@2:      * the specified requestors when a trigger fires.
williamr@2:      *
williamr@2:      * Requestors attribute is a mandatory trigger attribute. If the requestors
williamr@2:      * attribute is not set when the trigger is created in the server, the
williamr@2:      * trigger creation will fail.
williamr@2:      *
williamr@2:      * Refer to Location Acquisition API for detailed information on 
williamr@2:      * requestors.
williamr@2:      *
williamr@2:      * @see RLbt::CreateTriggerL()
williamr@2:      *
williamr@2:      * @param[in] aRequestors The requestors of trigger entry.
williamr@2:      * @leave KErrArgument The stack contains no requestors.
williamr@2:      */
williamr@2:     IMPORT_C void SetRequestorsL( const RRequestorStack& aRequestors );
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets requestor of trigger entry.
williamr@2:      *
williamr@2:      * Requestor information is used by the Location Triggering Server to
williamr@2:      * verify that the user allows information to be sent to the specified
williamr@2:      * requestors when a trigger fires.
williamr@2:      *
williamr@2:      * Requestors attribute is a mandatory trigger attribute. If the requestors
williamr@2:      * attribute is not set when the trigger is created in the server, the
williamr@2:      * trigger creation will fail.
williamr@2:      *
williamr@2:      * @see RLbt::CreateTriggerL()
williamr@2:      *
williamr@2:      * @param[in] aType identifies the type of requestor, a service or a contact.
williamr@2:      * @param[in] aFormat determines the type of data held in aData
williamr@2:      * @param[in] aData is requestor data. Can be a telephone number, a URL etc.
williamr@2:      */
williamr@2:     IMPORT_C void SetRequestorL( 
williamr@2:         CRequestor::TRequestorType aType,
williamr@2:         CRequestor::TRequestorFormat aFormat,
williamr@2:         const TDesC& aData );
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets UID of the manager UI. The UID means 
williamr@2:      * the UID3 value, which identifies the particular application. 
williamr@2:      * If the UID of the manager UI is not set, this function 
williamr@2:      * returns KNullUid. 
williamr@2:      *
williamr@2:      * @return The UID of manager UI application. KNullUid if the UID
williamr@2:      * has not been set.
williamr@2:      */
williamr@2:     IMPORT_C TUid ManagerUi() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets UID of the manager UI.
williamr@2:      * 
williamr@2:      * @param[in] aUid The SID value if available. Else the UID3 value, which is 
williamr@2:      * the idenfifier of the particaular application. KNullUid can be used to 
williamr@2:      * remove previous setting.
williamr@2:      */
williamr@2:     IMPORT_C void SetManagerUi( TUid aUid );
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the trigger condition.
williamr@2:      *
williamr@2:      * The ownership of the returned trigger condition object is 
williamr@2:      * not transferred to the client. The pointer can be 
williamr@2:      * used to modify the trigger condition.
williamr@2:      *
williamr@2:      * @return A non-const pointer to the trigger's 
williamr@2:      * trigger condition. NULL if the trigger condition is not set. 
williamr@2:      */
williamr@2:     IMPORT_C CLbtTriggerConditionBase* GetCondition();
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the trigger condition.
williamr@2:      * 
williamr@2:      * The ownership of the returned trigger condition object is 
williamr@2:      * not transferred to the client. The pointer can be 
williamr@2:      * used to modify the trigger condition.
williamr@2:      *
williamr@2:      * @return A const pointer to the trigger's 
williamr@2:      * trigger condition. NULL if the trigger condition is not set. 
williamr@2:      */
williamr@2:     IMPORT_C const CLbtTriggerConditionBase* GetCondition() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets trigger condition.
williamr@2:      *
williamr@2:      * This object takes the ownership of the trigger condition object.
williamr@2:      * 
williamr@2:      * @param[in] aCondition Pointer to the new trigger condition object.
williamr@2:      * This object takes the ownership of aCondition. NULL can be used
williamr@2:      * to remove previous setting. 
williamr@2:      */
williamr@2:     IMPORT_C void SetCondition( CLbtTriggerConditionBase* aCondition );
williamr@2: 
williamr@2:     /**
williamr@2:      * Internalizes the trigger object's details and attributes 
williamr@2:      * from stream.
williamr@2:      *
williamr@2:      * The presence of this function means that the standard template 
williamr@2:      * operator>>() ( defined in s32strm.h ) is available to internalize objects 
williamr@2:      * of this class.
williamr@2:      *
williamr@2:      * @param[in] aStream Stream from which the object should be internalized.
williamr@2:      */
williamr@2:     IMPORT_C void InternalizeL( RReadStream& aStream );
williamr@2:     
williamr@2:     /**
williamr@2:      * Externalizes the trigger object's details and attributes
williamr@2:      * to stream.
williamr@2:      *
williamr@2:      * The presence of this function means that the standard template 
williamr@2:      * operator<<() ( defined in s32strm.h ) is available to externalize objects 
williamr@2:      * of this class.
williamr@2:      *
williamr@2:      * @param[in] aStream Stream to which the object should be externalized.
williamr@2:      */
williamr@2:     IMPORT_C void ExternalizeL( RWriteStream& aStream ) const;
williamr@2:    
williamr@2: protected:
williamr@2:     /**
williamr@2:      * Internalize method that subclass must implement.
williamr@2:      * @param[in] aStream Stream from which the object should be internalized.
williamr@2:      */
williamr@2:     virtual void DoInternalizeL( RReadStream& aStream ) = 0;
williamr@2:     
williamr@2:     /**
williamr@2:      * Externalize method that subclass must implement.
williamr@2:      * @param[in] aStream Stream to which the object should be externalized.
williamr@2:      */
williamr@2:     virtual void DoExternalizeL( RWriteStream& aStream ) const = 0;
williamr@2:     
williamr@2:     /**
williamr@2:      * Constructor.
williamr@2:      */
williamr@2:     CLbtTriggerEntry();
williamr@2: 
williamr@2: private:
williamr@2:     /**
williamr@2:      * By default, prohibit copy constructor
williamr@2:      */
williamr@2:     CLbtTriggerEntry( const CLbtTriggerEntry& );
williamr@2:     
williamr@2:     /**
williamr@2:      * Prohibit assigment operator
williamr@2:      */
williamr@2:     CLbtTriggerEntry& operator= ( const CLbtTriggerEntry& );
williamr@2: 
williamr@2: private: //data
williamr@2:     /**
williamr@2:      * Id
williamr@2:      */
williamr@2:     TLbtTriggerId iId;
williamr@2:     
williamr@2:     /**
williamr@2:      * Name
williamr@2:      */
williamr@2:     HBufC* iName;
williamr@2:     
williamr@2:     /**
williamr@2:      * State
williamr@2:      */
williamr@2:     TLbtTriggerState iState; 
williamr@2:     
williamr@2:     /**
williamr@2:      * Rearm time
williamr@2:      */
williamr@2:     TInt iRearmTime;
williamr@2:     
williamr@2:     /**
williamr@2:      * Requestors
williamr@2:      */
williamr@2:     RRequestorStack iRequestor;
williamr@2:     
williamr@2:     /**
williamr@2:      * manager UI
williamr@2:      */
williamr@2:     TUid iManagerUi;
williamr@2:     
williamr@2:     /**
williamr@2:      * Trigger condition
williamr@2:      */
williamr@2:     CLbtTriggerConditionBase* iTriggerCondition;
williamr@2:     
williamr@2:     /**
williamr@2:      * Reserved for schedule information
williamr@2:      */
williamr@2:     TAny* iSchedule; 
williamr@2:     
williamr@2:     /**
williamr@2:      * Reserved pointer for future extension
williamr@2:      */
williamr@2:     TAny* iReserved;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: #endif // LBTTRIGGERENTRY_H