このトピックでは、参照によってストリングまたはバイト配列を戻す C 関数が使用するインターフェースについて説明します。
C アプリケーションが、値によりストリングを戻す C 関数または 値によりバイト配列を戻す C 関数に説明されているいずれかの関数を呼び出した場合、XMS は、アプリケーションが提供するバッファーにストリングまたはバイト配列をコピーする必要があります。 アプリケーションが大量のメッセージを処理しており、メッセージ内のストリングまたはバイト配列のサイズがきわめて大きい場合は、ストリングまたはバイト配列のコピーに要する時間がパフォーマンスに影響を与える可能性があります。
この状態でのパフォーマンスを向上するため、C API には別の関数群が用意されています。 アプリケーションがこれらのいずれかの関数を呼び出すと、1 つのパラメーターは、XMS が所有するメモリーに格納されているストリングまたはバイト配列を指すポインターを戻し、別のパラメーターは、そのストリングまたはバイト配列の長さを戻します。 これらの関数の例は、xmsBytesMsgReadBytesByRef() や xmsGetStringPropertyByRef() です。
ストリングのデータ変換が必要な場合、XMS は、文字をアプリケーションのコード・ページに変換して、変換済みのストリングを指すポインターを戻します。 アプリケーションに戻される長さは、変換後のストリングの長さです。
データ変換が必要な場合、アプリケーションが参照によってストリングを初めて検索するときに要する時間は、ストリングを値によって検索する場合と同程度になります。 ただし、XMS は、変換済みのストリングをキャッシュに格納するため、同じストリングを検索するための以降の呼び出しには、それほど時間がかからなくなります。
これらの関数は、XMS が所有するメモリーを指すポインターを戻すため、アプリケーションはこのメモリーを解放しようとしたり、メモリーの内容を変更しようとしたりしてはいけません。 そのようにすると、予測できない結果を招く恐れがあります。
アプリケーションに戻されたポインターは、ストリングまたはバイト配列が関連付けられている XMS オブジェクトを削除するまでは有効な状態が維持されます。 このオブジェクトの削除後もアプリケーションがデータを必要な場合は、アプリケーションがストリングまたはバイト配列をコピーする必要があります。