Méthode IUnknown ::QueryInterface(REFIID,void**) (unknwn.h)

Interroge un objet COM pour rechercher un pointeur vers l’une de son interface ; identification de l’interface par une référence à son identificateur d’interface (IID). Si l’objet COM implémente l’interface, il retourne un pointeur vers cette interface après avoir appelé IUnknown ::AddRef dessus.

Syntaxe

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

Paramètres

riid

Type : REFIID

Référence à l’identificateur d’interface (IID) de l’interface interrogée.

ppvObject

Type : void**

Adresse d’un pointeur vers une interface avec l’IID spécifié dans le paramètre riid . Étant donné que vous transmettez l’adresse d’un pointeur d’interface, la méthode peut remplacer cette adresse par le pointeur vers l’interface interrogée. Une fois le retour réussi, *ppvObject (l’adresse déréférencée) contient un pointeur vers l’interface demandée. Si l’objet ne prend pas en charge l’interface, la méthode affecte à *ppvObject (l’adresse déréférencée) la valeur nullptr.

Valeur retournée

Cette méthode retourne S_OK si l’interface est prise en charge, et E_NOINTERFACE autrement. Si ppvObject (l’adresse) est nullptr, cette méthode retourne E_POINTER.

Remarques

Pour un objet COM donné (également appelé composant COM), une requête spécifique pour l’interface IUnknown sur l’une des interfaces de l’objet doit toujours retourner la même valeur de pointeur. Cela permet à un client de déterminer si deux pointeurs pointent vers le même composant en appelant QueryInterface avec IID_IUnknown et en comparant les résultats. Il n’est pas spécifiquement le cas que les requêtes pour des interfaces autres que IUnknown (même la même interface via le même pointeur) doivent retourner la même valeur de pointeur.

Il existe quatre conditions requises pour les implémentations de QueryInterface (Dans ce cas, « doit réussir » signifie « doit réussir sauf défaillance catastrophique »).

• L’ensemble d’interfaces accessibles sur un objet via QueryInterface doit être statique et non dynamique. Cela signifie que si un appel à QueryInterface pour un pointeur vers une interface spécifiée réussit la première fois, il doit réussir à nouveau. Si l’appel échoue la première fois, il doit échouer sur tous les appels suivants.
• Elle doit être réflexive : si un client contient un pointeur vers une interface sur un objet et que le client interroge cette interface, l’appel doit réussir.
• Il doit être symétrique : si un client contenant un pointeur vers une interface interroge correctement une autre interface, une requête via le pointeur obtenu pour la première interface doit réussir.
• Il doit être transitif : si un client contenant un pointeur vers une interface interroge correctement une seconde, et par le biais de ce pointeur interroge correctement pour une troisième interface, une requête pour la première interface via le pointeur de la troisième interface doit réussir.

Remarques aux implémenteurs

Les implémentations de QueryInterface ne doivent jamais case activée ACL. La raison main de cette règle est que COM exige qu’un objet prenant en charge une interface particulière retourne toujours la réussite lorsqu’il est interrogé pour cette interface. Une autre raison est que la vérification des listes de contrôle d’accès sur QueryInterface n’offre pas de sécurité réelle, car tout client ayant accès à une interface particulière peut la remettre directement à un autre client sans aucun rappel au serveur. En outre, comme COM met en cache des pointeurs d’interface, il n’appelle pas QueryInterface sur le serveur chaque fois qu’un client effectue une requête.

Configuration requise

Voir aussi

• Interface IUnknown