Метод IShellFolder::BindToObject (shobjidl_core.h)

Статья
08/26/2023

Извлекает обработчик, обычно объект папки оболочки, который реализует IShellFolder для определенного элемента. Необязательные параметры, управляющие построением обработчика, передаются в контексте привязки.

Синтаксис

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

Параметры

[in] pidl

Тип: PCUIDLIST_RELATIVE

Адрес структуры ITEMIDLIST (PIDL), которая идентифицирует вложенную папку. Это значение может ссылаться на элемент на любом уровне ниже родительской папки в иерархии пространства имен. Структура содержит одну или несколько структур SHITEMID , за которым следует завершающее значение NULL.

[in] pbc

Тип: IBindCtx*

Указатель на интерфейс IBindCtx в объекте контекста привязки, который можно использовать для передачи параметров в конструкцию обработчика. Если этот параметр не используется, присвойте ему значение NULL. Так как поддержка этого параметра необязательна для реализаций объектов папок, некоторые папки могут не поддерживать использование контекстов привязки.

Сведения, которые можно предоставить в контексте привязки, включают BIND_OPTS структуру, которая включает элемент grfMode , указывающий режим доступа при привязке к обработчику потока. Другие параметры можно задать и обнаружить с помощью IBindCtx::RegisterObjectParam и IBindCtx::GetObjectParam.

[in] riid

Тип: REFIID

Идентификатор возвращаемого интерфейса. Это может быть IID_IShellFolder, IID_IStream или любой другой интерфейс, который идентифицирует конкретный обработчик.

[out] ppv

Тип: void**

При возврате этим методом содержит адрес указателя на запрошенный интерфейс. При возникновении ошибки по этому адресу возвращается указатель NULL .

Возвращаемое значение

Тип: HRESULT

Если этот метод завершается успешно, он возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Приложения используют IShellFolder::BindToObject(..., IID_IShellFolder, ...) для получения объекта папки оболочки для подэлемента. Клиенты должны передавать канонический интерфейс IID, который используется для идентификации определенного обработчика. Например, IID_IShellFolder определяет обработчик папок, а IID_IStream идентифицирует обработчик потока. Реализации могут поддерживать привязку к обработчикам с помощью производных интерфейсов, таких как IID_IShellFolder2. Расширение пространства имен оболочки может реализовать эту функцию, создав объект папки оболочки для указанного подэлемента, а затем вызвав QueryInterface для взаимодействия с объектом через указатель интерфейса.

Реализации BindToObject могут оптимизировать любой вызов к нему, быстро завершаясь сбоем для значений IID, которые он не поддерживает. Например, если объект папки Shell подэлемента не поддерживает IRemoteComputer, реализация должна немедленно вернуть E_NOINTERFACE вместо того, чтобы без необходимости создавать объект папки Оболочки для подэлемента, а затем обнаруживать, что IRemoteComputer не поддерживается в конце концов.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)
DLL	Shell32.dll (версия 4.0 или более поздняя)

См. также раздел