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

  • Artigo

Recupera um manipulador, normalmente o objeto de pasta Shell que implementa IShellFolder para um item específico. Parâmetros opcionais que controlam a construção do manipulador são passados no contexto de associação.

Sintaxe

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

Parâmetros

[in] pidl

Tipo: PCUIDLIST_RELATIVE

O endereço de uma estrutura ITEMIDLIST (PIDL) que identifica a subpasta. Esse valor pode se referir a um item em qualquer nível abaixo da pasta pai na hierarquia de namespace. A estrutura contém uma ou mais estruturas SHITEMID , seguidas por um NULL de terminação.

[in] pbc

Tipo: IBindCtx*

Um ponteiro para uma interface IBindCtx em um objeto de contexto de associação que pode ser usado para passar parâmetros para a construção do manipulador. Se esse parâmetro não for usado, defina-o como NULL. Como o suporte para esse parâmetro é opcional para implementações de objeto de pasta, algumas pastas podem não dar suporte ao uso de contextos de associação.

As informações que podem ser fornecidas no contexto de associação incluem uma estrutura BIND_OPTS que inclui um membro grfMode que indica o modo de acesso ao associar a um manipulador de fluxo. Outros parâmetros podem ser definidos e descobertos usando IBindCtx::RegisterObjectParam e IBindCtx::GetObjectParam.

[in] riid

Tipo: REFIID

O identificador da interface a ser retornada. Isso pode ser IID_IShellFolder, IID_IStream ou qualquer outra interface que identifique um manipulador específico.

[out] ppv

Tipo: void**

Quando esse método retorna, contém o endereço de um ponteiro para a interface solicitada. Se ocorrer um erro, um ponteiro NULL será retornado nesse endereço.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Os aplicativos usam IShellFolder::BindToObject(..., IID_IShellFolder, ...) para obter o objeto de pasta Shell para um subitem. Os clientes devem passar a IID da interface canônica usada para identificar um manipulador específico. Por exemplo, IID_IShellFolder identifica o manipulador de pastas e IID_IStream identifica o manipulador de fluxo. As implementações também podem dar suporte à associação a manipuladores usando interfaces derivadas, como IID_IShellFolder2. Uma extensão de namespace shell pode implementar essa função criando o objeto de pasta Shell para o subitem especificado e, em seguida, chamando QueryInterface para se comunicar com o objeto por meio de seu ponteiro de interface.

As implementações de BindToObject podem otimizar qualquer chamada a ele falhando rapidamente em valores IID aos quais ele não dá suporte. Por exemplo, se o objeto de pasta Shell do subitem não der suporte a IRemoteComputer, a implementação deverá retornar E_NOINTERFACE imediatamente em vez de criar desnecessariamente o objeto de pasta Shell para o subitem e, em seguida, descobrir que IRemoteComputer não tinha suporte, afinal.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shobjidl_core.h (inclua Shobjidl.h)
DLL Shell32.dll (versão 4.0 ou posterior)

Confira também

IPersistFolder

IPersistFolder2

Ishellfolder

IShellFolder2

SHGetDesktopFolder