CoCreateFreeThreadedMarshaler 関数 (combaseapi.h)

  • [アーティクル]

コンテキスト依存のマーシャリングが可能な集計可能なオブジェクトを作成します。

構文

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

パラメーター

[in] punkOuter

集計オブジェクトの制御する IUnknown へのポインター。

[out] ppunkMarshal

集約可能マーシャラーへのインターフェイス ポインターを受け取るポインター変数のアドレス。

戻り値

この関数は、E_OUTOFMEMORY標準の戻り値と、次の値を返すことができます。

リターン コード 説明
S_OK
 マーシャラーが作成されました。

注釈

CoCreateFreeThreadedMarshaler 関数を使用すると、オブジェクトは同じプロセス内のスレッド間でインターフェイス ポインターを効率的にマーシャリングできます。 オブジェクトがスレッド間マーシャリングをサポートしていない場合は、この関数を呼び出す必要はありません。 これは、シングルスレッド アパートメントに関連付けられているスレッドであっても、プロセス内のすべてのスレッドから直接アクセスする必要があるフリースレッド DLL サーバーで使用することを目的としています。 これにより、実際のメモリ ポインターが偽の "プロキシ" として他のアパートメントにマーシャリングされ、フリー スレッドでない場合でも、すべての呼び出し元に直接アクセスできるようになります。

CoCreateFreeThreadedMarshaler 関数は、次のタスクを実行します。

  1. フリー スレッド マーシャラー オブジェクトを作成します。
  2. punkOuter パラメーターで指定されたオブジェクトにこのマーシャラーを集計します。 通常、このオブジェクトはインターフェイス ポインターをマーシャリングするオブジェクトです。
集計オブジェクトの IMarshal の実装では、IID_IMarshalの QueryInterface 呼び出しをフリー スレッド マーシャラーの IUnknown に委任する必要があります。 呼び出しを受信すると、フリー スレッド マーシャラーは次のタスクを実行します。
  1. CoMarshalInterface 関数の dwDestContext パラメーターで指定された宛先コンテキストを確認します。
  2. 宛先コンテキストがMSHCTX_INPROC場合は、インターフェイス ポインターをマーシャリング ストリームにコピーします。
  3. 変換先コンテキストが他の値である場合は、COM の既定の (標準) マーシャラーのインスタンスを検索または作成し、マーシャリングをそのコンテキストに委任します。
dwDestContext の値は、MSHCTX 列挙体から取得されます。 MSHCTX_INPROCは、インターフェイス ポインターが同じプロセス内の異なるスレッド間でマーシャリングされることを示します。 両方のスレッドが同じアドレス空間にアクセスできるため、クライアント スレッドはプロキシへの呼び出しを直接行う必要なく、ポインターを直接逆参照できます。 それ以外の場合はプロキシが必要であるため、 CoCreateFreeThreadedMarshaler はマーシャリング ジョブを COM の既定の実装に委任します。

CoCreateFreeThreadedMarshaler 関数を使用する場合は、細心の注意を払う必要があります。 これは、フリー スレッド マーシャラーを集計するオブジェクトのパフォーマンスは、COM の規則の計算された違反によって取得され、オブジェクトが特定の制限内で動作しない限り、未定義の動作のリスクが常に存在するためです。 最も重要な制限事項は次のとおりです。

  • フリースレッド マーシャラー オブジェクトは、フリースレッド マーシャラーを状態の一部として集計しないオブジェクト上のインターフェイスへの直接ポインターを保持できません。 オブジェクトが通常のシングルスレッド集計オブジェクトへの直接参照を使用する場合は、シングル スレッドのプロパティが壊れる可能性があります。 オブジェクトが通常のマルチスレッド集計オブジェクトへの直接参照を使用する場合、これらのオブジェクトは、直接シングルスレッド集計クライアントのニーズに対して秘密度を示さない方法で動作できます。 たとえば、これらのオブジェクトは新しいスレッドをスピンし、通常のシングルスレッド集計オブジェクトへの参照であるスレッドにパラメーターを渡すことができます。
  • フリー スレッド マーシャラー オブジェクトは、他のアパートメント内のオブジェクトへのプロキシへの参照を保持できません。 プロキシはスレッド モデルに依存し、間違ったクライアントによって呼び出された場合にRPC_E_WRONG_THREADを返す可能性があります。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー combaseapi.h (Objbase.h を含む)
Library Ole32.lib
[DLL] Ole32.dll

こちらもご覧ください

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream