--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/locationtriggering/ltcontainer/inc/lbtcontainer.h Tue Feb 02 01:06:48 2010 +0200
@@ -0,0 +1,447 @@
+/*
+* 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