Método IShellFolder::BindToObject (shobjidl_core.h)

Artículo
03/15/2023

Recupera un controlador, normalmente el objeto de carpeta shell que implementa IShellFolder para un elemento determinado. Los parámetros opcionales que controlan la construcción del controlador se pasan en el contexto de enlace.

Sintaxis

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

Parámetros

[in] pidl

Tipo: PCUIDLIST_RELATIVE

Dirección de una estructura ITEMIDLIST (PIDL) que identifica la subcarpeta. Este valor puede hacer referencia a un elemento en cualquier nivel por debajo de la carpeta primaria de la jerarquía del espacio de nombres. La estructura contiene una o varias estructuras SHITEMID , seguidas de una terminación NULL.

[in] pbc

Tipo: IBindCtx*

Puntero a una interfaz IBindCtx en un objeto de contexto de enlace que se puede usar para pasar parámetros a la construcción del controlador. Si no se usa este parámetro, establézcalo en NULL. Dado que la compatibilidad con este parámetro es opcional para las implementaciones de objetos de carpeta, es posible que algunas carpetas no admitan el uso de contextos de enlace.

La información que se puede proporcionar en el contexto de enlace incluye una estructura de BIND_OPTS que incluye un miembro grfMode que indica el modo de acceso al enlazar a un controlador de secuencia. Se pueden establecer y detectar otros parámetros mediante IBindCtx::RegisterObjectParam e IBindCtx::GetObjectParam.

[in] riid

Tipo: REFIID

Identificador de la interfaz que se va a devolver. Esto puede ser IID_IShellFolder, IID_IStream o cualquier otra interfaz que identifique un controlador determinado.

[out] ppv

Tipo: void**

Cuando este método devuelve , contiene la dirección de un puntero a la interfaz solicitada. Si se produce un error, se devuelve un puntero NULL en esta dirección.

Valor devuelto

Tipo: HRESULT

Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Las aplicaciones usan IShellFolder::BindToObject(..., IID_IShellFolder, ...) para obtener el objeto de carpeta shell de un subelemento. Los clientes deben pasar el IID de interfaz canónica que se usa para identificar un controlador específico. Por ejemplo, IID_IShellFolder identifica el controlador de carpetas y IID_IStream identifica el controlador de flujo. Las implementaciones también pueden admitir el enlace a controladores mediante interfaces derivadas, como IID_IShellFolder2. Una extensión de espacio de nombres de Shell puede implementar esta función creando el objeto de carpeta shell para el subelemento especificado y, a continuación, llamando a QueryInterface para comunicarse con el objeto a través de su puntero de interfaz.

Las implementaciones de BindToObject pueden optimizar cualquier llamada a él si se produce un error rápido en los valores de IID que no admite. Por ejemplo, si el objeto de carpeta Shell del subelemento no admite IRemoteComputer, la implementación debe devolver E_NOINTERFACE inmediatamente en lugar de crear innecesariamente el objeto de carpeta shell para el subelemento y, a continuación, encontrar que IRemoteComputer no se admitía después de todo.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shobjidl_core.h (include Shobjidl.h)
Archivo DLL	Shell32.dll (versión 4.0 o posterior)