/*

 * 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

 * which accompanies this distribution, and is available

 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  Class of options used in listing triggers

 *

 */

 #ifndef LBTLISTTRIGGEROPTIONS_H

 #define LBTLISTTRIGGEROPTIONS_H

 #include <lbtcommon.h>

 #include <lbtgeoareabase.h>

 class CLbtTriggerFilterBase;

 /**

  * Helper class for options used when listing trigger entries 

  * from Location Triggering Server.

  *

  * The following options can be set.

  *

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

  * entry attributes field and trigger dynamic information field 

  * shall be filled in the returned trigger objects. 

  * Default value for trigger entry attribute field is 

  * KLbtTriggerAttributeFieldsAll, which means 

  * all attributes field shall be filled. Whether the Trigger 

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

  * in returned trigger objects. Default value for trigger dynamic 

  * information field is KLbtTriggerDynInfoFieldsAll, which means all 

  * dynamic information fields will be filled.

  *

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

  * trigger entries. Retrieved triggers shall fulfill the criteria defined 

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

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

  * used.

  *

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

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

  * 

  * @lib lbt.lib

  *

  * @since S60 5.1

  */

 class CLbtListTriggerOptions : public CBase

     {

 public:

     /**

      * Sorting order when retrieving triggers

      * from Location Triggering Server.

      */

     enum TLbtListTriggerSorting

         {

         /**

          * Result is not sorted.

          */

         ELbtNoSorting = 1,

         /**

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

          */

         ELbtTriggerNameAscending = 2,

         /**

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

          */

         ELbtTriggerNameDescending = 3,

         /**

          * Result is in ascending order according to the distance from 

          * the trigger area to the latest acquired location by Location

          * Triggering Server.

          */

         ELbtDistanceToLatestLocationAscending = 4

         };

 public:

     /**

      * Constructs a new instance of trigger listing option object.

      * In the returned object, retrieved fields is set 

      * to KLbtTriggerAttributeFieldsAll and KLbtTriggerDynInfoFieldsAll, 

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

      * ELbtNoSorting.

      *

      * @return Pointer to the new instance of the trigger 

      * retrieving option object.

      */

     IMPORT_C static CLbtListTriggerOptions* NewL();

     /**

      * Constructs a new instance of trigger listing option object and 

      * pushes it onto cleanup stack.

      * In the returned object, retrieved fields is set 

      * to KLbtTriggerAttributeFieldsAll and KLbtTriggerDynInfoFieldsAll, 

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

      * ELbtNoSorting.

      *

      * @return Pointer to the new instance of the trigger 

      * retrieving option object.

      */

     IMPORT_C static CLbtListTriggerOptions* NewLC();

     /**

      * Destructor

      */

     IMPORT_C ~CLbtListTriggerOptions();

     /**

      * Gets the fields that Location Triggering Server will fill when

      * list triggers 

      *

      * If the entry fields mask and dynamic information field mask 

      * is not set before, KLbtTriggerAttributeFieldsAll and 

      * KLbtTriggerDynInfoFieldsAll

      * are returned.

      *

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

      * which trigger entry fields shall be filled.

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

      * which trigger dynamic information field shall be filled.

      */

     IMPORT_C void GetRetrievedFields( 

         TLbtTriggerAttributeFieldsMask &aEntryMask,

         TLbtTriggerDynamicInfoFieldsMask &aDynInfoMask ) const;

     /**

      * Sets which fields shall be filled by Location

      * Triggering Server when listing triggers.

      *

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

      * be filled.

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

      * field shall be filled.

      */

     IMPORT_C void SetRetrievedFields( 

         TLbtTriggerAttributeFieldsMask aEntryMask,

         TLbtTriggerDynamicInfoFieldsMask aDynInfoMask = KLbtTriggerDynInfoFieldsAll );

     /**

      * Gets the sorting option when listing triggers. This

      * function returns ELbtNoSorting if the sorting option has

      * not been set.

      *

      * @return The sorting option when listing triggers.

      */

     IMPORT_C TLbtListTriggerSorting SortingOption() const;

     /**

      * Sets the sorting option when listing triggers. 

      *

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

      */

     IMPORT_C void SetSortingOption( TLbtListTriggerSorting aOption );

     /**

      * Sets the filter used for listing triggers.

      *

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

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

      * filter is deleted. Ownership of aFilter is transferred to

      * the client application.

      */

     IMPORT_C void SetFilter( 

         CLbtTriggerFilterBase* aFilter );

     /**

      * Gets pointer to the filter used for listing triggers.

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

      *

      * @return The filter used for listing triggers. Ownership

      * of the returned object is not transferred to the client

      * application.

      */

     IMPORT_C CLbtTriggerFilterBase* Filter();

     /**

      * Internalizes the trigger condition object's details and attributes 

      * from stream.

      *

      * The presence of this function means that the standard templated 

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

      * of this class.

      *

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

      */

     IMPORT_C void InternalizeL( RReadStream& aStream );

     /**

      * Externalizes the trigger condition object's details and attributes

      * to stream.

      *

      * The presence of this function means that the standard templated 

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

      * of this class.

      *

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

      */

     IMPORT_C void ExternalizeL( RWriteStream& aStream ) const;

 private:

     /**

      * Default Constructor.

      */

     CLbtListTriggerOptions();

     /**

      * By default, prohibit copy constructor

      */

     CLbtListTriggerOptions( const CLbtListTriggerOptions& );

     /**

      * Prohibit assigment operator

      */

     CLbtListTriggerOptions& operator= ( const CLbtListTriggerOptions& );

     /**

      * Symbian 2nd phase constructor

      */

     void ConstructL();

 private:

     /**

      * Trigger entry fields mask

      */

     TLbtTriggerAttributeFieldsMask iTriigerAttributeFieldsMask;

     /**

      * Trigger dynamic information field mask

      */

     TLbtTriggerDynamicInfoFieldsMask  iDynInfoFieldsMask;

     /**

      * Filter

      */

     CLbtTriggerFilterBase* iFilter;

     /**

      * Sorting

      */

     TLbtListTriggerSorting iSorting;

     /**

      * Reserved

      */

     TUint iReserved[8];

     };

 #endif // LBTLISTTRIGGEROPTIONS_H