--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/loc_plat/location_centre_api/inc/lclocationappfilter.h Tue Feb 02 00:16:03 2010 +0200
@@ -0,0 +1,292 @@
+/*
+* 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