アプリケーションがプロパティーの値を取得するときに、
XMS によりこの値のデータ型を別のデータ型に変換できます。サポートされる変換と、XMS による変換実行方法を制御するルールが多数あります。
オブジェクトのプロパティーには名前と値が指定されており、値には関連付けられたデータ型があります。プロパティー値のデータ型は、プロパティー・タイプとも呼ばれます。
アプリケーションは、PropertyContext クラスのメソッドを使用してオブジェクトのプロパティーを取得および設定します。プロパティー値を取得するため、アプリケーションは一般にプロパティー・タイプに対応したメソッドを呼び出します。例えば、整数プロパティーの値を取得する場合、アプリケーションは一般に Get Integer Property メソッドを呼び出します。
ただし、アプリケーションがプロパティーの値を取得する際に、
XMS によりこの値のデータ型を別のデータ型に変換できます。例えば、整数プロパティーの値を取得する場合、一般にアプリケーションは、プロパティーの値をストリングとして戻す Get String Property メソッドを呼び出すことができます。XMS でサポートされている変換を
表 1 に示します。
表 1. サポートされるプロパティー値のデータ型の変換プロパティー・タイプ |
サポートされるターゲット・データ型 |
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 配列 |
String |
xmsSHORT |
String、xmsINT、xmsLONG |
サポートされる変換を制御する一般的なルールを以下に示します。
- 変換中にデータが失われない限り、数値プロパティー値のデータ型を変換できます。例えば、データ型 xmsINT のプロパティーの値を、データ型
xmsLONG の値に変換できますが、データ型 xmsSHORT の値には変換できません。
- すべてのデータ型のプロパティー値をストリングに変換できます。
- ストリングが変換向けに正しい形式である限り、ストリング・プロパティー値は任意のデータ型に変換できます。正しくない形式のストリング・プロパティー値をアプリケーションが変換しようとすると、XMS からエラー・コード XMS_E_NUMBER_FORMAT_ERROR が戻されます。
- アプリケーションがサポートされていない変換を実行しようとすると、XMS から
エラー・コード XMS_E_TYPE_CONVERSION_FAILED が戻されます。
プロパティー値のデータ型の変換に関する特定のルールを以下に示します。
- ブール・プロパティー値をストリングに変換すると、値 xmsTRUE はストリング「true」に、xmsFALSE はストリング「false」に変換されます。
- ブール・プロパティー値を数値データ型 (xmsSBYTE を含む) に変換すると、値 xmsTRUE は 1 に、値 xmsFALSE は 0 に変換されます。
- ストリング・プロパティー値をブール値に変換すると、ストリング「true」(大/小文字の区別なし) または「1」が xmsTRUE に、ストリング「false」(大/小文字の区別なし) または「0」がxmsFALSE に変換されます。 その他のストリングは変換できません。
- ストリング・プロパティー値をデータ型 xmsINT、xmsLONG、xmsSBYTE、または xmsSHORT の値に変換する場合、変換するストリングは以下の形式でなければなりません。
ストリングの各部分の意味を以下に示します。
- blanks
- 先行ブランク文字 (オプション)。
- sign
- 正符号 (+) または負符号 (-) 文字 (オプション)。
- digits
- 数字 (0 から 9) の連続シーケンス。少なくとも 1 つの数字が必要です。
ストリングの数字シーケンスの後には、数字ではない文字を含めることができますが、数字以外の最初の文字に達した時点で変換が停止します。ストリングは 10 進数の整数値を表現していることを前提としています。
ストリングの形式が正しくないと、XMS からエラー・コード XMS_E_NUMBER_FORMAT_ERROR が戻されます。
- ストリング・プロパティー値をデータ型 xmsDOUBLE または xmsFLOAT の値に変換する場合、このストリングは以下の形式でなければなりません。
- [blanks][sign]digits[e_char[e_sign]e_digits]
ストリングの各部分の意味を以下に示します。- blanks
- 先行ブランク文字 (オプション)。
- sign
- 正符号 (+) または負符号 (-) 文字 (オプション)。
- digits
- 数字 (0 から 9) の連続シーケンス。少なくとも 1 つの数字が必要です。
- e_char
- 指数文字 (E または e)。
- e_sign
- 指数の正符号 (+) または負符号 (-) 文字 (オプション)。
- e_digits
- 指数の数字 (0 から 9) からなる連続シーケンス。ストリングに指数文字が含まれている場合、少なくとも 1 つの数字が必要です。
ストリングの数字シーケンス、または指数を表す文字 (オプション) の後には、数字ではない文字を含めることができますが、数字および指数を表す文字以外の最初の文字に達した時点で変換が停止します。ストリングは 10 の累乗の指数を持つ 10 進数の浮動小数点数値を表現していることを前提としています。
ストリングの形式が正しくないと、XMS からエラー・コード XMS_E_NUMBER_FORMAT_ERROR が戻されます。
- 数値プロパティー値 (データ型 xmsSBYTE のプロパティー値を含む) をストリングに変換する場合、その値に対応する ASCII 文字を含むストリングではなく、その値を 10 進数として表現するストリングに変換されます。例えば、整数値 65 はストリング「A」ではなくストリング「65」に変換されます。
- バイト配列プロパティー値をストリングに変換する場合、各バイトはバイトを表す 2 つの 16 進文字に変換されます。例えばバイト配列 {0xF1, 0x12, 0x00, 0xFF} はストリング「F11200FF」に変換されます。
プロパティー・タイプのデータ型変換は、Property クラスと PropertyContext クラスの両方のメソッドによりサポートされています。ただし、
C 関数 xmsPropertyGetStringByRef() と xmsGetStringPropertyByRef() では、非ストリング・プロパティー値の変換は
行われません。アプリケーションがこれらのいずれかの関数を呼び出し、非ストリング・プロパティー値を指すポインターを取得
しようとすると、XMS からエラー・コード XMS_E_TYPE_CONVERSION_FAILED が戻されます。