メモリの割り当て

アプリケーションでは、このデータのメモリを割り当てる必要があります。TAPI とサービス プロバイダーがデータを提供します。 操作が非同期の場合、非同期応答メッセージが成功を示すまでデータは使用できません。

アプリケーションと TAPI の間でデータを渡すために使用されるすべてのデータ構造が フラット化されます。 つまり、データ構造には、可変サイズのデータ コンポーネントを含むサブ構造へのポインターは含まれません。 代わりに、可変量のデータをアプリケーションに渡すために使用されるデータ構造には、次のメタ構造が必要です。

  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize; 
    <fixed size fields> 
  DWORD  dw<VarSizeField1>Size;
  DWORD  dw<VarSizeField1>Offset; 
    <fixed size fields> 
  DWORD  dw<VarSizeField2>Size;
  DWORD  dw<VarSizeField2>Offset; 
    <common extensions> 
    <var sized field1> 
    <var sized field2>

dwTotalSize メンバーは、このデータ構造に割り当てられたサイズ (バイト単位) です。 データ構造の末尾をマークし、このデータ構造を使用する関数を呼び出す前にアプリケーションによって設定されます。 関数は、このサイズを超える読み取りまたは書き込みを行いません。 アプリケーションは、TAPI が構造体の内容を返すために割り当てられたバイトの合計数を示すように dwTotalSize メンバーを設定する必要があります。

TAPI は dwNeededSize メンバーを入力します。 要求されたすべてのデータを返すために必要なバイト数を示します。 多くの場合、可変サイズのフィールドが存在すると、割り当てに必要なデータ構造サイズをアプリケーションで見積もることができなくなります。 このフィールドは、データに実際に必要なバイト数を返します。 この数値は dwTotalSize より小さいか、等しいか、または大きくすることができ、 dwTotalSize メンバー自体のスペースが含まれます。 大きい場合、返される構造体は部分的にしか塗りつぶされません。 アプリケーションで必要なフィールドが部分構造で使用できる場合は、他に何も行う必要はありません。 それ以外の場合、アプリケーションは少なくとも dwNeededSize のサイズの構造体を割り当てて、関数を再度呼び出す必要があります。 通常、今回はすべての情報を返すために十分な領域を使用できますが、サイズが再び増加した可能性があります。

TAPI は、有用なデータを含むデータ構造の部分の実際のサイズ (バイト単位) を示すためにデータをアプリケーションに返す場合、 dwUsedSize メンバーを入力します。 たとえば、割り当てられた構造体が小さすぎて、切り捨てられたフィールドが可変サイズのフィールドである場合、 dwNeededSize は dwTotalSize より大きく、切り捨てられたフィールドは空のままです。 したがって 、dwUsedSize メンバーは dwTotalSize より小さくなります。 部分的なフィールド値は返されません。

このヘッダーの後には、データ構造の固定部分があります。 これには、通常のフィールドと、実際の可変サイズのフィールドを記述するサイズとオフセットのペアが含まれています。 offset フィールドには、レコードの先頭からの可変サイズのフィールドのオフセット (バイト単位) が含まれます。 size フィールドには、可変サイズのフィールドのサイズ (バイト単位) が含まれます。 可変サイズのフィールドが空の場合、サイズ フィールドは 0 になり、オフセットは 0 に設定されます。 構造体の合計サイズが不十分な場合に切り捨てられる可変サイズのフィールドは空のままです。 つまり、サイズ フィールドは 0 に設定され、オフセットは 0 に設定されます。 可変サイズのフィールドは、固定フィールドに従います。

サービス プロバイダーが変数メンバーを入力する必要がある場合、TAPI は対応するサイズとオフセット メンバーを 0 に初期化します。 サービス プロバイダーが変数メンバーを入力する場合は、対応するサイズとオフセット メンバーを適切な値 (変数メンバーを設定する場合 は dwUsedSize や dwNeededSize など) に設定する必要があります。 サービス プロバイダーは、使用可能な領域に収まるように変数メンバーを切り捨ててはなりません。

サービス プロバイダーは、構造体の固定メンバーの直後に変数メンバーを開始し、TAPI が可変長メンバーに使用できるように、割り当てられたメモリの末尾に余分な領域を残す必要があります。 変数メンバーは任意の順序で配置できますが、メンバーは連続している必要があります。