1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This header file describes the triggering container interface

    15 *

    16 */

    17 

    18 

    19 #ifndef C_LBTCONTAINER_H

    20 #define C_LBTCONTAINER_H

    21 

    22 #include <e32base.h>

    23 #include <lbttriggerfiltercomposite.h>

    24 #include <lbttriggerdynamicinfo.h>

    25 #include <lbtlisttriggeroptions.h>

    26 

    27 #include "lbtcontainertriggerentry.h"

    28 #include "lbtlisttriggerobserver.h"

    29 #include "lbtcontainerlistoptions.h"

    30 #include "lbtsecuritypolicy.h"

    31 

    32 

    33 // forward declaration

    34 class MLbtTriggerStore; // Trigger Store Interface

    35 class MLbtContainerChangeEventObserver; // Client Observer Interface

    36 class CLbtListTriggerOptions;

    37 class CLbtTriggerIdGenerator;

    38 class CLbtContainerAO;

    39 class CLbtContainerUpdateFilter;

    40 

    41 /**

    42  * The data type defines a bitmask of the TLbtTriggerChangeEvent enumerator.

    43  * It is used to subscribe to specific trigger store change events.

    44  */

    45 typedef TInt TLbtTriggerEventMask;

    46     

    47 /**

    48  *  This class provides the inteface to access the functionality of the

    49  *  Location Triggering Container.

    50  *

    51  *  The CLbtContainer is a singleton class. The same instance is shared by all

    52  *  the components in the subsystem.

    53  *

    54  *  The inteface provides the following functionality,

    55  *  - Create a Session or Startup trigger

    56  *  - Modify the static or dynamic information of a trigger

    57  *  - Delete one or more triggers based on filters.

    58  *  - Retrieve information on one or more triggers based on filters.

    59  *

    60  *  @lib lbtcontainer.lib

    61  *  @since S60 v4.0

    62  */

    63 NONSHARABLE_CLASS( CLbtContainer ) : public CBase

    64     {

    65 public:

    66     /**

    67      * enumerator to specify the different trigger store events .

    68      */

    69     enum TLbtTriggerChangeEvent

    70         {

    71         ELbtConTriggerCreated = 0x0001, // A Trigger is added to trigger store

    72         ELbtConTriggerDeleted = 0x0002, // A Trigger is deleted from trigger store

    73         ELbtConTriggerNameFieldChanged = 0x0004, // Trigger Name Field has changed

    74         ELbtConTriggerStateFieldChanged = 0x0008, // Trigger has been enabled or disabled

    75         ELbtConTriggerRequestorFieldChanged = 0x0010, // Trigger requestor Field has changed

    76         ELbtConTriggerManagerUiFieldChanged = 0x0020, // Trigger Manager Ui has changed

    77         ELbtConTriggerConditionFieldChanged = 0x0040, // Trigger Condition has changed

    78         ELbtConTriggerStartupFieldChanged = 0x0080, // Trigger Startup Field has changed

    79         ELbtConTriggerHysteresisFieldChanged = 0x0100, // Trigger Hysteresis Field has Changed

    80         ELbtConTriggerRectAreaFieldChanged = 0x0200, // Trigger Rectangular area field has changed

    81         ELbtConTriggerFiredFieldChanged = 0x0400, // Trigger Fired field has changed

    82         ELbtConTriggerStrategyDataFieldChanged = 0x0800, // Trigger strategy data field has changed

    83         ELbtConTriggerValidityFieldChanged = 0x1000, // Trigger validity field has changed

    84         ELbtConTriggerFireOnCreationFieldChanged = 0x2000, // Trigger fire on creation field has changed

    85         ELbtConTriggerEnabledAndValidCreated = 0x4000 // For startegy. Enabled and valid trigger created

    86         };

    87         

    88 public:

    89     /**

    90      * The Symbian 2 phase constructor.

    91      * This method does not create new instances of the container. It creates

    92      * an instance the first time and then returns the same instance.

    93      *

    94      * @return An instance of this class

    95      */

    96     IMPORT_C static CLbtContainer* NewL();

    97 

    98     /**

    99      * Destroy the Container Instance.

   100      * Since this class is a singleton class, this does not necessarily 

   101      * destroy the Container instance. 

   102      */

   103 

   104     IMPORT_C static void Destroy();

   105     

   106 public:    

   107     /**

   108      * Create a trigger in the Container. Both session and startup triggers

   109      * are created using this method. This is an synchronous method call.

   110      *

   111      * @param[in] aEntry This parameter contains trigger information.

   112      * 

   113      * @param[out] aStatus Contains the error code once the operation is 

   114      * completed. The value can be,

   115      * - any Symbian error code.

   116      * - KErrNoMemory if the trigger was not created because of low memory

   117      * - KErrDiskFull if the startup trigger was not created because of

   118      * low disk space.

   119      */

   120     IMPORT_C void CreateTrigger(

   121                     CLbtContainerTriggerEntry &aEntry,TInt& aOpId,

   122                     TRequestStatus& aStatus,

   123                     TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );                    

   124                     

   125                     

   126     /** 

   127      * Cancel Async Operation operation in the container

   128      *

   129      */    

   130     IMPORT_C void CancelAsyncOperation(TInt aOpId);

   131     

   132     /**

   133      * Retreives the specified triggers from the database. Both session and startup 

   134      * triggers are retreived by this API. The triggers are retreived asynchronously

   135      *

   136      * @param[in] aTriggerIds the trigger ids which have to be retreived 

   137      * @param[out] the container trigger entries that hold the trigger information

   138      * @param[out] aStatus Contains the error code once the operation is 

   139      * completed.

   140      * @param[out] aOpId the operation identifier

   141      * @param[in] The security policy which the retreived triggers have to satisfy

   142      */

   143     IMPORT_C void GetTriggers( const RArray<TLbtTriggerId>& aTriggerIds,

   144     						   RPointerArray < CLbtContainerTriggerEntry >& aTriggers,

   145     						   TInt& aOpId,

   146     						   TRequestStatus& aStatus,

   147     						   TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );

   148     

   149     

   150     /**

   151      * Modify the trigger fire state.The fires state of both session and 

   152      * startup triggers can be modified using this method.

   153      *

   154      * @param[in] aTriggerIds an array containing the trigger ids whose

   155      * fired state needs to be updated

   156      *

   157      * @param[out] aOpId the operation identifier

   158      *

   159      * @param[in] aFireBool the state to which the fires state has to be updated

   160      *

   161      * @param[in] aStatus the request status of the client 

   162      */

   163 	IMPORT_C void UpdateTriggerFiredState( RArray<TLbtTriggerId>& aTriggerIds,

   164 				                		   TInt& aOpId,

   165 				                		   TBool aFireBool,

   166 			                    		   TRequestStatus& aStatus );

   167 

   168 

   169 	/**

   170 	 * Modifies the fields of a particular trigger in container. The fields

   171 	 * of both session and startup triggers can be changed using this method.

   172 	 *

   173 	 * @param[in] aEntry refrence to the trigger entry whose fields have to be 

   174 	 * changed

   175 	 *

   176 	 * @param[in] aDataMask the mask of the data fields that have to be changed

   177 	 *

   178 	 * @param[in] aAttrMask the mask of the attribute fields that have to be 

   179 	 * changed

   180 	 *

   181 	 * @param[out] aOpId the operation identifier

   182 	 *

   183 	 * @param[in] aStatus the request status of the client 

   184 	 *

   185 	 * @leave KErrNoMemory The trigger was not updated because of low memory

   186      * @leave KErrDiskFull The trigger was not updated because of

   187      * low disk space. This happens when the commandline or the name of

   188      * the trigger is updated and there is no disk space for the update.

   189      *

   190      * @note The Update Trigger potentially allows modification for any 

   191      * trigger attribute except the trigger ID. The Container does not perform

   192      * any checks regarding non modifiable attributes.

   193 	 */

   194 	

   195 	IMPORT_C void UpdateTriggerL( CLbtContainerTriggerEntry& aEntry,

   196     							  TLbtTriggerDataMask aDataMask,

   197     							  TLbtTriggerAttributeFieldsMask aAttrMask,

   198     							  TInt& aOpId,

   199     							  TRequestStatus& aStatus,

   200                     			  TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );

   201     /**

   202      * Modify the state of triggers in the Container. The state of both 

   203      * session and startup triggers can be modified using this method.

   204      * 

   205      * @param[in] aState This parameter specifies the state to which the trigger

   206      * should be set to. 

   207      *

   208      * @param[in] aFilter This parameter specifies the triggers for which the state

   209      * has to be changed. 

   210      * <b> The Container will take ownership of the filter paramter.</b>

   211      *

   212      * @param[out] aStatus Contains the error code once the operation is 

   213      * completed. The value can be any Symbian error code.

   214      *

   215      * @note The Update Trigger potentially allows modification for any 

   216      * trigger attribute except the trigger ID. The Container does not perform

   217      * any checks regarding non modifiable attributes.

   218      *

   219      * @note The Filter can specify a list of trigger Ids. Hence using this 

   220      * method it is possible to enable or disable a list of triggers.

   221      */

   222 	 IMPORT_C void UpdateTriggersState(

   223 	                CLbtTriggerEntry::TLbtTriggerState aState,

   224                     CLbtContainerUpdateFilter* aFilter,

   225                     TInt& aOpId,

   226                     TLbtFireOnUpdate aFireOnUpdate,

   227                     TRequestStatus& aStatus,

   228                     TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );

   229                     

   230   

   231        

   232     /**

   233      * Modify the validity of triggers in the Container. The validity attribute

   234      * of both session and startup triggers can be modified using this method.

   235      * 

   236      * @param[in] aValidity This parameter specifies the validity to which the trigger

   237      * should be set to.

   238      *

   239      * @param[in] aFilter This parameter specifies the triggers for which

   240      * the state has to be changed.

   241      * <b> The Container will take ownership of the filter paramter.</b>

   242      *

   243      * @param[out] aStatus Contains the error code once the operation is 

   244      * completed.The value can be any Symbian error code.

   245      *

   246      * @note The Update Trigger potentially allows modification for any 

   247      * trigger attribute except the trigger ID. The Container does not perform

   248      * any checks regarding non modifiable attributes.

   249      *

   250      * @note The Filter can specify a list of trigger Ids. Hence using this 

   251      * method it is possible to set a list of triggers to valid or invalid.

   252      */

   253 	IMPORT_C void UpdateTriggersValidity(

   254                     TLbtTriggerDynamicInfo::TLbtTriggerValidity aValidity,

   255                     RArray <TLbtTriggerId>& aTriggerIds,

   256                     TInt& aOpId,

   257                     TRequestStatus& aStatus,

   258                     TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );

   259                     

   260 

   261     /**

   262      * Asynchronous delete triggers in the Container based on a filter. 

   263      * Both session and startup triggers can be deleted using this method.

   264      * 

   265      * @param[in] aFilter This parameter specifies the triggers which need to

   266      * be deleted.

   267      * <b> The Container will take ownership of the filter paramter.</b>

   268      *

   269      * @param[out] aStatus Contains the error code once the operation is 

   270      * completed.The value can be,

   271      * - KErrNotFound if the filter does not match any trigger

   272      * - any other Symbian error code.

   273      *

   274      * @note The Filter can specify a list of trigger Ids. Hence using this 

   275      * method it is possible to delete a list of triggers.

   276      */

   277 	IMPORT_C void DeleteTriggers(

   278 	                CLbtContainerUpdateFilter* aFilter,

   279 	                TInt& aOpId,

   280 	                TRequestStatus &aStatus,

   281                     TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );

   282 	

   283     /**

   284      * List triggers in the Container. The session and startup triggers

   285      * can be deleted using this method.

   286      * 

   287      * @param[in] aListOptions Specifies the options used for listing 

   288      * triggers. Default value is NULL, which will retrieve all triggers

   289      * owned by the client application.

   290      * <b> The Container will take ownership of the list options paramter.

   291      * </b>

   292      *

   293      * @param[out] aTriggers An Array of trigger entry objects. It contains 

   294      * the triggers that match the specified criteria. The ownership of the 

   295      * trigger entry objects in the array is transferred to the client.

   296      *

   297      * @param[in] aMask Specifies the attributes that need to be modified.

   298      * The mask is a bitmask of the enumerators defined in 

   299      * #CLbtContainerTriggerEntry::TLbtContainerTriggerAttribute

   300      *

   301      * @param[out] aStatus Contains the error code once the operation is 

   302      * completed.The value can be,

   303      * - KErrNotFound if the filter does not match any trigger

   304      * - any other Symbian error code.

   305      *

   306      * @note The Filter can specify a list of trigger Ids. Hence using this 

   307      * method it is possible to delete a list of triggers.

   308      */

   309 	IMPORT_C void ListTriggers(

   310 	                CLbtContainerListOptions* aListOptions,

   311 	                RPointerArray < CLbtContainerTriggerEntry >& aTriggers,

   312 	                TInt& aOpId,

   313 	                TRequestStatus &aStatus,

   314                     TLbtSecurityPolicy aSecurityPolicy = KLbtNullSecurity );

   315 	 

   316     /**

   317      * Register for notifications when the container trigger store changes.

   318      * The parameters specify the events for which the observer can choose to get

   319      * notification.

   320      *

   321      * @param[in] aObserver This parameter specifies the observer for the events.

   322      * The observer will be notified when ever a change occurs in the Container.

   323      * The container does not take ownership of this parameter.

   324      * @param[in] aEventMask This parameter specifies the specific events for which

   325      * the client wants to obtain notifications

   326      *

   327      * @note the client should implement the observer methods to obtain the 

   328      * events. 

   329      */

   330 	IMPORT_C void SetChangeObserver(

   331 	                MLbtContainerChangeEventObserver* aObserver,

   332 	                TLbtTriggerEventMask aEventMask);

   333 

   334     /**

   335      * De-register request for container trigger store change notification.

   336      *

   337      * @param[in] aObserver This parameter specifies the observer that has to 

   338      * be de-registered. The Container doesn't take onwership of this parameter.

   339      *

   340      * @note The observer will be not notified when a change occurs in the

   341      * Container in future.

   342      */

   343 	IMPORT_C void RemoveObserver(MLbtContainerChangeEventObserver* aObserver);

   344 

   345 

   346 	/* Get the Count of Enabled and Valid Triggers */

   347 	IMPORT_C TInt GetCountOfEnabledAndValidTriggers();

   348 	

   349 	/**

   350 	 * Used to set the time till when compaction is preferred. Over the time specified

   351 	 * compaction should not happed in ideal cases. As and when compaction happens this

   352 	 * time is check to see that compaction does not over shoot this time interval

   353 	 *

   354 	 * @param aTime the time untill which compaction can proceed without effecting

   355 	 *        the system

   356 	 */ 

   357 	IMPORT_C void SetTimeTillCompaction(TTime aTime);

   358 	

   359 

   360 public:

   361     /**

   362      * Internal structure for maintaining observers

   363      */     

   364     struct TLbtTriggerStoreChangeObserver

   365         {

   366         MLbtContainerChangeEventObserver* iObserver;

   367         TLbtTriggerEventMask iEventMask;

   368         };

   369         

   370 private:

   371 	/**

   372 	 * Generates op code to identify requests

   373 	 *

   374 	 * @return TInt the opcode

   375 	 */ 

   376 	TInt GenerateRandomOpCode();

   377 

   378     /**

   379      * C++ constructor

   380      */

   381     CLbtContainer();

   382 

   383     /**

   384      * Symbian 2nd phase of construction

   385      */

   386     void ConstructL();

   387 

   388     /**

   389      * Destructor.

   390      */

   391     virtual ~CLbtContainer();

   392     

   393     /**

   394      * C++ Copy Constructor

   395      * The private copy constructor prevents the usage of copy constructors

   396      * with this class.

   397      */

   398     CLbtContainer(const CLbtContainer& aContainer);

   399     

   400     /**

   401      * Overload equality operator

   402      * The private overload of the equality operator prevents the usage of

   403      * equality operator with this class.

   404      */

   405     CLbtContainer& operator =(const CLbtContainer& aContainer);

   406     

   407 

   408 private: // data members

   409     /**

   410      * Pointer to an instance of this class.

   411      * Owns

   412      */

   413     static CLbtContainer* iContainerInstance;

   414 

   415     /**

   416      * variable to maintain usage reference count for the shared instance of 

   417      * this class.

   418      */

   419     static TInt iRefCount;

   420     

   421     /**

   422      * Array of Pointers to Trigger Store Managers.

   423      * Owns

   424      */

   425     RPointerArray<MLbtTriggerStore> iTriggerStores;

   426     

   427     /**

   428      * Array of Trigger Store Change Observers.

   429      * Owns

   430      */

   431     RArray<TLbtTriggerStoreChangeObserver> iObservers;

   432     

   433     // For generating trigger ids

   434     TLbtTriggerId iTrigId;

   435     

   436     // Pointer to an object of trigger id generator

   437     CLbtTriggerIdGenerator *iTrigIdGenerator;

   438     

   439     // Pointer to an object of Container active object

   440     CLbtContainerAO* iContainerAO;

   441     

   442     // For random number generator

   443     TInt64 iRandNumRef;

   444     };

   445 

   446 

   447 #endif //  C_lbtTAINER_H