When an application gets the value of a property, the value can
be converted by XMS into
another data type. There are a number of rules that govern which conversions
are supported and how XMS performs
the conversions.
A property of an object has a name and a value, where the value has an
associated data type. The data type of the value of a property is also referred
to as the property type.
An application uses the methods of the PropertyContext class to get and
set the properties of objects. In order to get the value of a property, an
application normally calls the method that is appropriate for the property
type. For example, to get the value of an integer property, an application
normally calls the Get Integer Property method.
However, when an application gets the value of a property, the value can
be converted by XMS into
another data type. For example, to get the value of an integer property, an
application can call the Get String Property method, which returns the value
of the property as a string. The conversions supported by XMS are
shown in Table 1.
Table 1. Supported conversions from a property type to other data typesProperty type |
Supported target data types |
String |
xmsBOOL, xmsDOUBLE, xmsFLOAT, xmsINT, xmsLONG, xmsSBYTE,
xmsSHORT |
xmsBOOL |
String, xmsSBYTE, xmsINT, xmsLONG, xmsSHORT |
xmsCHAR |
String |
xmsDOUBLE |
String |
xmsFLOAT |
String, xmsDOUBLE |
xmsINT |
String, xmsLONG |
xmsLONG |
String |
xmsSBYTE |
String, xmsINT, xmsLONG, xmsSHORT |
xmsSBYTE array |
String |
xmsSHORT |
String, xmsINT, xmsLONG |
The general rules governing the supported conversions are as follows:
- Numeric property values can be converted from one data type to another
provided no data is lost during the conversion. For example, the value of
a property with data type xmsINT can be converted into a value with data type
xmsLONG, but cannot be converted into a value with data type xmsSHORT.
- A property value of any data type can be converted into a string.
- A string property value can be converted to any other data type provided
the string is formatted correctly for the conversion. If an application attempts
to convert a string property value that is not formatted correctly, XMS returns
error code XMS_E_NUMBER_FORMAT_ERROR.
- If an application attempts a conversion that is not supported, XMS returns
error code XMS_E_TYPE_CONVERSION_FAILED.
The specific rules for converting a property value from one data type to
another are as follows:
- When converting a boolean property value to a string, the value xmsTRUE
is converted to the string "true", and the value false is converted to
the string "false".
- When converting a boolean property value to a numeric data type, including
xmsSBYTE, the value xmsTRUE is converted to 1, and the value xmsFALSE is converted
to 0.
- When converting a string property value to a boolean value, the string "true" (not
case sensitive) or "1" is converted to xmsTRUE, and the string "false" (not
case sensitive) or "0" is converted to xmsFALSE. Any other string cannot
be converted.
- When converting a string property value to a value with data type xmsINT,
xmsLONG, xmsSBYTE, or xmsSHORT, the string must have the following format:
The meanings of the components of the string are as follows:
- blanks
- Optional leading blank characters.
- sign
- An optional plus sign (+) or minus sign (-) character.
- digits
- A contiguous sequence of digit characters (0-9). At least one digit character
must be present.
After the sequence of digit characters, the string can contain
other characters that are not digit characters, but the conversion stops as
soon as the first of these characters is reached. The string is assumed to
represent a decimal integer.
XMS returns
error code XMS_E_NUMBER_FORMAT_ERROR if the string is not formatted correctly.
- When converting a string property value to a value with data type xmsDOUBLE
or xmsFLOAT, the string must have the following format:
- [blanks][sign]digits[e_char[e_sign]e_digits]
The meanings of the components of the string are as follows:- blanks
- Optional leading blank characters.
- sign
- An optional plus sign (+) or minus sign (-) character.
- digits
- A contiguous sequence of digit characters (0-9). At least one digit character
must be present.
- e_char
- An exponent character, which is either E or e.
- e_sign
- An optional plus sign (+) or minus sign (-) character for the exponent.
- e_digits
- A contiguous sequence of digit characters (0-9) for the exponent. At least
one digit character must be present if the string contains an exponent character.
After the sequence of digit characters, or the optional
characters representing an exponent, the string can contain other characters
that are not digit characters, but the conversion stops as soon as the first
of these characters is reached. The string is assumed to represent a decimal
floating point number with an exponent that is a power of 10.
XMS returns
error code XMS_E_NUMBER_FORMAT_ERROR if the string is not formatted correctly.
- When converting a numeric property value to a string, including a property
value with data type xmsSBYTE, the value is converted to the string representation
of the value as a decimal number, not the string containing the ASCII character
for that value. For example, the integer 65 is converted to the string "65",
not the string "A".
- When converting a byte array property value to a string, each byte is
converted to the 2 hexadecimal characters that represent the byte. For example,
the byte array {0xF1, 0x12, 0x00, 0xFF} is converted to the string "F11200FF".
Conversions from a property type to other data types are supported by the
methods of both the Property and the PropertyContext classes. However, the
C functions xmsPropertyGetStringByRef() and xmsGetStringPropertyByRef() make
no attempt to convert a property value that is not a string. If an application
calls either of these functions to get a pointer to a property value that
is not a string, XMS returns
error code XMS_E_TYPE_CONVERSION_FAILED.