IUnknown::QueryInterface(REFIID,void**) メソッド (unknwn.h)

COM オブジェクトに対して、インターフェイスの 1 つへのポインターを照会します。インターフェイス識別子 (IID) への参照によってインターフェイスを識別します。 COM オブジェクトがインターフェイスを実装する場合は、 IUnknown::AddRef を呼び出した後、そのインターフェイスへのポインターを返します。

構文

HRESULT QueryInterface(
  REFIID riid,
  void   **ppvObject
);

パラメーター

riid

型: REFIID

クエリ対象のインターフェイスのインターフェイス識別子 (IID) への参照。

ppvObject

型: void**

riid パラメーターで指定された IID を持つインターフェイスへのポインターのアドレス。 インターフェイス ポインターのアドレスを渡すので、メソッドはクエリ対象のインターフェイスへのポインターでそのアドレスを上書きできます。 正常に戻ると、 *ppvObject (逆参照されたアドレス) には、要求されたインターフェイスへのポインターが含まれます。 オブジェクトがインターフェイスをサポートしていない場合、メソッド は *ppvObject (逆参照されたアドレス) を nullptr.

戻り値

このメソッドは、インターフェイスがサポートされている場合は S_OK を返し、それ以外 の場合はE_NOINTERFACE 返します。 ppvObject (アドレス) が指定されている場合、このメソッドはnullptrE_POINTERを返します。

注釈

特定の COM オブジェクト (COM コンポーネントとも呼ばれます) の場合、オブジェクトのインターフェイス上の IUnknown インターフェイス に対する特定のクエリは、常に同じポインター値を返す必要があります。 これにより、クライアントは、IID_IUnknownを使用して QueryInterface を呼び出し、結果を比較 することで、2 つのポインターが同じコンポーネントを指しているかどうかを判断できます。 特に、 IUnknown 以外のインターフェイスに対するクエリ (同じポインターを介して同じインターフェイスであっても) が同じポインター値を返す必要がある場合は特にありません。

QueryInterface の実装には 4 つの要件があります (このような場合、"成功する必要があります" とは、"致命的な障害を発生さないために成功する必要があります" を意味します)。

  • QueryInterface を介してオブジェクトでアクセスできるインターフェイスのセットは、動的ではなく静的である必要があります。 つまり、指定したインターフェイスへのポインターに対する QueryInterface の呼び出しが初めて成功した場合は、再度成功する必要があります。 呼び出しが最初に失敗した場合は、後続のすべての呼び出しで失敗する必要があります。
  • これは再帰型である必要があります。クライアントがオブジェクト上のインターフェイスへのポインターを保持し、そのインターフェイスに対してクライアントがクエリを実行する場合、呼び出しは成功する必要があります。
  • 対称である必要があります。あるインターフェイスへのポインターを保持しているクライアントが別のインターフェイスに対して正常にクエリを実行した場合、最初のインターフェイスの取得したポインターを介したクエリは成功する必要があります。
  • これは推移的である必要があります。1 つのインターフェイス へのポインターを保持しているクライアントが 1 秒間正常にクエリを実行し、そのポインターを介して 3 番目のインターフェイスに対して正常にクエリを実行した場合、3 番目のインターフェイスのポインターを介した最初のインターフェイスのクエリは成功する必要があります。

実装者へのメモ

QueryInterface の実装では、ACL をチェックしないでください。 この規則の主な理由は、COM では、特定のインターフェイスをサポートするオブジェクトが、そのインターフェイスに対してクエリを実行したときに常に成功を返す必要があるということです。 もう 1 つの理由は、 QueryInterface で ACL をチェックしても、特定のインターフェイスにアクセスできるクライアントは、サーバーへの呼び出しなしで別のクライアントに直接渡すことができるため、実際のセキュリティが提供されないことです。 また、COM はインターフェイス ポインターをキャッシュするため、クライアントがクエリを実行するたびにサーバー上で QueryInterface を呼び出すことはありません。

要件

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

こちらもご覧ください