williamr@2: /*
williamr@2: * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  General properties definition file.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef SENSRVGENERALPROPERTIES_H
williamr@2: #define SENSRVGENERALPROPERTIES_H
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <sensrvtypes.h>
williamr@2: 
williamr@2: // PROPERTY TEMPLATE
williamr@2: 
williamr@2: /*
williamr@2: * The following is a template that must be used when defining new properties
williamr@2: *
williamr@2: * Property Name: Name of the property
williamr@2: * Property Type: Defines type of the property (TInt/TReal/TBuf)
williamr@2: * Scope: Defines a property scope. Property can be defined for a channel, for a specific
williamr@2: * item in a channel or for a sensor related to a channel.
williamr@2: * Mandatory: Defines is property mandatory
williamr@2: * Capability: Capabilities needed to set this property
williamr@2: * Description: Description of the property
williamr@2: */
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: 
williamr@2: /**
williamr@2: * Property Name: Data Rate
williamr@2: * Type:         TInt
williamr@2: * Scope:        Channel property
williamr@2: * Mandatory:    Yes
williamr@2: * Capability:   None
williamr@2: * Description:  Current data rate (Hz) of the sensor channel.
williamr@2: *
williamr@2: * A Sensor channel which supports data rates within a given range can use one Data Rate
williamr@2: * property. The range is defined using the property's maximum and minimum value. E.g. A
williamr@2: * sensor channel supports a data range from 10Hz to 100Hz and all values within this range
williamr@2: * are feasible. To implement this use one Data Rate property with a minimum value 10 and a
williamr@2: * maximum value of 100.
williamr@2: *
williamr@2: * A Sensor channel which supports discrete data rates can use the Data Rate property as
williamr@2: * an array. E.g. A sensor channel supports the following data rates 10Hz, 40Hz and 50Hz.
williamr@2: * To implement this four different Data Rate properties are needed. The following table
williamr@2: * shows the content of the four properties, only mandatory attributes are shown.
williamr@2: *
williamr@2: * @code
williamr@2: * property ID     Array index     Value           Min Value       Max Value       Read only
williamr@2: * -----------     -----------     -----           ---------       ---------       ---------
williamr@2: * 0x00000002      -2              1               0               2               EFalse
williamr@2: * 0x00000002      0               10              n/a             n/a             ETrue
williamr@2: * 0x00000002      1               40              n/a             n/a             ETrue
williamr@2: * 0x00000002      2               50              n/a             n/a             ETrue
williamr@2: * @endcode
williamr@2: *
williamr@2: * The first property (first row in table above) is the header for the property array. It
williamr@2: * defines that this property is an array property. The attributes of this property are:
williamr@2: *
williamr@2: * Array index:
williamr@2: * -2 means that the property is an array property
williamr@2: * Value:
williamr@2: * 1 means that current value of the property is defined by the property with an array index of
williamr@2: * 1. The value is 40Hz in this example.
williamr@2: * Min value
williamr@2: * 0 is the start index of the property array
williamr@2: * Max value:
williamr@2: * 2 is the last index of the property array
williamr@2: * Read only:
williamr@2: * EFalse means that the properties current value can be changed,
williamr@2: *
williamr@2: * In this example the possible values of the property are 0, 1, and 2 which corresponds to data
williamr@2: * rates of 10Hz, 40Hz and 50Hz.
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdDataRate = 0x00000002;
williamr@2: 
williamr@2: /**
williamr@2: * Name:         Power id property
williamr@2: * Type:         TInt
williamr@2: * Scope:        Channel item property
williamr@2: * Mandatory:    No
williamr@2: * Capability:   None
williamr@2: * Description:  Power Property of the sensor
williamr@2: *               Sensor power may either be down (ESensrvPowerPowerDown) or up (ESensrvPowerPowerUp).
williamr@2: *               When sensor power is down, it's channels will also be unavailable.
williamr@2: *               When sensor power is up, any given channel provided by the sensor may either be
williamr@2: *               available or unavailable. The availability property represents channel's availability.
williamr@2: *
williamr@2: * @see          TSensrvPower.
williamr@2: * @see          KSensrvPropIdAvailability
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdPower = 0x00000003;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Availability
williamr@2: * Type:         TInt.
williamr@2: * Scope:        Channel property
williamr@2: * Mandatory:    Yes
williamr@2: * Capability:   None
williamr@2: * Description:  Indicates if channel is available or not. There are channels
williamr@2: *               supported by a sensor that cannot be opened at the same time.
williamr@2: *               These so called dependant channnels are managed by client priorities.
williamr@2: *               Availability property informs if a channel is available at the moment.
williamr@2: *               Also, unavailable channel can be opened or be listened by client but
williamr@2: *               the channel become functional after availability changes.
williamr@2: *               Availability property values are defined in TSensrvAvailability
williamr@2: *               as ESensrvAvailabilityFalse (not available) and ESensrvAvailabilityTrue
williamr@2: *               (available).
williamr@2: *
williamr@2: * @see          TSensrvAvailability
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdAvailability = 0x00000004;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Measure Range
williamr@2: * Type: TReal or TInt
williamr@2: * Scope: Channel item property
williamr@2: * Mandatory: No
williamr@2: * Capability: None
williamr@2: * Description: The measure range of the sensor channel.
williamr@2: *
williamr@2: * The channel measure range is defined by the property's maximum and minimum values. The property
williamr@2: * value represents the resolution of the measure range. The measure range property can also be
williamr@2: * an array property.
williamr@2: *
williamr@2: * Example:
williamr@2: *
williamr@2: * An accelerometer xyz axis channel has a range of +/- 2g. Therefore the property would be a single
williamr@2: * property, its type would be ESensrvIntProperty and its value would be 2.
williamr@2: *
williamr@2: * An orientation channel has a range of scalar integers representing the current orientation of
williamr@2: * the mobile:  Undefined, Up, Down, Left, Right, Upward, Downward. Therefore the property would be an
williamr@2: * array property (count of 8 made up of 1 header + 7 scalar values), its type would be
williamr@2: * ESensrvIntProperty and the values of each member of the array would be one of the scalar values
williamr@2: * above. For an example of an array property see KSensrvPropIdDataRate.
williamr@2: *
williamr@2: * A rotation channel has a range of 0-360 degrees. Therefore the property would be an array property
williamr@2: * (count of 3 made up of 1 header + 1 min value + 1 max value), its type would be ESensrvIntProperty
williamr@2: * and the values of each member of the array would be 0 and 360.
williamr@2: *
williamr@2: * The sensor specific channel header file for each channel found in epoc32\include\sensors\channels
williamr@2: * will define the exact content of this property.
williamr@2: *
williamr@2: * @see ESensrvIntProperty
williamr@2: * @see TSensrvArrayIndex
williamr@2: * @see KSensrvPropIdDataRate
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdMeasureRange = 0x00000005;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Format of the channel data
williamr@2: * Type: TInt, see possible values from TSensrvChannelDataFormat
williamr@2: * Scope: Channel item property
williamr@2: * Mandatory: Yes
williamr@2: * Capability: None
williamr@2: * Description: A format which is used to present a data value.
williamr@2: *
williamr@2: * @see TSensrvChannelDataFormat
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdChannelDataFormat = 0x000000006;
williamr@2: 
williamr@2: /**
williamr@2: * Name:        Data item scaled range
williamr@2: * Type:        TInt.
williamr@2: * Scope:       Channel item property
williamr@2: * Mandatory:   No
williamr@2: * Capability:  None
williamr@2: * Description: If the channel data is scaled it represents the scale of the returned data.
williamr@2: *
williamr@2: * The property value represents the minimum and maximum values of the scaled range. This property
williamr@2: * should is used when the KSensrvPropIdChannelDataFormat property value is ESensrvFormatScaled.
williamr@2: *
williamr@2: * Example:
williamr@2: *
williamr@2: * An accelerometer xyz axis channel has a scaled range of -128 to 127. Therefore the property would
williamr@2: * be an array property (count of 3 made up of 1 header + 1 min value + 1 max value), its type would
williamr@2: * be ESensrvIntProperty and the values of each member of the array would be -128 and 127.
williamr@2: *
williamr@2: * If the accelerometer xyz axis channel also has a measure range of +/- 2g given by
williamr@2: * KSensrvPropIdMeasureRange property. Then if a data value of 64 is read on one of the axis the g reading
williamr@2: * would be approximately +1g.
williamr@2: *
williamr@2: * Rotation and orientation channels would have KSensrvPropIdChannelDataFormat set to
williamr@2: * ESensrvChannelDataFormatAbsolute. Theerfore this property would not exist for these channels.
williamr@2: *
williamr@2: * The sensor specific channel header file for each channel found in epoc32\include\sensors\channels
williamr@2: * will define the exact content of this property.
williamr@2: *
williamr@2: * @see KSensrvPropIdChannelDataFormat
williamr@2: * @see KSensrvPropIdMeasureRange
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdScaledRange = 0x000000007;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Accuracy of the channel data
williamr@2: * Type: TReal
williamr@2: * Scope: Channel item property
williamr@2: * Mandatory: No
williamr@2: * Capability: None
williamr@2: * Description: The property value is the accuracy of the channel
williamr@2: *
williamr@2: * Example:
williamr@2: *
williamr@2: * An accelerometer xyz axis channel has an accuracy of +/-2mg. Therefore the property would be a
williamr@2: * single property, its type would be ESensrvIntProperty and its value would be 2.
williamr@2: *
williamr@2: * An orientation channel has a range of scalar integers representing the current orientation of
williamr@2: * the mobile and therefore has no accuracy associated with it. Therefore this property will not
williamr@2: * exist for this channel.
williamr@2: *
williamr@2: * A rotation channel has an accuracy of the nearest 15 degrees. Therefore the property would be
williamr@2: * a single property, its type would be ESensrvIntProperty and its value would be 15.
williamr@2: *
williamr@2: * The sensor specific channel header file for each channel found in epoc32\include\sensors\channels
williamr@2: * will define the exact content of this property.
williamr@2: *
williamr@2: * @see ESensrvIntProperty
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdChannelAccuracy = 0x000000008;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Channel Data Scale
williamr@2: * Type: TInt
williamr@2: * Scope: Channel item property
williamr@2: * Mandatory: Mandatory when KSensrvPropIdChannelDataFormat is set to ESensrvFormatGeneral
williamr@2: * Capability: None
williamr@2: * Description: The property value is the scale used for the measurement provided by this channel.
williamr@2: *
williamr@2: * The scale can be used as a substitute for prefixing the unit. The scale is expressed as an
williamr@2: * exponent of ten. If no scaling is needed, the scale MUST be zero.
williamr@2: *
williamr@2: * Either the unit or data values can be altered by the scaling factor. If, for example, the
williamr@2: * unit is meter and the scale is -3, either the unit can be interpreted as "mm" or the data
williamr@2: * value can be mulitplied by 10^(scale). i.e For a unit of Meter, a scale of -3 and a value of
williamr@2: * 10 the value canbe interpreted as either 10mm, or 0.01 Meter
williamr@2: *
williamr@2: * If the data type of the channel is int this results in a fixed-point representation in which
williamr@2: * the number of decimal places always remains the same. Using a fixed-point representation can
williamr@2: * have a favorable effect on performance. With floating point data type, the scaling factor is
williamr@2: * often used for convenience. With either very small, or very large values the presentation can
williamr@2: * be more readable when the values are presented in moderate numbers.
williamr@2: *
williamr@2: * Channel data values and the KSensrvMeasureRange property must be represented using the same
williamr@2: * scale.
williamr@2: *
williamr@2: * @see KSensrvPropIdChannelDataFormat
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdChannelScale = 0x000000009;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Channel item unit
williamr@2: * Type: TInt, see possible values from TSensrvChannelUnit
williamr@2: * Scope: Channel item property
williamr@2: * Mandatory: No
williamr@2: * Capability: None
williamr@2: * Description:  The property value is the unit, in which data values are presented.
williamr@2: *
williamr@2: * The recommended units are listed in TSensrvChannelUnit.
williamr@2: *
williamr@2: * @see TSensrvChannelUnit
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdChannelUnit = 0x0000000010;
williamr@2: 
williamr@2: /**
williamr@2: * Name:         Sensor model
williamr@2: * Type:         Buffer
williamr@2: * Scope:        Sensor property
williamr@2: * Mandatory:    No
williamr@2: * Capability:   None
williamr@2: * Description: The property value is a sensor model description
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvSensorModel = 0x0000000011;
williamr@2: 
williamr@2: /**
williamr@2: * Name:         Sensor connection type
williamr@2: * Type:         TInt.
williamr@2: * Scope:        Sensor property
williamr@2: * Mandatory:    No
williamr@2: * Capability:   None
williamr@2: * Description: Defines sensor connection type
williamr@2: *
williamr@2: * @see TSensrvConnectionType
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvSensorConnectionType = 0x0000000012;
williamr@2: 
williamr@2: /**
williamr@2: * Name: Sensor description
williamr@2: * Type: Buffer
williamr@2: * Scope: Sensor property
williamr@2: * Mandatory: No
williamr@2: * Capability: None
williamr@2: * Description: The property value is a short description of the sensor
williamr@2: *
williamr@2: * If required this property can be used to hold a long description (>20 characters) of the sensor
williamr@2: * by making it an array property. Each member of the array can hold part of the longer description.
williamr@2: * Any framework client retrieving the property can then concatenate parts to make the full
williamr@2: * description. The sensor specific headers found in epoc32\include\sensors\channels will define
williamr@2: * whether this is a single property or an array property.
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvSensorDescription = 0x0000000013;
williamr@2: 
williamr@2: /**
williamr@2: * - Name:         Compensation type of channel data
williamr@2: * - Type:         TInt, see possible values from TSensorCompensationType 
williamr@2: *                 enumeration declared in sensordatacompensationtypes.h.
williamr@2: * - Scope:        Channel property
williamr@2: * - Mandatory:    No   
williamr@2: * - Capability:   None
williamr@2: * - Description:  Indicates channel data compensation type.
williamr@2: */
williamr@2: const TSensrvPropertyId KSensrvPropIdChannelDataCompensation = 0x0000000014;
williamr@2: 
williamr@2: #endif //SENSRVGENERALPROPERTIES_H
williamr@2: 
williamr@2: // End of File