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

  • [アーティクル]

インターフェイス ポインターをマーシャリングします。

構文

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

パラメーター

[in] pStm

マーシャリング中に使用されるストリームへのポインター。

[in] riid

マーシャリングするインターフェイスの識別子への参照。 このインターフェイスは、 IUnknown インターフェイスから派生する必要があります。

[in] pv

マーシャリングするインターフェイス ポインターへのポインター。 呼び出し元に目的のインターフェイスへのポインターがない場合、このパラメーターは NULL にすることができます。

[in] dwDestContext

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

[in] pvDestContext

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

[in] mshlflags

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

戻り値

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

リターン コード 説明
S_OK
 インターフェイス ポインターが正常にマーシャリングされました。
E_NOINTERFACE
 指定されたインターフェイスはサポートされていません。
STG_E_MEDIUMFULL
 ストリームがいっぱいです。

解説

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

呼び出し元へのメモ

通常、 MarshalInterface を 直接呼び出すのではなく、マーシャリング スタブで、このメソッドの呼び出しを含む CoMarshalInterface 関数を呼び出す必要があります。 スタブは、マーシャリング データをストリームに書き込むオブジェクトをコマンドに対してこの呼び出しを行います。 その後、スタブはマーシャリング データをクライアント プロセスに渡すか、グローバル テーブルに書き込みます。このテーブルは、複数のクライアントでマーシャリングを解除できます。 通常、スタブの CoMarshalInterface の呼び出しの前には、マーシャリング データの書き込み先となるストリーム バッファーの最大サイズを取得する CoGetMarshalSizeMax の呼び出しが行われます。

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

独自のインターフェイスを定義するために MIDL を使用していない場合は、マーシャリング スタブで直接または間接的にこのメソッドを呼び出す必要があります。 スタブの実装では、IMarshal::GetMarshalSizeMax が返された前の呼び出しの直後に MarshalInterface を呼び出す必要があります。 GetMarshalSizeMax によって返される値は、マーシャリングされるオブジェクトの内部状態が変更されない限り有効であることが保証されるため、MarshalInterface の呼び出しの遅延により、オブジェクトが最初に示したよりも大きなストリーム バッファーが必要になるリスクが発生します。

呼び出し元がマーシャリングされるインターフェイスへのポインターを持っている場合は、効率の問題として pv パラメーターを使用してそのポインターを渡す必要があります。 このようにして、このようなポインターを使用してプロキシに適した CLSID を決定する実装では、それ自体で QueryInterface を呼び出す必要はありません。 呼び出し元にマーシャリングするインターフェイスへのポインターがない場合は、 NULL を渡すことができます。

実装者へのメモ

MarshalInterface の実装では、受信側でプロキシを初期化するために必要なデータをストリームに書き込む必要があります。 このようなデータには、マーシャリングするインターフェイスへの参照、クライアント プロセスにデータを返すかグローバル テーブルに書き込むかを指定する MSHLFLAGS 値、名前付きパイプ、ウィンドウへのハンドル、RPC チャネルへのポインターなど、オブジェクトに接続するために必要なものが含まれます。

実装では、ストリームがすべてのデータを保持するのに十分な大きさであると想定しないでください。 むしろ、STG_E_MEDIUMFULLエラーを適切に処理する必要があります。 終了する直前に、実装では、書き込まれたデータの最後のバイトの直後に、ストリーム内にシーク ポインターを配置する必要があります。

pv パラメーターが NULL で、実装にインターフェイス ポインターが必要な場合は、現在のオブジェクトで QueryInterface を 呼び出して取得できます。 pv パラメーターは、単に効率を向上させるために存在します。

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

呼び出し元は、 MSHLFLAGS 列挙を使用して、インターフェイス ポインターを 1 つのクライアントにマーシャリングするか、グローバル テーブルに書き込むかを指定できます。ここで、複数のクライアントでマーシャリングを解除できます。 オブジェクトが、同じ初期化データから作成される可能性がある複数のプロキシからの呼び出しを処理できることを確認する必要があります。

要件

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

関連項目

CoMarshalInterface

IMarshal