IMarshal::GetMarshalSizeMax メソッド (objidl.h)

[アーティクル]
02/29/2024

マーシャリング中に必要となるバッファーの最大サイズを取得します。

構文

HRESULT GetMarshalSizeMax(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] DWORD  *pSize
);

パラメーター

[in] riid

マーシャリングするインターフェイスの識別子への参照。

[in] pv

マーシャリングするインターフェイスポインター。このパラメーターは、NULL でもかまいません。

[in] dwDestContext

指定したインターフェイスをマーシャリングしない宛先コンテキスト。可能な値は、列挙 MSHCTX から取得されます。マーシャリングの解除は、現在のプロセスの別のアパートメント (MSHCTX_INPROC) または現在のプロセスと同じコンピューター上の別のプロセス (MSHCTX_LOCAL) のいずれかで発生する可能性があります。

[in] pvDestContext

このパラメーターは予約済みであり、 NULL である必要があります。

[in] mshlflags

マーシャリングするデータをクライアントプロセス (一般的なケース) に転送するか、グローバルテーブルに書き込むかを示します。このテーブルは、複数のクライアントから取得できます。使用できる値は、MSHLFLAGS 列挙体から取得されます。

[out] pSize

バッファーの最大サイズを受け取る変数へのポインター。

戻り値

このメソッドは、E_FAILおよびS_OK標準の戻り値と、次の値を返すことができます。

リターンコード	説明
E_NOINTERFACE	指定されたインターフェイスはサポートされていません。

注釈

このメソッドは、 CoGetMarshalSizeMax の呼び出しで間接的に呼び出されます。これは、サーバープロセス内の任意のコードがオブジェクト上のインターフェイスへのポインターをマーシャリングする役割を担います。通常、このマーシャリングコードは、まったく異なるオブジェクトに実装されているインターフェイスへのポインターをマーシャリングできるいくつかのインターフェイスの 1 つについて、COM によって生成されるスタブです。たとえば、 IClassFactory インターフェイスと IOleItemContainer インターフェイスがあります。ディスカッションの目的で、ポインターのマーシャリングを担当するコードは マーシャリングスタブと呼ばれます。

オブジェクトのプロキシを作成するには、元のオブジェクトからの 2 つの情報 (マーシャリングストリームに書き込まれるデータの量とプロキシの CLSID) が必要です。

マーシャリングスタブは、 CoGetMarshalSizeMax と CoMarshalInterface を連続して呼び出して、これら 2 つの情報を取得します。

呼び出し元へのメモ

マーシャリングスタブは、 CoGetMarshalSizeMax の呼び出しを介して、このメソッドのオブジェクトの実装を呼び出して、 MarshalInterface に渡されるストリームバッファーを事前割り当てします。

既存の COM インターフェイスを実装する場合、または Microsoft Interface Definition Language (MIDL) を使用して独自のカスタムインターフェイスを定義する場合は、このメソッドを明示的に呼び出さないでください。どちらの場合も、MIDL によって生成されたスタブが自動的に呼び出しを行います。

MIDL を使用して独自のインターフェイスを定義しない場合 (「 COM インターフェイスの定義」を参照)、マーシャリングスタブで GetMarshalSizeMax を呼び出す必要はありませんが、これを行うことを強くお勧めします。オブジェクトは、マーシャリングデータパケットの最大サイズの可能性が高いインターフェイススタブよりも適切に認識されます。したがって、拡張のオーバーヘッドが重要でないほど効率的な自動的に拡張されるストリームを提供しない限り、独自のインターフェイスを実装する場合でも、このメソッドを呼び出す必要があります。

このメソッドによって返される値は、マーシャリングされるオブジェクトの内部状態が変更されない限り、有効であることが保証されます。したがって、実際のマーシャリングは、この関数が戻った直後に行う必要があります。または、スタブは、状態が変化したためにオブジェクトが最初に示したメモリよりも多くのメモリをマーシャリングする必要がある可能性があるリスクを実行します。

実装者へのメモ

MarshalInterface の実装では、事前に割り当てられたバッファーを使用して、マーシャリングデータをストリームに書き込みます。バッファーが小さすぎると、マーシャリング操作は失敗します。したがって、このメソッドによって返される値は、インターフェイスをマーシャリングするために必要なデータの量を控えめに見積もる必要があります。この要件の違反は、致命的なエラーとして扱う必要があります。

MarshalInterface の後続の呼び出しでは、IMarshal 実装は、GetMarshalSizeMax を事前に呼び出した呼び出し元に依存できません。ストリームによって返されるエラー STG_E_MEDIUMFULL注意し、適切に処理する準備をしておく必要があります。

GetMarshalSizeMax の実装が今後も新しい宛先コンテキストがサポートされるにつれて引き続き正常に動作するようにするには、実装で認識されないすべての dwDestContext 値について、COM の既定の実装にマーシャリングを委任します。マーシャリングを COM の既定の実装に委任するには、 CoGetStandardMarshal 関数を呼び出します。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	objidl.h

こちらもご覧ください

CoGetMarshalSizeMax

IMarshal