IShellFolder::BindToObject (Compact 2013)

3/28/2014

This method retrieves an IShellFolder object for a subfolder.

Syntax

HRESULT BindToObject(
  LPCITEMIDLIST pidl,
  LPBC pbc,
  REFIID riid,
  VOID** ppvOut
);

Parameters

• pidl
  [in] Pointer to an ITEMIDLIST structure (PIDL) that identifies the subfolder.

• pbc
  [in] Optional address of an IBindCtx interface on a bind context object to be used during this operation. If this parameter is not used, set it to NULL. Because support for pbc is optional for folder object implementations, some folders may not support the use of bind contexts.

• riid
  [in] Identifier of the interface to return.

• ppvOut
  [out] Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Return Value

Returns NOERROR if successful, or an error value otherwise.

Remarks

The pidl parameter can refer to an object at any level below the parent folder in the namespace hierarchy. The pidl can thus be either a multi-level pointer to an item identifier list (PIDL), relative to the parent folder. The structure will contain one or more SHITEMID structures, followed by a terminating NULL.

Applications use IShellFolder::BindToObject to obtain a directly exposed interface from the shell folder object of a subitem. Usually the calling application passes IID_IShellFolder as the interface identifier to retrieve the IShellFolder interface. However, sometimes the calling application needs to obtain some other directly exposed interface, such as IRemoteComputer. A shell namespace extension can implement this function by creating the shell folder object for the specified subitem and then calling IUnknown::QueryInterface to convert it into the desired interface pointer, which is returned to the calling application.

This call is also useful if a particular interface is not implemented. For example, if the shell folder object of the subitem does not support the IRemoteComputer interface, the implementation can return E_NOINTERFACE immediately instead of needlessly creating the shell folder object for the subitem and then finding that IRemoteComputer was not supported after all.

This optimization is useful if creating a shell folder object is an expensive operation. In other words, the following two code fragments are equivalent.

/* This is the more efficient way */
   HRESULT hres = psf->BindToObject(pidl, pbc, riid, ppvOut);
/* This is the equivalent slower way */
   IShellFolder *psfOut;
   HRESULT hres = psf->BindToObject(pidl,
                                    pbc,
                                    IID_IShellFolder,
                                    (LPVOID)&psfOut);
   if (SUCCEEDED(hres)) 
   {
      hres = psfOut->QueryInterface(riid, ppvOut);
      psfOut->Release();
   } 
   
   else 
   {
      *ppvOut = NULL;
   }

Requirements

See Also

Reference

IShellFolder
ITEMIDLIST
SHITEMID
SHGetDesktopFolder