このトピックでは、値によってストリングを戻す C 関数が使用するインターフェースについて説明します。
C API では、特定の関数がストリングをパラメーターとして戻します。 これらの各関数は、ストリングを検索する場合に同じインターフェースを使用します。
次に示す例は、こうした関数の 1 つである
xmsGetStringProperty() で、
PropertyContext クラスに属しています。
xmsRC xmsGetStringProperty(xmsHObj object,
xmsCHAR *propertyName,
xmsCHAR *propertyValue,
xmsINT length,
xmsINT *actualLength,
xmsHErrorBlock errorBlock);
次の 3 つのパラメーターにより、ストリングの検索を制御します。
- propertyValue
- このパラメーターは、アプリケーションが提供するバッファーを指すポインターで、このバッファーは XMS によるストリング内の文字のコピー先となるバッファーです。
データ変換が必要な場合、XMS は、文字をアプリケーションが使用するコード・ページに変換してから、バッファーにコピーします。
- length
- このパラメーターは、バッファーの長さ (バイト単位) です。これは、呼び出し前にアプリケーションによって設定する必要がある入力パラメーターです。
その代わりに XMSC_QUERY_SIZE を指定すると、ストリングは戻されませんが、actualLength パラメーターでストリング長が戻されます。
- actualLength
- この出力パラメーターは、XMS がバッファー内にコピーするストリングの長さを表します。
データ変換が必要な場合、これは変換後の長さです。長さはバイト単位で測定されます。 XMS は、必ずヌル終了ストリングを戻します。また、アプリケーションに報告される長さには、終了ヌル文字が含まれます。
入力時にこのパラメーターに NULL ポインターを指定すると、ストリングの長さは戻りません。
バッファーのサイズが不十分で、終了ヌル文字を含むストリング全体を格納できない場合、XMS は、バッファーの長さに切り捨てたストリングを戻し、actualLength パラメーターをストリング全体の長さに設定して、エラー・コード XMS_E_DATA_TRUNCATED を戻します。
JMS アプリケーションによって送信されたメッセージを XMS アプリケーションが受信した場合、このメッセージのヘッダー・フィールド、プロパティー、および本文に使用されているストリングには、組み込みのヌル文字が含まれる場合があります。
組み込みヌル文字を含むストリングを処理するときは、標準の C ストリング処理関数を使用することはできません。これらの関数では、ストリングの最初のヌル文字が、そのストリングの末尾を意味するマークであることが前提になっているためです。