IShellFolder ::BindToObject, méthode (shobjidl_core.h)

Article
03/02/2024

Récupère un gestionnaire, généralement l’objet de dossier Shell qui implémente IShellFolder pour un élément particulier. Les paramètres facultatifs qui contrôlent la construction du gestionnaire sont passés dans le contexte de liaison.

Syntaxe

HRESULT BindToObject(
  [in]  PCUIDLIST_RELATIVE pidl,
  [in]  IBindCtx           *pbc,
  [in]  REFIID             riid,
  [out] void               **ppv
);

Paramètres

[in] pidl

Type : PCUIDLIST_RELATIVE

Adresse d’une structure ITEMIDLIST (PIDL) qui identifie le sous-dossier. Cette valeur peut faire référence à un élément à n’importe quel niveau sous le dossier parent dans la hiérarchie de l’espace de noms. La structure contient une ou plusieurs structures SHITEMID , suivies d’une valeur NULL de fin.

[in] pbc

Type : IBindCtx*

Pointeur vers une interface IBindCtx sur un objet de contexte de liaison qui peut être utilisé pour passer des paramètres à la construction du gestionnaire. Si ce paramètre n’est pas utilisé, définissez-le sur NULL. Étant donné que la prise en charge de ce paramètre est facultative pour les implémentations d’objets de dossier, certains dossiers peuvent ne pas prendre en charge l’utilisation de contextes de liaison.

Les informations qui peuvent être fournies dans le contexte de liaison incluent une structure BIND_OPTS qui inclut un membre grfMode qui indique le mode d’accès lors de la liaison à un gestionnaire de flux. D’autres paramètres peuvent être définis et découverts à l’aide de IBindCtx ::RegisterObjectParam et IBindCtx ::GetObjectParam.

[in] riid

Type : REFIID

Identificateur de l’interface à retourner. Il peut s’agir de IID_IShellFolder, de IID_IStream ou de toute autre interface qui identifie un gestionnaire particulier.

[out] ppv

Type : void**

Lorsque cette méthode retourne, contient l’adresse d’un pointeur vers l’interface demandée. Si une erreur se produit, un pointeur NULL est retourné à cette adresse.

Valeur retournée

Type : HRESULT

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Les applications utilisent IShellFolder ::BindToObject(..., IID_IShellFolder, ...) pour obtenir l’objet de dossier Shell pour un sous-élément. Les clients doivent passer l’IID d’interface canonique utilisée pour identifier un gestionnaire spécifique. Par exemple, IID_IShellFolder identifie le gestionnaire de dossiers et IID_IStream identifie le gestionnaire de flux. Les implémentations peuvent également prendre en charge la liaison à des gestionnaires à l’aide d’interfaces dérivées, telles que IID_IShellFolder2. Une extension d’espace de noms Shell peut implémenter cette fonction en créant l’objet de dossier Shell pour le sous-élément spécifié, puis en appelant QueryInterface pour communiquer avec l’objet via son pointeur d’interface.

Les implémentations de BindToObject peuvent optimiser n’importe quel appel à celui-ci en échouant rapidement pour les valeurs IID qu’il ne prend pas en charge. Par exemple, si l’objet de dossier Shell du sous-élément ne prend pas en charge IRemoteComputer, l’implémentation doit retourner immédiatement E_NOINTERFACE au lieu de créer inutilement l’objet de dossier Shell pour le sous-élément, puis de constater qu’IRemoteComputer n’était pas pris en charge après tout.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shobjidl_core.h (inclure Shobjidl.h)
DLL	Shell32.dll (version 4.0 ou ultérieure)