diff -r 000000000000 -r 522cd55cc3d7 loc_plat/location_centre_api/inc/lclocationappfilter.h --- /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 + +/** + * @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