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

[アーティクル]
08/25/2023

マーシャリング解除コードの CLSID を取得します。

構文

HRESULT GetUnmarshalClass(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] CLSID  *pCid
);

パラメーター

[in] riid

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

[in] pv

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

[in] dwDestContext

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

[in] pvDestContext

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

[in] mshlflags

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

[out] pCid

クライアントプロセスでプロキシを作成するために使用される CLSID を受け取るポインター。

戻り値

メソッドが成功した場合、戻り値はS_OK。それ以外の場合は、S_FALSE。

注釈

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

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

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

呼び出し元へのメモ

マーシャリングスタブは、このメソッドのオブジェクトの実装を呼び出して、プロキシのインスタンスの作成に使用される CLSID を取得します。クライアントは、CLSID を受信すると、システムレジストリに一覧表示されている DLL を読み込みます。

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

独自のインターフェイスを定義するために MIDL を使用していない場合、クライアント側 COM ライブラリがインターフェイスを実装するオブジェクトのプロキシを作成するために必要な CLSID を取得するには、スタブで直接または間接的にこのメソッドを呼び出す必要があります。

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

実装者へのメモ

COM は GetUnmarshalClass を呼び出して、クライアントプロセスでプロキシを作成するために使用される CLSID を取得します。通常、プロキシに使用する CLSID は、元のオブジェクトの CLSID ではなく、プロキシオブジェクト専用に (Guidgen.exe ツールを使用して) 生成したものになります。

1 つ以上のインターフェイスにマーシャリングを提供するオブジェクトごとに、このメソッドを実装します。オブジェクトのマーシャリングを担当するコードは、CLSID とマーシャリングデータをストリームに書き込みます。COM は、受信側のストリームから CLSID とデータを抽出します。

プロキシの実装が元のオブジェクト全体をクライアントプロセスにコピーするだけで構成される場合、元のオブジェクトへの呼び出しを転送する必要がなくなり、返される CLSID は元のオブジェクトと同じになります。もちろん、この戦略は、変更が予想されないオブジェクトに対してのみ推奨されます。

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

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

メモThreadingModel レジストリ値は、GetUnmarshalClass メソッドから返される CLSID を実装するインプロセスサーバーの場合は Both である必要があります。詳細については、「 InprocServer32」を参照してください。

要件

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

こちらもご覧ください

CoMarshalInterface

IMarshal

Share via