/*
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Location Application Filters
*
*/
#ifndef T_LCLOCATIONAPPFILTER_H
#define T_LCLOCATIONAPPFILTER_H
/**
* @file lclocationappfilter.h
*
* This file provides the filters which can be used to customize the list
* of Location based Application which can be retrieved from Location Centre
* or which can be displayed in Location Centre.
*
* @note The components which can register with Location Centre are of
* two types
* - Applications
* - Location based services / contents.
*
* These Client Applications or Services/Contents which register with Location
* Centre will be called Location based Application henceforth.
*
* @lib lcservice.lib
* @since S60 5.0
*/
// SYSTEM INCLUDES
#include <e32base.h>
/**
* @class TLcLocationAppFilter
* Location Application Filter.
*
* This class allows the client application to configure the list of Location
* based Applications that the client intends to obtain from Location Centre
* or the list of Location based Application that the client application wants
* Location Centre to show.
* The filtering is based on characteristics exhibited by the Location based
* Applications. These characteristics can be of two types
* - System Characteristics defined by
* @ref CLcLocationAppInfo::TLcSystemCharacteristics and
* - Application Characteristics defined by
* @ref CLcLocationAppInfo::TLcApplicationCharacteristics.
*
* The default state of the filter class for various property is
* - System Characteristics is @ref TLcSystemCharacteristics::ESysCharNone
* - System Characteristic filter configuration is @ref EFilterStrict
* - Application Characteristic is @ref TLcApplicationCharacteristics::EAppCharNone
* - Application Characteristic filter configuration is @ref EFilterStrict
*
* This class is expected to be is passed as an input argument to the
* @p GetLocationApplicationsL, @p GetLocationApplications and
* @p LaunchLocationCentreL functions of @ref CLcService class.
*
* @see CLcService::GetLocationApplicationsL
* @see CLcService::GetLocationApplications
* @see CLcService::LaunchLocationCentreL
*
* @lib lcservice.lib
* @since S60 v5.0
*/
class TLcLocationAppFilter
{
public:
/**
* @enum TLcFilterConfig
* The mode in which the application filtering should be done.
* This enumeration is used by the client application to specify the way
* in which filtering of applications should be done.
*/
enum TLcFilterConfig
{
/**
* Location based Application that exhibit only the characteristics
* specified by the client applications must be used. If the
* System / Application characteristics stored in this object
* contains a bitmask of more than one characteristic, then only
* those Location based Application which satisfy all the mentioned
* characteristics will be considered for filtering.
* These characteristics are specified by the enumerations
* @ref CLcLocationAppInfo::TLcSystemCharacteristics and
* @ref CLcLocationAppInfo::TLcApplicationCharacteristics
*/
EFilterStrict = 0,
/**
* Applications that exhibit only the characteristics specified by
* the client application alone or other characteristics in-addition
* to the specified ones will be used for processing. If the
* System / Application characteristics stored in this object
* contains a bitmask of more than one characteristic, then
* only those Location based Applications which satisfy all the
* mentioned characteristics in addtion to optionally satisfying
* other characteristics will be considered for filetering.
* These characteristics are specified by the enumerations
* @ref CLcLocationAppInfo::TLcSystemCharacteristics and
* @ref CLcLocationAppInfo::TLcApplicationCharacteristics
*/
EFilterInclusive = 1,
/**
* Location based Application that exhibit characteristics other than
* those specified by the client application must be used. If the
* System / Application characteristics stored in this object
* contains a bitmask of more than one characteristic, then only
* Location based Application which do not satisfy any of the
* mentioned characteristics will be considered for filtering.
* These characteristics are specified by the enumerations
* @ref CLcLocationAppInfo::TLcSystemCharacteristics and
* @ref CLcLocationAppInfo::TLcApplicationCharacteristics
*/
EFilterExclusive = 2
};
public: // Exported Member Functions
/**
* Default Constructor
*/
IMPORT_C TLcLocationAppFilter();
/**
* Accessor function which returns the currently configured System
* characteristics which will be used for filtering. All the system
* characteristics would be combined to form an integer bit-mask and
* this function retrieves the current bit-mask. The individual system
* characteristics are defined by
* @ref CLcLocationAppInfo::TLcSystemCharacteristics enumeration.
*
* @note If the current configuration of the system characteristics is
* the default value @ref CLcLocationAppInfo::ESysCharNone,
* then it should not be treated as a bit-mask but as an independent
* value alone.
*
* @since S60 5.0
* @return Bit-mask holding the currently enabled System characteristics.
*/
IMPORT_C TUint32 SystemCharacteristics() const;
/**
* Sets the requested system characteristic to the filter.
*
* All the system characteristics which the Client application intends
* to be used for filtering must be combined to form a bit-mask
* and this value is set to the filter.
* The individual system characteristics are defined by
* @ref CLcLocationAppInfo::TLcSystemCharacteristics enumeration.
*
* @since S60 5.0
* @param[in] aSystemChar System Characteristic bit-mask value.
* @return KErrArgument If the value of the input parameter is
* if its not a valid mask.
*/
IMPORT_C TInt SetSystemCharacteristic( TUint32 aSystemChar );
/**
* Retrieves the current value of the System characteristics filter option.
* The value of the filter is defined by the @ref TLcFilterConfig
* enumeration.
*
* @since S60 5.0
* @return Current System characteristics filter configuration.
*/
IMPORT_C TLcFilterConfig SysCharFilterConfiguration() const;
/**
* Sets the filter configuration option for system characteristics.
* Location centre can be configured to treat the System
* characteristics value based upon this flag.
*
* @since S60 5.0
* @param[in] aFilterConfig The mode in which the System characteristics
* value must be treated. The values which this
* variable can assume is defined by the
* @ref TLcFilterConfig enumeration.
*/
IMPORT_C void SetSysCharFilterConfiguration(
TLcFilterConfig aFilterConfig );
/**
* Accessor function which returns the currently configured Application
* characteristics which will be used for filtering. All the application
* characteristics would be combined to form an integer bit-mask and
* this function retrieves the current bit-mask. The individual application
* characteristics are defined by
* @ref CLcLocationAppInfo::TLcApplicationCharacteristics enumeration.
*
* @note If the current configuration of the application characteristics
* is the default value @ref EAppCharNone, then it should not be
* treated as a bit-mask but as an independent value alone.
*
* @since S60 5.0
* @return Bit-mask holding the currently enabled System
* characteristics.
*/
IMPORT_C TUint32 ApplicationCharacteristics() const;
/**
* Sets the requested Application characteristic to the filter.
*
* All the Application characteristics which the Client application
* intends to be used for filtering must be combined to form a bit-mask
* and this value is set to the filter.
* The individual system characteristics are defined by
* @ref CLcLocationAppInfo::TLcApplicationCharacteristics enumeration.
*
* @since S60 5.0
* @param[in] aAppChar Application Characteristic bit-mask value.
* @return KErrArgument If the value of the input parameter is
* if its not a valid mask.
*/
IMPORT_C TInt SetApplicationCharacteristics( TUint32 aAppChar );
/**
* Retrieves the current value of the Application characteristics
* filter option. The value of the filter is defined by the
* @ref TLcFilterConfig enumeration.
*
* @return Current Application characteristics filter configuration.
*/
IMPORT_C TLcFilterConfig AppCharFilterConfiguration() const;
/**
* Sets the filter configuration option for application characteristics.
* Location centre can be configured to treat the Application
* characteristics value based upon this flag.
*
* @since S60 5.0
* @param[in] aFilterConfig The mode in which the Application
* characteristics value must be treated. The
* values which this variable can assume is
* defined by the @ref TLcFilterConfig
* enumeration.
*/
IMPORT_C void SetAppCharFilterConfiguration(
TLcFilterConfig aFilterConfig );
private: // Data
/**
* System characteristics which must be used for Filtering Location
* applications. This variable contains a Bitmask of the enumeration
* CLcLocationAppInfo::TLcSystemCharacteristics.
* If the Client application decides to set the default value or
* doesn't explicitly initialize this variable then the value used
* would be ESysCharNone.
*/
TUint32 iSystemChar;
/**
* Filtering option for System Characteristics.
* If the client application decides to use the default value for this
* filter then then value used would be EFilterStrict.
*/
TLcFilterConfig iSysFilterConfig;
/**
* Application characteristics which must be used for Filtering Location
* applications. This variable contains a Bitmask of the enumeration
* CLcLocationAppInfo::TLcApplicationCharacteristics.
* If the Client application decides to set the default value or
* doesn't explicitly initialize this variable then the value used
* would be EAppCharNone.
*/
TUint32 iApplicationChar;
/**
* Filtering option for Application Characteristics.
* If the client application decides to use the default value for this
* filter then then value used would be EFilterStrict.
*/
TLcFilterConfig iAppFilterConfig;
/**
* Reserved for future use.
*/
TUint8 iReserved[8];
};
#endif // T_LCLOCATIONAPPFILTER_H