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:  Class of options used in listing triggers

    15 *

    16 */

    17 

    18 

    19 #ifndef LBTLISTTRIGGEROPTIONS_H

    20 #define LBTLISTTRIGGEROPTIONS_H

    21 

    22 #include <lbtcommon.h>

    23 #include <lbtgeoareabase.h>

    24 

    25 class CLbtTriggerFilterBase;

    26 

    27 /**

    28  * Helper class for options used when listing trigger entries 

    29  * from Location Triggering Server.

    30  *

    31  * The following options can be set.

    32  *

    33  * -  <B>Retrieved fields</B>. It specifies what trigger 

    34  * entry attributes field and trigger dynamic information field 

    35  * shall be filled in the returned trigger objects. 

    36  * Default value for trigger entry attribute field is 

    37  * KLbtTriggerAttributeFieldsAll, which means 

    38  * all attributes field shall be filled. Whether the Trigger 

    39  * ID field is specified or not, the trigger ID attribute is always valid

    40  * in returned trigger objects. Default value for trigger dynamic 

    41  * information field is KLbtTriggerDynInfoFieldsAll, which means all 

    42  * dynamic information fields will be filled.

    43  *

    44  * -  <B>Trigger filter</B>. It specifies the filter used in retrieving 

    45  * trigger entries. Retrieved triggers shall fulfill the criteria defined 

    46  * in the filter. By default, the option does not contain a filter

    47  * and all triggers will be retrieved. A composite filter can also be

    48  * used.

    49  *

    50  * -  <B>Sorting option</B>. It specifies in which order the retrieved

    51  * trigger shall be sorted. The default value is ELbtNoSorting. 

    52  * 

    53  * @lib lbt.lib

    54  *

    55  * @since S60 5.1

    56  */

    57 class CLbtListTriggerOptions : public CBase

    58     {

    59 public:

    60     /**

    61      * Sorting order when retrieving triggers

    62      * from Location Triggering Server.

    63      */

    64     enum TLbtListTriggerSorting

    65         {

    66         /**

    67          * Result is not sorted.

    68          */

    69         ELbtNoSorting = 1,

    70 

    71         /**

    72          * Result is in ascending order according to the trigger name.

    73          */

    74         ELbtTriggerNameAscending = 2,

    75 

    76         /**

    77          * Result is in descending order according to the trigger name.

    78          */

    79         ELbtTriggerNameDescending = 3,

    80 

    81         /**

    82          * Result is in ascending order according to the distance from 

    83          * the trigger area to the latest acquired location by Location

    84          * Triggering Server.

    85          */

    86         ELbtDistanceToLatestLocationAscending = 4

    87         };

    88 

    89 

    90 public:

    91 

    92     /**

    93      * Constructs a new instance of trigger listing option object.

    94      * In the returned object, retrieved fields is set 

    95      * to KLbtTriggerAttributeFieldsAll and KLbtTriggerDynInfoFieldsAll, 

    96      * no trigger filters is set and sorting option is set to 

    97      * ELbtNoSorting.

    98      *

    99      * @return Pointer to the new instance of the trigger 

   100      * retrieving option object.

   101      */

   102     IMPORT_C static CLbtListTriggerOptions* NewL();

   103 

   104     /**

   105      * Constructs a new instance of trigger listing option object and 

   106      * pushes it onto cleanup stack.

   107      * In the returned object, retrieved fields is set 

   108      * to KLbtTriggerAttributeFieldsAll and KLbtTriggerDynInfoFieldsAll, 

   109      * no trigger filters is set and sorting option is set to 

   110      * ELbtNoSorting.

   111      *

   112      * @return Pointer to the new instance of the trigger 

   113      * retrieving option object.

   114      */

   115     IMPORT_C static CLbtListTriggerOptions* NewLC();

   116     

   117     /**

   118      * Destructor

   119      */

   120     IMPORT_C ~CLbtListTriggerOptions();

   121 

   122     /**

   123      * Gets the fields that Location Triggering Server will fill when

   124      * list triggers 

   125      *

   126      * If the entry fields mask and dynamic information field mask 

   127      * is not set before, KLbtTriggerAttributeFieldsAll and 

   128      * KLbtTriggerDynInfoFieldsAll

   129      * are returned.

   130      *

   131      * @param[out] aEntryMask On return contains the field mask defines

   132      * which trigger entry fields shall be filled.

   133      * @param[out] aDynInfoMask On return contains the field mask defines

   134      * which trigger dynamic information field shall be filled.

   135      */

   136     IMPORT_C void GetRetrievedFields( 

   137         TLbtTriggerAttributeFieldsMask &aEntryMask,

   138         TLbtTriggerDynamicInfoFieldsMask &aDynInfoMask ) const;

   139 

   140     /**

   141      * Sets which fields shall be filled by Location

   142      * Triggering Server when listing triggers.

   143      *

   144      * @param[in] aEntryMask Mask defines which trigger entry fields shall 

   145      * be filled.

   146      * @param[in] aDynInfoMask The mask defines which dynamic information

   147      * field shall be filled.

   148      */

   149     IMPORT_C void SetRetrievedFields( 

   150         TLbtTriggerAttributeFieldsMask aEntryMask,

   151         TLbtTriggerDynamicInfoFieldsMask aDynInfoMask = KLbtTriggerDynInfoFieldsAll );

   152 

   153     /**

   154      * Gets the sorting option when listing triggers. This

   155      * function returns ELbtNoSorting if the sorting option has

   156      * not been set.

   157      *

   158      * @return The sorting option when listing triggers.

   159      */

   160     IMPORT_C TLbtListTriggerSorting SortingOption() const;

   161 

   162     /**

   163      * Sets the sorting option when listing triggers. 

   164      *

   165      * @param[in] aOption The sorting option when retrieving triggers.

   166      */

   167     IMPORT_C void SetSortingOption( TLbtListTriggerSorting aOption );

   168 

   169     /**

   170      * Sets the filter used for listing triggers.

   171      *

   172      * @param[in] aFilter Pointer to the filter used for

   173      * listing triggers. If the pointer is NULL, previous set 

   174      * filter is deleted. Ownership of aFilter is transferred to

   175      * the client application.

   176      */

   177     IMPORT_C void SetFilter( 

   178         CLbtTriggerFilterBase* aFilter );

   179 

   180     /**

   181      * Gets pointer to the filter used for listing triggers.

   182      * The function returns NULL if the filter is not previously set.

   183      *

   184      * @return The filter used for listing triggers. Ownership

   185      * of the returned object is not transferred to the client

   186      * application.

   187      */

   188     IMPORT_C CLbtTriggerFilterBase* Filter();

   189     

   190     /**

   191      * Internalizes the trigger condition object's details and attributes 

   192      * from stream.

   193      *

   194      * The presence of this function means that the standard templated 

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

   196      * of this class.

   197      *

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

   199      */

   200     IMPORT_C void InternalizeL( RReadStream& aStream );

   201     

   202     /**

   203      * Externalizes the trigger condition object's details and attributes

   204      * to stream.

   205      *

   206      * The presence of this function means that the standard templated 

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

   208      * of this class.

   209      *

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

   211      */

   212     IMPORT_C void ExternalizeL( RWriteStream& aStream ) const;

   213     

   214 private:

   215     /**

   216      * Default Constructor.

   217      */

   218     CLbtListTriggerOptions();

   219     

   220     /**

   221      * By default, prohibit copy constructor

   222      */

   223     CLbtListTriggerOptions( const CLbtListTriggerOptions& );

   224     

   225     /**

   226      * Prohibit assigment operator

   227      */

   228     CLbtListTriggerOptions& operator= ( const CLbtListTriggerOptions& );

   229     

   230     /**

   231      * Symbian 2nd phase constructor

   232      */

   233     void ConstructL();

   234   

   235 private:

   236     /**

   237      * Trigger entry fields mask

   238      */

   239     TLbtTriggerAttributeFieldsMask iTriigerAttributeFieldsMask;

   240 

   241     /**

   242      * Trigger dynamic information field mask

   243      */

   244     TLbtTriggerDynamicInfoFieldsMask  iDynInfoFieldsMask;

   245 

   246     /**

   247      * Filter

   248      */

   249     CLbtTriggerFilterBase* iFilter;

   250 

   251     /**

   252      * Sorting

   253      */

   254     TLbtListTriggerSorting iSorting;

   255     

   256     /**

   257      * Reserved

   258      */

   259     TUint iReserved[8];

   260     };

   261 

   262 #endif // LBTLISTTRIGGEROPTIONS_H