1 sensrvgeneralproperties.h

     1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  General properties definition file.

    15 *

    16 */

    17 

    18 

    19 #ifndef SENSRVGENERALPROPERTIES_H

    20 #define SENSRVGENERALPROPERTIES_H

    21 

    22 #include <e32base.h>

    23 #include <sensrvtypes.h>

    24 

    25 // PROPERTY TEMPLATE

    26 

    27 /*

    28 * The following is a template that must be used when defining new properties

    29 *

    30 * Property Name: Name of the property

    31 * Property Type: Defines type of the property (TInt/TReal/TBuf)

    32 * Scope: Defines a property scope. Property can be defined for a channel, for a specific

    33 * item in a channel or for a sensor related to a channel.

    34 * Mandatory: Defines is property mandatory

    35 * Capability: Capabilities needed to set this property

    36 * Description: Description of the property

    37 */

    38 

    39 // CONSTANTS

    40 

    41 /**

    42 * Property Name: Data Rate

    43 * Type:         TInt

    44 * Scope:        Channel property

    45 * Mandatory:    Yes

    46 * Capability:   None

    47 * Description:  Current data rate (Hz) of the sensor channel.

    48 *

    49 * A Sensor channel which supports data rates within a given range can use one Data Rate

    50 * property. The range is defined using the property's maximum and minimum value. E.g. A

    51 * sensor channel supports a data range from 10Hz to 100Hz and all values within this range

    52 * are feasible. To implement this use one Data Rate property with a minimum value 10 and a

    53 * maximum value of 100.

    54 *

    55 * A Sensor channel which supports discrete data rates can use the Data Rate property as

    56 * an array. E.g. A sensor channel supports the following data rates 10Hz, 40Hz and 50Hz.

    57 * To implement this four different Data Rate properties are needed. The following table

    58 * shows the content of the four properties, only mandatory attributes are shown.

    59 *

    60 * @code

    61 * property ID     Array index     Value           Min Value       Max Value       Read only

    62 * -----------     -----------     -----           ---------       ---------       ---------

    63 * 0x00000002      -2              1               0               2               EFalse

    64 * 0x00000002      0               10              n/a             n/a             ETrue

    65 * 0x00000002      1               40              n/a             n/a             ETrue

    66 * 0x00000002      2               50              n/a             n/a             ETrue

    67 * @endcode

    68 *

    69 * The first property (first row in table above) is the header for the property array. It

    70 * defines that this property is an array property. The attributes of this property are:

    71 *

    72 * Array index:

    73 * -2 means that the property is an array property

    74 * Value:

    75 * 1 means that current value of the property is defined by the property with an array index of

    76 * 1. The value is 40Hz in this example.

    77 * Min value

    78 * 0 is the start index of the property array

    79 * Max value:

    80 * 2 is the last index of the property array

    81 * Read only:

    82 * EFalse means that the properties current value can be changed,

    83 *

    84 * In this example the possible values of the property are 0, 1, and 2 which corresponds to data

    85 * rates of 10Hz, 40Hz and 50Hz.

    86 */

    87 const TSensrvPropertyId KSensrvPropIdDataRate = 0x00000002;

    88 

    89 /**

    90 * Name:         Power id property

    91 * Type:         TInt

    92 * Scope:        Channel item property

    93 * Mandatory:    No

    94 * Capability:   None

    95 * Description:  Power Property of the sensor

    96 *               Sensor power may either be down (ESensrvPowerPowerDown) or up (ESensrvPowerPowerUp).

    97 *               When sensor power is down, it's channels will also be unavailable.

    98 *               When sensor power is up, any given channel provided by the sensor may either be

    99 *               available or unavailable. The availability property represents channel's availability.

   100 *

   101 * @see          TSensrvPower.

   102 * @see          KSensrvPropIdAvailability

   103 */

   104 const TSensrvPropertyId KSensrvPropIdPower = 0x00000003;

   105 

   106 /**

   107 * Name: Availability

   108 * Type:         TInt.

   109 * Scope:        Channel property

   110 * Mandatory:    Yes

   111 * Capability:   None

   112 * Description:  Indicates if channel is available or not. There are channels

   113 *               supported by a sensor that cannot be opened at the same time.

   114 *               These so called dependant channnels are managed by client priorities.

   115 *               Availability property informs if a channel is available at the moment.

   116 *               Also, unavailable channel can be opened or be listened by client but

   117 *               the channel become functional after availability changes.

   118 *               Availability property values are defined in TSensrvAvailability

   119 *               as ESensrvAvailabilityFalse (not available) and ESensrvAvailabilityTrue

   120 *               (available).

   121 *

   122 * @see          TSensrvAvailability

   123 */

   124 const TSensrvPropertyId KSensrvPropIdAvailability = 0x00000004;

   125 

   126 /**

   127 * Name: Measure Range

   128 * Type: TReal or TInt

   129 * Scope: Channel item property

   130 * Mandatory: No

   131 * Capability: None

   132 * Description: The measure range of the sensor channel.

   133 *

   134 * The channel measure range is defined by the property's maximum and minimum values. The property

   135 * value represents the resolution of the measure range. The measure range property can also be

   136 * an array property.

   137 *

   138 * Example:

   139 *

   140 * An accelerometer xyz axis channel has a range of +/- 2g. Therefore the property would be a single

   141 * property, its type would be ESensrvIntProperty and its value would be 2.

   142 *

   143 * An orientation channel has a range of scalar integers representing the current orientation of

   144 * the mobile:  Undefined, Up, Down, Left, Right, Upward, Downward. Therefore the property would be an

   145 * array property (count of 8 made up of 1 header + 7 scalar values), its type would be

   146 * ESensrvIntProperty and the values of each member of the array would be one of the scalar values

   147 * above. For an example of an array property see KSensrvPropIdDataRate.

   148 *

   149 * A rotation channel has a range of 0-360 degrees. Therefore the property would be an array property

   150 * (count of 3 made up of 1 header + 1 min value + 1 max value), its type would be ESensrvIntProperty

   151 * and the values of each member of the array would be 0 and 360.

   152 *

   153 * The sensor specific channel header file for each channel found in epoc32\include\sensors\channels

   154 * will define the exact content of this property.

   155 *

   156 * @see ESensrvIntProperty

   157 * @see TSensrvArrayIndex

   158 * @see KSensrvPropIdDataRate

   159 */

   160 const TSensrvPropertyId KSensrvPropIdMeasureRange = 0x00000005;

   161 

   162 /**

   163 * Name: Format of the channel data

   164 * Type: TInt, see possible values from TSensrvChannelDataFormat

   165 * Scope: Channel item property

   166 * Mandatory: Yes

   167 * Capability: None

   168 * Description: A format which is used to present a data value.

   169 *

   170 * @see TSensrvChannelDataFormat

   171 */

   172 const TSensrvPropertyId KSensrvPropIdChannelDataFormat = 0x000000006;

   173 

   174 /**

   175 * Name:        Data item scaled range

   176 * Type:        TInt.

   177 * Scope:       Channel item property

   178 * Mandatory:   No

   179 * Capability:  None

   180 * Description: If the channel data is scaled it represents the scale of the returned data.

   181 *

   182 * The property value represents the minimum and maximum values of the scaled range. This property

   183 * should is used when the KSensrvPropIdChannelDataFormat property value is ESensrvFormatScaled.

   184 *

   185 * Example:

   186 *

   187 * An accelerometer xyz axis channel has a scaled range of -128 to 127. Therefore the property would

   188 * be an array property (count of 3 made up of 1 header + 1 min value + 1 max value), its type would

   189 * be ESensrvIntProperty and the values of each member of the array would be -128 and 127.

   190 *

   191 * If the accelerometer xyz axis channel also has a measure range of +/- 2g given by

   192 * KSensrvPropIdMeasureRange property. Then if a data value of 64 is read on one of the axis the g reading

   193 * would be approximately +1g.

   194 *

   195 * Rotation and orientation channels would have KSensrvPropIdChannelDataFormat set to

   196 * ESensrvChannelDataFormatAbsolute. Theerfore this property would not exist for these channels.

   197 *

   198 * The sensor specific channel header file for each channel found in epoc32\include\sensors\channels

   199 * will define the exact content of this property.

   200 *

   201 * @see KSensrvPropIdChannelDataFormat

   202 * @see KSensrvPropIdMeasureRange

   203 */

   204 const TSensrvPropertyId KSensrvPropIdScaledRange = 0x000000007;

   205 

   206 /**

   207 * Name: Accuracy of the channel data

   208 * Type: TReal

   209 * Scope: Channel item property

   210 * Mandatory: No

   211 * Capability: None

   212 * Description: The property value is the accuracy of the channel

   213 *

   214 * Example:

   215 *

   216 * An accelerometer xyz axis channel has an accuracy of +/-2mg. Therefore the property would be a

   217 * single property, its type would be ESensrvIntProperty and its value would be 2.

   218 *

   219 * An orientation channel has a range of scalar integers representing the current orientation of

   220 * the mobile and therefore has no accuracy associated with it. Therefore this property will not

   221 * exist for this channel.

   222 *

   223 * A rotation channel has an accuracy of the nearest 15 degrees. Therefore the property would be

   224 * a single property, its type would be ESensrvIntProperty and its value would be 15.

   225 *

   226 * The sensor specific channel header file for each channel found in epoc32\include\sensors\channels

   227 * will define the exact content of this property.

   228 *

   229 * @see ESensrvIntProperty

   230 */

   231 const TSensrvPropertyId KSensrvPropIdChannelAccuracy = 0x000000008;

   232 

   233 /**

   234 * Name: Channel Data Scale

   235 * Type: TInt

   236 * Scope: Channel item property

   237 * Mandatory: Mandatory when KSensrvPropIdChannelDataFormat is set to ESensrvFormatGeneral

   238 * Capability: None

   239 * Description: The property value is the scale used for the measurement provided by this channel.

   240 *

   241 * The scale can be used as a substitute for prefixing the unit. The scale is expressed as an

   242 * exponent of ten. If no scaling is needed, the scale MUST be zero.

   243 *

   244 * Either the unit or data values can be altered by the scaling factor. If, for example, the

   245 * unit is meter and the scale is -3, either the unit can be interpreted as "mm" or the data

   246 * value can be mulitplied by 10^(scale). i.e For a unit of Meter, a scale of -3 and a value of

   247 * 10 the value canbe interpreted as either 10mm, or 0.01 Meter

   248 *

   249 * If the data type of the channel is int this results in a fixed-point representation in which

   250 * the number of decimal places always remains the same. Using a fixed-point representation can

   251 * have a favorable effect on performance. With floating point data type, the scaling factor is

   252 * often used for convenience. With either very small, or very large values the presentation can

   253 * be more readable when the values are presented in moderate numbers.

   254 *

   255 * Channel data values and the KSensrvMeasureRange property must be represented using the same

   256 * scale.

   257 *

   258 * @see KSensrvPropIdChannelDataFormat

   259 */

   260 const TSensrvPropertyId KSensrvPropIdChannelScale = 0x000000009;

   261 

   262 /**

   263 * Name: Channel item unit

   264 * Type: TInt, see possible values from TSensrvChannelUnit

   265 * Scope: Channel item property

   266 * Mandatory: No

   267 * Capability: None

   268 * Description:  The property value is the unit, in which data values are presented.

   269 *

   270 * The recommended units are listed in TSensrvChannelUnit.

   271 *

   272 * @see TSensrvChannelUnit

   273 */

   274 const TSensrvPropertyId KSensrvPropIdChannelUnit = 0x0000000010;

   275 

   276 /**

   277 * Name:         Sensor model

   278 * Type:         Buffer

   279 * Scope:        Sensor property

   280 * Mandatory:    No

   281 * Capability:   None

   282 * Description: The property value is a sensor model description

   283 */

   284 const TSensrvPropertyId KSensrvSensorModel = 0x0000000011;

   285 

   286 /**

   287 * Name:         Sensor connection type

   288 * Type:         TInt.

   289 * Scope:        Sensor property

   290 * Mandatory:    No

   291 * Capability:   None

   292 * Description: Defines sensor connection type

   293 *

   294 * @see TSensrvConnectionType

   295 */

   296 const TSensrvPropertyId KSensrvSensorConnectionType = 0x0000000012;

   297 

   298 /**

   299 * Name: Sensor description

   300 * Type: Buffer

   301 * Scope: Sensor property

   302 * Mandatory: No

   303 * Capability: None

   304 * Description: The property value is a short description of the sensor

   305 *

   306 * If required this property can be used to hold a long description (>20 characters) of the sensor

   307 * by making it an array property. Each member of the array can hold part of the longer description.

   308 * Any framework client retrieving the property can then concatenate parts to make the full

   309 * description. The sensor specific headers found in epoc32\include\sensors\channels will define

   310 * whether this is a single property or an array property.

   311 */

   312 const TSensrvPropertyId KSensrvSensorDescription = 0x0000000013;

   313 

   314 /**

   315 * - Name:         Compensation type of channel data

   316 * - Type:         TInt, see possible values from TSensorCompensationType 

   317 *                 enumeration declared in sensordatacompensationtypes.h.

   318 * - Scope:        Channel property

   319 * - Mandatory:    No   

   320 * - Capability:   None

   321 * - Description:  Indicates channel data compensation type.

   322 */

   323 const TSensrvPropertyId KSensrvPropIdChannelDataCompensation = 0x0000000014;

   324 

   325 #endif //SENSRVGENERALPROPERTIES_H

   326 

   327 // End of File