epoc32/include/lbscriteria.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of "Eclipse Public License v1.0"
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    15 
    16 #ifndef __LBSCRITERIA_H__
    17 #define __LBSCRITERIA_H__
    18 
    19 #include <lbscommon.h>
    20 
    21 
    22 class TPositionSelectionOrder
    23 /**
    24 This class is used as part of the TPositionCriteria class to chose a
    25 positioning module that will provide the desired quality of information.
    26 It allows position-quality-metrics to be given priorities, enabling them
    27 to be given preference in the decision.
    28 
    29 @publishedAll
    30 @released
    31  */
    32 	{
    33 public:
    34 	/**
    35 	 Specifies the priority of selection parameters.
    36 	 */
    37 	enum TOrder
    38 		{
    39 		/** Don't care */
    40 		EOrderDontCare   = 0,
    41 		/** Default */
    42 		EOrderDefault    = 1,
    43 		/** Very low */
    44 		EOrderVeryLow    = 25,
    45 		/** Low */
    46 		EOrderLow        = 50,
    47 		/** Fairly low */
    48 		EOrderFairlyLow  = 75,
    49 		/** Medium */
    50 		EOrderMedium     = 100,
    51 		/** Fairly high */
    52 		EOrderFairlyHigh = 125,
    53 		/** High */
    54 		EOrderHigh       = 150,
    55 		/** Very high */
    56 		EOrderVeryHigh   = 175
    57 		};
    58 
    59 	/**
    60 	 Specifies the quality of position metrics that can be prioritized.
    61 	 */
    62 	enum TField
    63 		{
    64 		/** Time to first fix */
    65 		EFieldTimeToFirstFix,
    66 		/** Time to next fix */
    67 		EFieldTimeToNextFix,
    68 		/** Field Horizontal Accuracy */
    69 		EFieldHorizontalAccuracy,
    70 		/** Field Vertical Accuracy */
    71 		EFieldVerticalAccuracy,
    72 		/** Field cost */
    73 		EFieldCost,
    74 		/** Field power */
    75 		EFieldPower,
    76 		/** Number of fields */
    77 		EFieldNumFields,       // Do not use this value. Must appear after all other field values.
    78 		/** Last field */
    79 		EFieldLast = KMaxTInt8 // Do not use this value. Must appear at end.
    80 		};
    81 
    82 	IMPORT_C TPositionSelectionOrder();
    83 
    84 	IMPORT_C TInt SetOrderTimeToFirstFix(TOrder aOrder);
    85 	IMPORT_C TInt SetOrderTimeToNextFix(TOrder aOrder);
    86 
    87 	IMPORT_C TInt SetOrderHorizontalAccuracy(TOrder aOrder);
    88 	IMPORT_C TInt SetOrderVerticalAccuracy(TOrder aOrder);
    89 
    90 	IMPORT_C TInt SetOrderCostIndicator(TOrder aOrder);
    91 	IMPORT_C TInt SetOrderPowerConsumption(TOrder aOrder);
    92 
    93 	IMPORT_C void ResetSelectionOrder();
    94 	IMPORT_C void ClearSelectionOrder();
    95 
    96 	IMPORT_C TUint NumSelectionItems() const;
    97 	IMPORT_C TInt GetSelectionItem(TUint aIndex,
    98 	                               TField& aField,
    99 	                               TOrder& aOrder) const;
   100 
   101 protected:
   102 	struct SItem
   103 	/**
   104 	 Stores a field / priority pair.
   105 	 */
   106 		{
   107 		/** A position quality metric identifier. */
   108 		TField iField;
   109 		/** The priority given to the iField position quality metric. */
   110 		TOrder iOrder;
   111 		};
   112 
   113 protected:
   114 	/**
   115 	An internal method to add a selection criteria choice to the current set of
   116 	criteria.
   117 	 */
   118 	TInt AddItem(TField aField, TOrder aOrder);
   119 
   120 protected:
   121 	/** The number of selection items in the iItems array. */
   122 	TUint iNumItems;
   123 	/** Array of users position quality priorities. */
   124 	SItem iItems[KPositionMaxSectionFields];
   125 	};
   126 
   127 /**
   128 TPositionCriteriaBase derived classes class types
   129 // If the following line generates an error, too many fields have been added
   130 // to the TPositionSelectionOrder::TOrder enumeration, some must be removed
   131 // to maintain BC.
   132 @publishedAll
   133 @released
   134  */
   135 POSITION_COMPILE_TIME_ASSERT(TPositionSelectionOrder::EFieldNumFields <= KPositionMaxSectionFields);
   136 
   137 
   138 class TPositionCriteriaBase : public TPositionClassTypeBase
   139 /**
   140 The base class for classes used to store position module selection
   141 criteria information.
   142 
   143 @publishedAll
   144 @released
   145  */
   146 	{
   147 protected:
   148 	IMPORT_C TPositionCriteriaBase();
   149 	IMPORT_C TPositionCriteriaBase(TPositionModuleInfo::TCapabilities aCapabilityMask);
   150 
   151 public:
   152 	IMPORT_C void AddRequiredCapabilities(TPositionModuleInfo::TCapabilities aCapabilityMask);
   153 	IMPORT_C void ClearRequiredCapabilities();
   154 	IMPORT_C TPositionModuleInfo::TCapabilities RequiredCapabilities() const;
   155 
   156 	IMPORT_C void SetRequiredQuality(const TPositionQuality& aPosQuality);
   157 	IMPORT_C void GetRequiredQuality(TPositionQuality& aPosQuality) const;
   158 
   159 	IMPORT_C void SetSelectionOrder(const TPositionSelectionOrder& aSelectionOrder); 
   160 	IMPORT_C void GetSelectionOrder(TPositionSelectionOrder& aSelectionOrder) const;
   161 
   162 	IMPORT_C void ResetCriteria();
   163 	IMPORT_C void ClearCriteria();
   164 
   165 protected:
   166 	/** The capabilities a positioning module must have. */
   167 	TPositionModuleInfo::TCapabilities iRequiredCaps;
   168 	/** The quality required of a positioning module. */
   169 	TPositionQuality iRequiredQuality;
   170 	/** The priorities assigned to the various quality metrics. */
   171 	TPositionSelectionOrder	iSelectionOrder;
   172 	};
   173 
   174 
   175 class TPositionCriteria : public TPositionCriteriaBase
   176 /**
   177 The standard class criteria class for selecting a positioning module.
   178 
   179 @publishedAll
   180 @released
   181  */
   182 	{
   183 public:
   184 	IMPORT_C TPositionCriteria();
   185 	IMPORT_C TPositionCriteria(TPositionModuleInfo::TCapabilities aCapabilityMask);
   186 
   187 private:
   188 	/** Unused variable for future expansion. */
   189 	TUint8 iReserved[4];
   190 	};
   191 
   192 #endif // __LBSCRITERIA_H__