williamr@2: /*
williamr@2: * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Class of options used in listing triggers
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef LBTLISTTRIGGEROPTIONS_H
williamr@2: #define LBTLISTTRIGGEROPTIONS_H
williamr@2: 
williamr@2: #include <lbtcommon.h>
williamr@2: #include <lbtgeoareabase.h>
williamr@2: 
williamr@2: class CLbtTriggerFilterBase;
williamr@2: 
williamr@2: /**
williamr@2:  * Helper class for options used when listing trigger entries 
williamr@2:  * from Location Triggering Server.
williamr@2:  *
williamr@2:  * The following options can be set.
williamr@2:  *
williamr@2:  * -  <B>Retrieved fields</B>. It specifies what trigger 
williamr@2:  * entry attributes field and trigger dynamic information field 
williamr@2:  * shall be filled in the returned trigger objects. 
williamr@2:  * Default value for trigger entry attribute field is 
williamr@2:  * KLbtTriggerAttributeFieldsAll, which means 
williamr@2:  * all attributes field shall be filled. Whether the Trigger 
williamr@2:  * ID field is specified or not, the trigger ID attribute is always valid
williamr@2:  * in returned trigger objects. Default value for trigger dynamic 
williamr@2:  * information field is KLbtTriggerDynInfoFieldsAll, which means all 
williamr@2:  * dynamic information fields will be filled.
williamr@2:  *
williamr@2:  * -  <B>Trigger filter</B>. It specifies the filter used in retrieving 
williamr@2:  * trigger entries. Retrieved triggers shall fulfill the criteria defined 
williamr@2:  * in the filter. By default, the option does not contain a filter
williamr@2:  * and all triggers will be retrieved. A composite filter can also be
williamr@2:  * used.
williamr@2:  *
williamr@2:  * -  <B>Sorting option</B>. It specifies in which order the retrieved
williamr@2:  * trigger shall be sorted. The default value is ELbtNoSorting. 
williamr@2:  * 
williamr@2:  * @lib lbt.lib
williamr@2:  *
williamr@2:  * @since S60 5.1
williamr@2:  */
williamr@2: class CLbtListTriggerOptions : public CBase
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * Sorting order when retrieving triggers
williamr@2:      * from Location Triggering Server.
williamr@2:      */
williamr@2:     enum TLbtListTriggerSorting
williamr@2:         {
williamr@2:         /**
williamr@2:          * Result is not sorted.
williamr@2:          */
williamr@2:         ELbtNoSorting = 1,
williamr@2: 
williamr@2:         /**
williamr@2:          * Result is in ascending order according to the trigger name.
williamr@2:          */
williamr@2:         ELbtTriggerNameAscending = 2,
williamr@2: 
williamr@2:         /**
williamr@2:          * Result is in descending order according to the trigger name.
williamr@2:          */
williamr@2:         ELbtTriggerNameDescending = 3,
williamr@2: 
williamr@2:         /**
williamr@2:          * Result is in ascending order according to the distance from 
williamr@2:          * the trigger area to the latest acquired location by Location
williamr@2:          * Triggering Server.
williamr@2:          */
williamr@2:         ELbtDistanceToLatestLocationAscending = 4
williamr@2:         };
williamr@2: 
williamr@2: 
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * Constructs a new instance of trigger listing option object.
williamr@2:      * In the returned object, retrieved fields is set 
williamr@2:      * to KLbtTriggerAttributeFieldsAll and KLbtTriggerDynInfoFieldsAll, 
williamr@2:      * no trigger filters is set and sorting option is set to 
williamr@2:      * ELbtNoSorting.
williamr@2:      *
williamr@2:      * @return Pointer to the new instance of the trigger 
williamr@2:      * retrieving option object.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtListTriggerOptions* NewL();
williamr@2: 
williamr@2:     /**
williamr@2:      * Constructs a new instance of trigger listing option object and 
williamr@2:      * pushes it onto cleanup stack.
williamr@2:      * In the returned object, retrieved fields is set 
williamr@2:      * to KLbtTriggerAttributeFieldsAll and KLbtTriggerDynInfoFieldsAll, 
williamr@2:      * no trigger filters is set and sorting option is set to 
williamr@2:      * ELbtNoSorting.
williamr@2:      *
williamr@2:      * @return Pointer to the new instance of the trigger 
williamr@2:      * retrieving option object.
williamr@2:      */
williamr@2:     IMPORT_C static CLbtListTriggerOptions* NewLC();
williamr@2:     
williamr@2:     /**
williamr@2:      * Destructor
williamr@2:      */
williamr@2:     IMPORT_C ~CLbtListTriggerOptions();
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the fields that Location Triggering Server will fill when
williamr@2:      * list triggers 
williamr@2:      *
williamr@2:      * If the entry fields mask and dynamic information field mask 
williamr@2:      * is not set before, KLbtTriggerAttributeFieldsAll and 
williamr@2:      * KLbtTriggerDynInfoFieldsAll
williamr@2:      * are returned.
williamr@2:      *
williamr@2:      * @param[out] aEntryMask On return contains the field mask defines
williamr@2:      * which trigger entry fields shall be filled.
williamr@2:      * @param[out] aDynInfoMask On return contains the field mask defines
williamr@2:      * which trigger dynamic information field shall be filled.
williamr@2:      */
williamr@2:     IMPORT_C void GetRetrievedFields( 
williamr@2:         TLbtTriggerAttributeFieldsMask &aEntryMask,
williamr@2:         TLbtTriggerDynamicInfoFieldsMask &aDynInfoMask ) const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets which fields shall be filled by Location
williamr@2:      * Triggering Server when listing triggers.
williamr@2:      *
williamr@2:      * @param[in] aEntryMask Mask defines which trigger entry fields shall 
williamr@2:      * be filled.
williamr@2:      * @param[in] aDynInfoMask The mask defines which dynamic information
williamr@2:      * field shall be filled.
williamr@2:      */
williamr@2:     IMPORT_C void SetRetrievedFields( 
williamr@2:         TLbtTriggerAttributeFieldsMask aEntryMask,
williamr@2:         TLbtTriggerDynamicInfoFieldsMask aDynInfoMask = KLbtTriggerDynInfoFieldsAll );
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets the sorting option when listing triggers. This
williamr@2:      * function returns ELbtNoSorting if the sorting option has
williamr@2:      * not been set.
williamr@2:      *
williamr@2:      * @return The sorting option when listing triggers.
williamr@2:      */
williamr@2:     IMPORT_C TLbtListTriggerSorting SortingOption() const;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the sorting option when listing triggers. 
williamr@2:      *
williamr@2:      * @param[in] aOption The sorting option when retrieving triggers.
williamr@2:      */
williamr@2:     IMPORT_C void SetSortingOption( TLbtListTriggerSorting aOption );
williamr@2: 
williamr@2:     /**
williamr@2:      * Sets the filter used for listing triggers.
williamr@2:      *
williamr@2:      * @param[in] aFilter Pointer to the filter used for
williamr@2:      * listing triggers. If the pointer is NULL, previous set 
williamr@2:      * filter is deleted. Ownership of aFilter is transferred to
williamr@2:      * the client application.
williamr@2:      */
williamr@2:     IMPORT_C void SetFilter( 
williamr@2:         CLbtTriggerFilterBase* aFilter );
williamr@2: 
williamr@2:     /**
williamr@2:      * Gets pointer to the filter used for listing triggers.
williamr@2:      * The function returns NULL if the filter is not previously set.
williamr@2:      *
williamr@2:      * @return The filter used for listing triggers. Ownership
williamr@2:      * of the returned object is not transferred to the client
williamr@2:      * application.
williamr@2:      */
williamr@2:     IMPORT_C CLbtTriggerFilterBase* Filter();
williamr@2:     
williamr@2:     /**
williamr@2:      * Internalizes the trigger condition object's details and attributes 
williamr@2:      * from stream.
williamr@2:      *
williamr@2:      * The presence of this function means that the standard templated 
williamr@2:      * operator>>() ( defined in s32strm.h ) is available to internalize objects 
williamr@2:      * of this class.
williamr@2:      *
williamr@2:      * @param[in] aStream Stream from which the object should be internalized.
williamr@2:      */
williamr@2:     IMPORT_C void InternalizeL( RReadStream& aStream );
williamr@2:     
williamr@2:     /**
williamr@2:      * Externalizes the trigger condition object's details and attributes
williamr@2:      * to stream.
williamr@2:      *
williamr@2:      * The presence of this function means that the standard templated 
williamr@2:      * operator<<() ( defined in s32strm.h ) is available to externalize objects 
williamr@2:      * of this class.
williamr@2:      *
williamr@2:      * @param[in] aStream Stream to which the object should be externalized.
williamr@2:      */
williamr@2:     IMPORT_C void ExternalizeL( RWriteStream& aStream ) const;
williamr@2:     
williamr@2: private:
williamr@2:     /**
williamr@2:      * Default Constructor.
williamr@2:      */
williamr@2:     CLbtListTriggerOptions();
williamr@2:     
williamr@2:     /**
williamr@2:      * By default, prohibit copy constructor
williamr@2:      */
williamr@2:     CLbtListTriggerOptions( const CLbtListTriggerOptions& );
williamr@2:     
williamr@2:     /**
williamr@2:      * Prohibit assigment operator
williamr@2:      */
williamr@2:     CLbtListTriggerOptions& operator= ( const CLbtListTriggerOptions& );
williamr@2:     
williamr@2:     /**
williamr@2:      * Symbian 2nd phase constructor
williamr@2:      */
williamr@2:     void ConstructL();
williamr@2:   
williamr@2: private:
williamr@2:     /**
williamr@2:      * Trigger entry fields mask
williamr@2:      */
williamr@2:     TLbtTriggerAttributeFieldsMask iTriigerAttributeFieldsMask;
williamr@2: 
williamr@2:     /**
williamr@2:      * Trigger dynamic information field mask
williamr@2:      */
williamr@2:     TLbtTriggerDynamicInfoFieldsMask  iDynInfoFieldsMask;
williamr@2: 
williamr@2:     /**
williamr@2:      * Filter
williamr@2:      */
williamr@2:     CLbtTriggerFilterBase* iFilter;
williamr@2: 
williamr@2:     /**
williamr@2:      * Sorting
williamr@2:      */
williamr@2:     TLbtListTriggerSorting iSorting;
williamr@2:     
williamr@2:     /**
williamr@2:      * Reserved
williamr@2:      */
williamr@2:     TUint iReserved[8];
williamr@2:     };
williamr@2: 
williamr@2: #endif // LBTLISTTRIGGEROPTIONS_H