増分シリアル化

増分スタイルのシリアル化を使用する場合は、バッファーを操作する 3 つのルーチンを指定します。 これらのルーチンは、Alloc、Read、Write です。 Alloc ルーチンは、必要なサイズのバッファーを割り当てます。 Write ルーチンはデータをバッファーに書き込み、Read ルーチンはマーシャリングされたデータを含むバッファーを取得します。 1 回のシリアル化呼び出しで、これらのルーチンを複数呼び出すことができます。

シリアル化の増分スタイルでは、次のルーチンが使用されます。

• MesEncodeIncrementalHandleCreate
• MesDecodeIncrementalHandleCreate
• MesIncrementalHandleReset
• MesHandleFree

提供する必要がある Alloc、Read、Write 関数のプロトタイプを次に示します。

void __RPC_USER Alloc (
   void *State,          /* application-defined pointer */
   char **pBuffer,       /* returns pointer to allocated buffer */
   unsigned int *pSize); /* inputs requested bytes; outputs 
                         /* pBuffer size */

void __RPC_USER Write (
   void *State,          /* application-defined pointer */
   char *Buffer,         /* buffer with serialized data */
   unsigned int Size);   /* number of bytes to write from Buffer */

void __RPC_USER Read (
   void *State,          /* application-defined pointer */
   char **pBuffer,       /* returned pointer to buffer with data */
   unsigned int *pSize); /* number of bytes to read into pBuffer */

3 つの関数すべてにパラメーターを入力する状態は、エンコード サービス ハンドルに関連付けられたアプリケーション定義のポインターです。 アプリケーションはこのポインターを使用して、ファイル ハンドルやストリーム ポインターなど、アプリケーション固有の情報を含む構造体にアクセスできます。 スタブでは、Alloc、Read、および Write 関数に渡す以外の State ポインターは変更されないことに注意してください。 エンコード中に Alloc が呼び出され、データがシリアル化されるバッファーが取得されます。 次に、Write が呼び出され、シリアル化されたデータが格納されるタイミングと場所をアプリケーションが制御できるようになります。 デコード中に Read が呼び出され、アプリケーションによって格納されたシリアル化されたデータの要求されたバイト数が返されます。

増分スタイルの重要な機能は、ハンドルが状態ポインターを保持することです。 このポインターは状態を維持し、Alloc、Write、または Read 関数へのポインターを渡す場合を除き、RPC 関数によって操作されることはありません。 また、ハンドルは内部状態を維持するため、配置に必要なパディングを追加することで、複数の型インスタンスをエンコードして同じバッファーにデコードできます。 MesIncrementalHandleReset 関数は、バッファーの先頭から読み取りまたは書き込みを有効にするために、ハンドルを初期状態にリセットします。

Alloc 関数と Write 関数は、アプリケーション定義のポインターと共に、 MesEncodeIncrementalHandleCreate 関数の呼び出しによってエンコード サービス ハンドルに関連付けられます。 MesEncodeIncrementalHandleCreate は、ハンドルに必要なメモリを割り当ててから初期化します。

アプリケーションは MesDecodeIncrementalHandleCreate を呼び出してデコード ハンドルを作成し、 MesIncrementalHandleReset を呼び出してハンドルを再初期化するか、 MesHandleFree を呼び出してハンドルのメモリを解放できます。 Read 関数は、アプリケーション定義パラメーターと共に、 MesDecodeIncrementalHandleCreate ルーチンの呼び出しによってデコード ハンドルに関連付けられます。 関数はハンドルを作成し、それを初期化します。

MesIncrementalHandleReset の UserState、Alloc、Write、Read の各パラメーターは、変更がないことを示す NULL にできます。