/*
* 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: This header file describes the triggering container interface
*
*/
#ifndef C_LBTCONTAINER_H
#define C_LBTCONTAINER_H
#include <e32base.h>
#include <lbttriggerfiltercomposite.h>
#include <lbttriggerdynamicinfo.h>
#include <lbtlisttriggeroptions.h>
#include "lbtcontainertriggerentry.h"
#include "lbtlisttriggerobserver.h"
#include "lbtcontainerlistoptions.h"
#include "lbtsecuritypolicy.h"
// forward declaration
class MLbtTriggerStore; // Trigger Store Interface
class MLbtContainerChangeEventObserver; // Client Observer Interface
class CLbtListTriggerOptions;
class CLbtTriggerIdGenerator;
class CLbtContainerAO;
class CLbtContainerUpdateFilter;
/**
* The data type defines a bitmask of the TLbtTriggerChangeEvent enumerator.
* It is used to subscribe to specific trigger store change events.
*/
typedef TInt TLbtTriggerEventMask;
/**
* This class provides the inteface to access the functionality of the
* Location Triggering Container.
*
* The CLbtContainer is a singleton class. The same instance is shared by all
* the components in the subsystem.
*
* The inteface provides the following functionality,
* - Create a Session or Startup trigger
* - Modify the static or dynamic information of a trigger
* - Delete one or more triggers based on filters.
* - Retrieve information on one or more triggers based on filters.
*
* @lib lbtcontainer.lib
* @since S60 v4.0
*/
NONSHARABLE_CLASS( CLbtContainer ) : public CBase
{
public:
/**
* enumerator to specify the different trigger store events .
*/
enum TLbtTriggerChangeEvent
{
ELbtConTriggerCreated = 0x0001, // A Trigger is added to trigger store
ELbtConTriggerDeleted = 0x0002, // A Trigger is deleted from trigger store
ELbtConTriggerNameFieldChanged = 0x0004, // Trigger Name Field has changed
ELbtConTriggerStateFieldChanged = 0x0008, // Trigger has been enabled or disabled
ELbtConTriggerRequestorFieldChanged = 0x0010, // Trigger requestor Field has changed
ELbtConTriggerManagerUiFieldChanged = 0x0020, // Trigger Manager Ui has changed
ELbtConTriggerConditionFieldChanged = 0x0040, // Trigger Condition has changed
ELbtConTriggerStartupFieldChanged = 0x0080, // Trigger Startup Field has changed
ELbtConTriggerHysteresisFieldChanged = 0x0100, // Trigger Hysteresis Field has Changed
ELbtConTriggerRectAreaFieldChanged = 0x0200, // Trigger Rectangular area field has changed
ELbtConTriggerFiredFieldChanged = 0x0400, // Trigger Fired field has changed
ELbtConTriggerStrategyDataFieldChanged = 0x0800, // Trigger strategy data field has changed
ELbtConTriggerValidityFieldChanged = 0x1000, // Trigger validity field has changed
ELbtConTriggerFireOnCreationFieldChanged = 0x2000, // Trigger fire on creation field has changed
ELbtConTriggerEnabledAndValidCreated = 0x4000 // For startegy. Enabled and valid trigger created
};
public:
/**
* The Symbian 2 phase constructor.
* This method does not create new instances of the container. It creates
* an instance the first time and then returns the same instance.
*
* @return An instance of this class
*/
IMPORT_C static CLbtContainer* NewL();
/**
* Destroy the Container Instance.
* Since this class is a singleton class, this does not necessarily
* destroy the Container instance.
*/
IMPORT_C static void Destroy();
public:
/**
* Create a trigger in the Container. Both session and startup triggers
* are created using this method. This is an synchronous method call.
*
* @param[in] aEntry This parameter contains trigger information.
*
* @param[out] aStatus Contains the error code once the operation is
* completed. The value can be,
* - any Symbian error code.
* - KErrNoMemory if the trigger was not created because of low memory
* - KErrDiskFull if the startup trigger was not created because of
* low disk space.
*/
IMPORT_C void CreateTrigger(
CLbtContainerTriggerEntry &aEntry,TInt& aOpId,
TRequestStatus& aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* Cancel Async Operation operation in the container
*
*/
IMPORT_C void CancelAsyncOperation(TInt aOpId);
/**
* Retreives the specified triggers from the database. Both session and startup
* triggers are retreived by this API. The triggers are retreived asynchronously
*
* @param[in] aTriggerIds the trigger ids which have to be retreived
* @param[out] the container trigger entries that hold the trigger information
* @param[out] aStatus Contains the error code once the operation is
* completed.
* @param[out] aOpId the operation identifier
* @param[in] The security policy which the retreived triggers have to satisfy
*/
IMPORT_C void GetTriggers( const RArray<TLbtTriggerId>& aTriggerIds,
RPointerArray < CLbtContainerTriggerEntry >& aTriggers,
TInt& aOpId,
TRequestStatus& aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* Modify the trigger fire state.The fires state of both session and
* startup triggers can be modified using this method.
*
* @param[in] aTriggerIds an array containing the trigger ids whose
* fired state needs to be updated
*
* @param[out] aOpId the operation identifier
*
* @param[in] aFireBool the state to which the fires state has to be updated
*
* @param[in] aStatus the request status of the client
*/
IMPORT_C void UpdateTriggerFiredState( RArray<TLbtTriggerId>& aTriggerIds,
TInt& aOpId,
TBool aFireBool,
TRequestStatus& aStatus );
/**
* Modifies the fields of a particular trigger in container. The fields
* of both session and startup triggers can be changed using this method.
*
* @param[in] aEntry refrence to the trigger entry whose fields have to be
* changed
*
* @param[in] aDataMask the mask of the data fields that have to be changed
*
* @param[in] aAttrMask the mask of the attribute fields that have to be
* changed
*
* @param[out] aOpId the operation identifier
*
* @param[in] aStatus the request status of the client
*
* @leave KErrNoMemory The trigger was not updated because of low memory
* @leave KErrDiskFull The trigger was not updated because of
* low disk space. This happens when the commandline or the name of
* the trigger is updated and there is no disk space for the update.
*
* @note The Update Trigger potentially allows modification for any
* trigger attribute except the trigger ID. The Container does not perform
* any checks regarding non modifiable attributes.
*/
IMPORT_C void UpdateTriggerL( CLbtContainerTriggerEntry& aEntry,
TLbtTriggerDataMask aDataMask,
TLbtTriggerAttributeFieldsMask aAttrMask,
TInt& aOpId,
TRequestStatus& aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* Modify the state of triggers in the Container. The state of both
* session and startup triggers can be modified using this method.
*
* @param[in] aState This parameter specifies the state to which the trigger
* should be set to.
*
* @param[in] aFilter This parameter specifies the triggers for which the state
* has to be changed.
* <b> The Container will take ownership of the filter paramter.</b>
*
* @param[out] aStatus Contains the error code once the operation is
* completed. The value can be any Symbian error code.
*
* @note The Update Trigger potentially allows modification for any
* trigger attribute except the trigger ID. The Container does not perform
* any checks regarding non modifiable attributes.
*
* @note The Filter can specify a list of trigger Ids. Hence using this
* method it is possible to enable or disable a list of triggers.
*/
IMPORT_C void UpdateTriggersState(
CLbtTriggerEntry::TLbtTriggerState aState,
CLbtContainerUpdateFilter* aFilter,
TInt& aOpId,
TLbtFireOnUpdate aFireOnUpdate,
TRequestStatus& aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* Modify the validity of triggers in the Container. The validity attribute
* of both session and startup triggers can be modified using this method.
*
* @param[in] aValidity This parameter specifies the validity to which the trigger
* should be set to.
*
* @param[in] aFilter This parameter specifies the triggers for which
* the state has to be changed.
* <b> The Container will take ownership of the filter paramter.</b>
*
* @param[out] aStatus Contains the error code once the operation is
* completed.The value can be any Symbian error code.
*
* @note The Update Trigger potentially allows modification for any
* trigger attribute except the trigger ID. The Container does not perform
* any checks regarding non modifiable attributes.
*
* @note The Filter can specify a list of trigger Ids. Hence using this
* method it is possible to set a list of triggers to valid or invalid.
*/
IMPORT_C void UpdateTriggersValidity(
TLbtTriggerDynamicInfo::TLbtTriggerValidity aValidity,
RArray <TLbtTriggerId>& aTriggerIds,
TInt& aOpId,
TRequestStatus& aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* Asynchronous delete triggers in the Container based on a filter.
* Both session and startup triggers can be deleted using this method.
*
* @param[in] aFilter This parameter specifies the triggers which need to
* be deleted.
* <b> The Container will take ownership of the filter paramter.</b>
*
* @param[out] aStatus Contains the error code once the operation is
* completed.The value can be,
* - KErrNotFound if the filter does not match any trigger
* - any other Symbian error code.
*
* @note The Filter can specify a list of trigger Ids. Hence using this
* method it is possible to delete a list of triggers.
*/
IMPORT_C void DeleteTriggers(
CLbtContainerUpdateFilter* aFilter,
TInt& aOpId,
TRequestStatus &aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* List triggers in the Container. The session and startup triggers
* can be deleted using this method.
*
* @param[in] aListOptions Specifies the options used for listing
* triggers. Default value is NULL, which will retrieve all triggers
* owned by the client application.
* <b> The Container will take ownership of the list options paramter.
* </b>
*
* @param[out] aTriggers An Array of trigger entry objects. It contains
* the triggers that match the specified criteria. The ownership of the
* trigger entry objects in the array is transferred to the client.
*
* @param[in] aMask Specifies the attributes that need to be modified.
* The mask is a bitmask of the enumerators defined in
* #CLbtContainerTriggerEntry::TLbtContainerTriggerAttribute
*
* @param[out] aStatus Contains the error code once the operation is
* completed.The value can be,
* - KErrNotFound if the filter does not match any trigger
* - any other Symbian error code.
*
* @note The Filter can specify a list of trigger Ids. Hence using this
* method it is possible to delete a list of triggers.
*/
IMPORT_C void ListTriggers(
CLbtContainerListOptions* aListOptions,
RPointerArray < CLbtContainerTriggerEntry >& aTriggers,
TInt& aOpId,
TRequestStatus &aStatus,
TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );
/**
* Register for notifications when the container trigger store changes.
* The parameters specify the events for which the observer can choose to get
* notification.
*
* @param[in] aObserver This parameter specifies the observer for the events.
* The observer will be notified when ever a change occurs in the Container.
* The container does not take ownership of this parameter.
* @param[in] aEventMask This parameter specifies the specific events for which
* the client wants to obtain notifications
*
* @note the client should implement the observer methods to obtain the
* events.
*/
IMPORT_C void SetChangeObserver(
MLbtContainerChangeEventObserver* aObserver,
TLbtTriggerEventMask aEventMask);
/**
* De-register request for container trigger store change notification.
*
* @param[in] aObserver This parameter specifies the observer that has to
* be de-registered. The Container doesn't take onwership of this parameter.
*
* @note The observer will be not notified when a change occurs in the
* Container in future.
*/
IMPORT_C void RemoveObserver(MLbtContainerChangeEventObserver* aObserver);
/* Get the Count of Enabled and Valid Triggers */
IMPORT_C TInt GetCountOfEnabledAndValidTriggers();
/**
* Used to set the time till when compaction is preferred. Over the time specified
* compaction should not happed in ideal cases. As and when compaction happens this
* time is check to see that compaction does not over shoot this time interval
*
* @param aTime the time untill which compaction can proceed without effecting
* the system
*/
IMPORT_C void SetTimeTillCompaction(TTime aTime);
public:
/**
* Internal structure for maintaining observers
*/
struct TLbtTriggerStoreChangeObserver
{
MLbtContainerChangeEventObserver* iObserver;
TLbtTriggerEventMask iEventMask;
};
private:
/**
* Generates op code to identify requests
*
* @return TInt the opcode
*/
TInt GenerateRandomOpCode();
/**
* C++ constructor
*/
CLbtContainer();
/**
* Symbian 2nd phase of construction
*/
void ConstructL();
/**
* Destructor.
*/
virtual ~CLbtContainer();
/**
* C++ Copy Constructor
* The private copy constructor prevents the usage of copy constructors
* with this class.
*/
CLbtContainer(const CLbtContainer& aContainer);
/**
* Overload equality operator
* The private overload of the equality operator prevents the usage of
* equality operator with this class.
*/
CLbtContainer& operator =(const CLbtContainer& aContainer);
private: // data members
/**
* Pointer to an instance of this class.
* Owns
*/
static CLbtContainer* iContainerInstance;
/**
* variable to maintain usage reference count for the shared instance of
* this class.
*/
static TInt iRefCount;
/**
* Array of Pointers to Trigger Store Managers.
* Owns
*/
RPointerArray<MLbtTriggerStore> iTriggerStores;
/**
* Array of Trigger Store Change Observers.
* Owns
*/
RArray<TLbtTriggerStoreChangeObserver> iObservers;
// For generating trigger ids
TLbtTriggerId iTrigId;
// Pointer to an object of trigger id generator
CLbtTriggerIdGenerator *iTrigIdGenerator;
// Pointer to an object of Container active object
CLbtContainerAO* iContainerAO;
// For random number generator
TInt64 iRandNumRef;
};
#endif // C_lbtTAINER_H