diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/sensrvproperty.h --- a/epoc32/include/sensrvproperty.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/sensrvproperty.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,670 @@ -sensrvproperty.h +/* +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* 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 +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Sensor and channel property container +* +*/ + + +#ifndef SENSRVPROPERTY_H +#define SENSRVPROPERTY_H + +// INCLUDES +#include +#include + +// CONSTANTS + +/** +* Maximum size of the buffer when the property type is ESensrvBufferProperty +* @see TSensrvProperty +*/ +const TInt KSensrvPropertyTextBufferSize = 20; + + +// DATA TYPES + +/** +* Property types +* @see TSensrvProperty +*/ +enum TSensrvPropertyType + { + /** Default property type */ + ESensrvUninitializedProperty = 0, + /** Integer property type. TInt is used to store property value */ + ESensrvIntProperty, + /** Real property type. TReal is used to store property value */ + ESensrvRealProperty, + /** + Descriptor property type. TBuf is used to store + property value + */ + ESensrvBufferProperty + }; + +/** +* Special index types for iArrayIndex. Any other value indicates that this property is a member of +* an array of properties +* @see TSensrvProperty +*/ +enum TSensrvArrayIndex + { + /** This property is a single property and is not a member of an array of properties */ + ESensrvSingleProperty = -1, + /** + This property is the information item for an array of properties. iIntValueMin and iIntValueMax + values in a property of this type defines the range of the property array + */ + ESensrvArrayPropertyInfo = -2 + }; + +/** +* Identifies the range of values that must be used for TSensrvPropertyId. These ranges are defined so that +* any customers wishing to add additional properties not yet supported by Symbian can do so without +* causing clashes with Symbian defined properties. +* 1-4095 General channel properties owned and defined by Symbian +* 4096-8191 Specific Channel properties owned and defined by Symbian +* 8192-12287 A range for customers to define their own properties. Usage defined by customer +* @see TSensrvPropertyId +* @see TSensrvProperty +*/ +enum TSensrvPropertyRangeUsage + { + // General properties + ESensrvPropertyRangeNotDefined = 0, // 0x0000 + ESensrvGeneralPropertyRangeBase = 1, // 0x0001 + ESensrvGeneralPropertyRangeEnd = 4095, // 0x0FFF + + // Channel properties + ESensrvChannelPropertyRangeBase = 4096, // 0x1000 + ESensrvChannelPropertyRangeEnd = 8191, // 0x1FFF + + // A range for licensees to define their own properties. Usage is defined by the licensee. + ESensrvLicenseePropertyRangeBase = 8192, // 0x2000 + ESensrvLicenseePropertyRangeEnd = 12287 // 0x2FFF + }; + +/** +* Type definition for property identifier. +* @see TSensrvProperty +*/ +typedef TUint32 TSensrvPropertyId; + +// CLASS DECLARATION + +/** +* TSensrvProperty is a simple data class that contains sensor channel property information. The class has +* little behaviour and only does sanity checks where it is possible. It is therefore assumed that users of +* this class are aware of and conform to a properties definition for a given property identifier. +* +* There are 2 groups of properties, General Channel Properties and Specific Channel Properties. +* +* General Channel Properties are properties that are supported by all channels. These are defined in +* sensrvgeneralproperties.h. Specific Channel Properties are properties that are supported by specific +* channel types as required. These are defined in the relevant headers files. +* +* The property identifier uniquely identifies the property within a channel. These property ids must fall +* into the relevant range specified by TSensrvPropertyRangeUsage. Each property will have a constant +* defined for its identifier. e.g. KSensrvPropIdDataRate. +* +* @see TSensrvProperty::SetPropertyId() +* @see TSensrvProperty::GetPropertyId() +* @see TSensrvPropertyRangeUsage +* @see KSensrvPropIdDataRate +* +* The property type is used to determine whether the property is TInt, TReal or Buffer. The property type +* is automatically set when the value of the object is set. +* +* @see TSensrvPropertyType +* @see TSensrvProperty::PropertyType() +* +* The value fields are used to indicate the value of a property when the property contains a single int, +* real or buffer value. The min and max value fields are used when a property has a range of int or real +* values. A property cannot have a range of buffer values. The value and min/max values of a property +* will never be set at the same time. +* +* @see TSensrvProperty::GetValue() +* @see TSensrvProperty::SetValue() +* @see TSensrvProperty::GetValueRef() +* @see TSensrvProperty::GetMinValue() +* @see TSensrvProperty::SetMinValue() +* @see TSensrvProperty::GetMaxValue() +* @see TSensrvProperty::SetMaxValue() +* +* Properties can be read only which means it cannot be set by CSensrvChannel::SetPropertyL(). +* +* @see TSensrvProperty::ReadOnly() +* @see TSensrvProperty::SetReadOnly() +* @see CSensrvChannel +* +* Properties can either be single properties, or can be a member of an array of properties. The array +* index field is set to ESensrvSingleProperty(-1) if the property is single. If a property is part of an +* array then the array index field will be set to ESensrvArrayPropertyInfo(-2) or the index for the array. +* When the array index is ESensrvArrayPropertyInfo the property uses the iIntValueMin and iIntValueMax fields +* to indicate the range of the array. When the array index is an actual index (neither ESensrvArrayPropertyInfo +* nor ESensrvArrayPropertyInfo) the property contains data. +* +* Example: +* +* A Sensor channel which supports data rates within a given range can use one Data Rate +* property. The range is defined using the property's maximum and minimum value. E.g. A +* sensor channel supports a data range from 10Hz to 100Hz and all values within this range +* are feasible. To implement this use one Data Rate property with a minimum value 10 and a +* maximum value of 100. +* +* A Sensor channel which supports discrete data rates can use the Data Rate property as +* an array. E.g. A sensor channel supports the following data rates 10Hz, 40Hz and 50Hz. +* To implement this four different Data Rate properties are needed. The following table +* shows the content of the four properties, only mandatory attributes are shown. +* +* @code +* property ID Array index Value Min Value Max Value Read only +* ----------- ----------- ----- --------- --------- --------- +* 0x00000002 -2 1 0 2 EFalse +* 0x00000002 0 10 n/a n/a ETrue +* 0x00000002 1 40 n/a n/a ETrue +* 0x00000002 2 50 n/a n/a ETrue +* @endcode +* +* The first property (first row in table above) is the header for the property array. It +* defines that this property is an array property. The attributes of this property are: +* +* Array index: +* -2 means that the property is an array property +* Value: +* 1 means that current value of the property is defined by the property with an array index of +* 1. The value is 40Hz in this example. +* Min value +* 0 is the start index of the property array +* Max value: +* 2 is the last index of the property array +* Read only: +* EFalse means that the properties current value can be changed, +* +* In this example the possible values of the property are 0, 1, and 2 which corresponds to data +* rates of 10Hz, 40Hz and 50Hz. +* +* @see TSensrvArrayIndex +* @see TSensrvProperty::SetArrayIndex() +* @see TSensrvProperty::GetArraIndex() +* +* The property item index is used to identify a specific item in the channel data structure that the property +* refers to. For example the Accelerometer XYZ-axis data structure defines data for the x, y and Z axis. +* Individual properties could have been defined for each of these axis. Instead a single property is defined +* and the Item Index is used to identify the relevant axis in the channel data structure that the property +* applies to. The indexes for these specific items and the channel data structures themselves are defined in +* the sensor specific headers files found in epoc32\include\sensors\channels. +* +* Example: +* +* Accelerometer data definition. TSensrvAccelerometerAxisDataIndexes is used to provide an index that +* relates to each of the class fields. +* +* @code +* // ACCELEROMETER RELATED DATATYPES +* +* // Accelerometer axis data type +* +* class TSensrvAccelerometerAxisData +* { +* public: +* // +* // Channel data type Id number +* // +* static const TSensrvChannelDataTypeId KDataTypeId = 0x1020507E; +* +* // +* // Channel data type index numbers +* // +* enum TSensrvAccelerometerAxisDataIndexes +* { +* ETimeStamp = 0, +* EAxisX, +* EAxisY, +* EAxisZ +* }; +* public: +* // +* // - Item name: Sampling time. +* // - Item Index: 0 +* // - Conditions: None +* // - Description: Timestamp for a sample. +* // +* TTime iTimeStamp; +* +* // +* // - Item name: Accelerometer x-axis +* // - Item Index: 1 +* // - Conditions: Single limit and range +* // - Description: Accelerometer values from x-axis +* // +* TInt iAxisX; +* +* // +* // - Item name: Accelerometer y-axis +* // - Item Index: 2 +* // - Conditions: Single limit and range +* // - Description: Accelerometer values from y-axis +* // +* TInt iAxisY; +* +* // +* // - Item name: Accelerometer z-axis +* // - Item Index: 3 +* // - Conditions: Single limit and range +* // - Description: Accelerometer values from z-axis +* // +* TInt iAxisZ; +* }; +* @endcode +* +* @see TSensrvProperty::SetItemIndex() +* @see TSensrvProperty::PropertyItemIndex() +* @lib sensrvutil.lib +* @since S60 5.0 +*/ +NONSHARABLE_CLASS( TSensrvProperty ) + { +public: + + /** + Default Constructor + */ + IMPORT_C TSensrvProperty(); + + /** + * Constructor to create complete integer type property. + * + * @since S60 5.0 + * @param aPropertyId Id of the property + * @param aItemIndex Item index of the property. Mapped to a specific item in channel data structure. + * @param aValue Value of the property. + * @param aMaxValue Maximum value of the property + * @param aMinValue Minimum value of the property + * @param aReadOnly Readonly-flag of the property + * @param aPropertyType Type of the property + */ + IMPORT_C TSensrvProperty( const TSensrvPropertyId aPropertyId, + const TInt aItemIndex, + const TInt aValue, + const TInt aMaxValue, + const TInt aMinValue, + const TBool aReadOnly, + const TSensrvPropertyType aPropertyType ); + + /** + * Constructor to create property object for setting integer property value. + * + * @since S60 5.0 + * @param aPropertyId Id of the property + * @param aItemIndex Item index of the property. Mapped to a specific item in channel data structure. + * @param aValue Value of the property. + */ + IMPORT_C TSensrvProperty( const TSensrvPropertyId aPropertyId, + const TInt aItemIndex, + const TInt aValue ); + + /** + * Constructor to create complete TReal type of property. + * + * @since S60 5.0 + * @param aPropertyId Id of the property + * @param aItemIndex Item index of the property. Mapped to a specific item in channel data structure. + * @param aValue Value of the property. + * @param aMaxValue Maximum value of the property + * @param aMinValue Minimum value of the property + * @param aReadOnly Readonly-flag of the property + * @param aPropertyType Type of the property + */ + IMPORT_C TSensrvProperty( const TSensrvPropertyId aPropertyId, + const TInt aItemIndex, + const TReal aValue, + const TReal aMaxValue, + const TReal aMinValue, + const TBool aReadOnly, + const TSensrvPropertyType aPropertyType ); + + /** + * Constructor to create property object for setting real property value. + * + * @since S60 5.0 + * @param aPropertyId Id of the property + * @param aItemIndex Item index of the property. Mapped to a specific item in channel data structure. + * @param aValue Value of the property. + */ + IMPORT_C TSensrvProperty( const TSensrvPropertyId aPropertyId, + const TInt aItemIndex, + const TReal aValue ); + + /** + * Constructor to create complete buffer property. + * + * @since S60 5.0 + * @param aPropertyId Id of the property + * @param aItemIndex Item index of the property. Mapped to a specific item in channel data structure. + * @param aValue Value of the property. Max length is defined in KSensrvPropertyTextBufferSize. + * @param aReadOnly Readonly-flag of the property + * @param aPropertyType Type of the property + */ + IMPORT_C TSensrvProperty( const TSensrvPropertyId aPropertyId, + const TInt aItemIndex, + const TDesC8& aValue, + const TBool aReadOnly, + const TSensrvPropertyType aPropertyType ); + + /** + * Constructor to create property object for setting buffer property value. + * + * @since S60 5.0 + * @param aPropertyId Id of the property + * @param aItemIndex Item index of the property. Mapped to a specific item in channel data structure. + * @param aValue Value of the property. Max length is defined in KSensrvPropertyTextBufferSize. + */ + IMPORT_C TSensrvProperty( const TSensrvPropertyId aPropertyId, + const TInt aItemIndex, + const TDesC8& aValue ); + + /** + * Set the property Id for the property. + * + * @since S60 5.0 + * @param aPropertyId Property Id to be set. + */ + IMPORT_C void SetPropertyId( TSensrvPropertyId aPropertyId ); + + /** + * Return Property Id + * + * @since S60 5.0 + * @return Property Id + */ + IMPORT_C TSensrvPropertyId GetPropertyId() const; + + /** + * Set the property item index for the property. + * + * @since S60 5.0 + * @param aItemIndex property item index to be set. + */ + IMPORT_C void SetItemIndex( TInt aItemIndex ); + + /** + * Get the property item index number + * + * @since S60 5.0 + * @return Item index number. + */ + IMPORT_C TInt PropertyItemIndex() const; + + /** + * Return property type + * + * @since S60 5.0 + * @return Property type's Id + */ + IMPORT_C TSensrvPropertyType PropertyType() const; + + /** + * Checks if the property is readonly + * + * @since S60 5.0 + * @return ETrue value indicates that property is a read only property. + */ + IMPORT_C TBool ReadOnly() const; + + /** + * Set the readonly information for the property. + * + * @since S60 5.0 + * @param aReadOnly readonly information to be set. EFalse means that the property is not readonly. + */ + IMPORT_C void SetReadOnly( TBool aReadOnly ); + + /** + * Set integer property value + * + * @since S60 5.0 + * @param aValue Value to be set. + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetValue( const TInt aValue ); + + /** + * Set real property value + * + * @since S60 5.0 + * @param aValue Value to be set. + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetValue( const TReal aValue ); + + /** + * Set buffer property value + * + * @since S60 5.0 + * @param aValue Value to be set. + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetValue( const TDesC8& aValue ); + + /** + * Get integer property value + * + * @since S60 5.0 + * @param aValue Value to get + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetValue( TInt& aValue ) const; + + /** + * Get real property value + * + * @since S60 5.0 + * @param aValue Value to get + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetValue( TReal& aValue ) const; + + /** + * Get buffer property value + * + * @since S60 5.0 + * @param aValue Destination where a property value is to be copied + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetValue( TDes8& aValue ) const; + + /** + * Get reference to buffer property value + * + * @since S60 5.0 + * @return Reference to a property value + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C TDes8& GetValueRef(); + + /** + * Get property maximum value of integer property + * + * @since S60 5.0 + * @param aMaxValue Maximum value to get + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetMaxValue( TInt& aMaxValue ) const; + + /** + * Get property minimum value of integer property + * + * @since S60 5.0 + * @param aMinValue Minimum value to get + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetMinValue( TInt& aMinValue ) const; + + /** + * Set property maximum value of integer property + * + * @since S60 5.0 + * @param aMaxValue Maximum value to be set + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetMaxValue( TInt aMaxValue ); + + /** + * Set property minimum value of integer property + * + * @since S60 5.0 + * @param aMinValue Minimum value to be set + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetMinValue( TInt aMinValue ); + + /** + * Get property maximum value of real property + * + * @since S60 5.0 + * @param aMaxValue Maximum value to get + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetMaxValue( TReal& aMaxValue ) const; + + /** + * Get property minimum value of real property + * + * @since S60 5.0 + * @param aMinValue Minimum value to get + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void GetMinValue( TReal& aMinValue ) const; + + /** + * Set property maximum value of real property + * + * @since S60 5.0 + * @param aMaxValue Maximum value to be set. + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetMaxValue( const TReal& aMaxValue ); + + /** + * Set property minimum value of real property + * + * @since S60 5.0 + * @param aMinValue Minimum value to be set. + * @panic KSensrvPanicCategory ESensrvPanicInvalidPropertyType Panic if the property object is not + * a correct type + */ + IMPORT_C void SetMinValue( const TReal& aMinValue ); + + /** + * Set security info of the property. This should be set to the Security info for the client process + * + * @since S60 5.0 + * @param aSecurityInfo Security info to be set + */ + IMPORT_C void SetSecurityInfo( const TSecurityInfo& aSecurityInfo ); + + /** + * Get security info of the property + * + * @since S60 5.0 + * @return Security info of the property + */ + IMPORT_C TSecurityInfo GetSecurityInfo() const; + + /** + * Set array index of the property. + * + * @since S60 5.0 + * @param aArrayIndex Array index to be set + * @see TSensrvArrayIndex + * @see KSensrvPropIdDataRate for an example + */ + IMPORT_C void SetArrayIndex( const TInt aArrayIndex ); + + /** + * Get array index of the property + * + * @since S60 5.0 + * @return Array index of the property. + * @see TSensrvArrayIndex + * @see KSensrvPropIdDataRate for an example + */ + IMPORT_C TInt GetArrayIndex() const; + +private: + // property identifier + TSensrvPropertyId iPropertyId; + + // property item index + TInt iItemIndex; + + //Array index + TInt16 iArrayIndex; + + + // property value + union + { + TInt iIntValue; + TReal iRealValue; + }; + TBuf8 iBufValue; + + // read only flag + TBitFlags32 iFlags; + + // maximum value + union + { + TInt iIntValueMax; + TReal iRealValueMax; + }; + + // minimum value + union + { + TInt iIntValueMin; + TReal iRealValueMin; + }; + + // property type + TSensrvPropertyType iPropertyType; + + // property security infomation + TSecurityInfo iSecurityInfo; + + // not used + TInt iReserved; + }; + +#endif //SENSRVPROPERTY_H + +// End of File + +