/*
* 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