SHBindToParent

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This function takes the fully qualified pointer to an item identifier list (PIDL) of a namespace object and returns a specified interface pointer on the parent object.

Syntax

HRESULT SHBindToParent(
  LPCITEMIDLIST pidl, 
  REFIID riid, 
  VOID** ppv, 
  LPCITEMIDLIST* ppidlLast
);

Parameters

• pidl
  [in] PIDL of the item.

• riid
  [in] Interface identifier for one of the interfaces exposed by the item's parent object.

• ppv
  [out] Pointer to the interface specified by riid. You must release the object when you are finished.

• ppidlLast
  [out] PIDL of the item relative to the parent folder. This PIDL can be used with many of the methods supported by the parent folder's interfaces. If you set ppidlLast to NULL, the PIDL is not returned. The calling application is responsible for freeing this pointer with the shell's IMalloc interface (see SHGetMalloc).

Return Value

Returns S_OK if successful, an OLE-defined error value otherwise.

Remarks

The following code example shows how to use SHBindToParent to retrieve the display name from an item's PIDL. The StrRetToBuf function is used to convert the STRRET structure returned by IShellFolder::GetDisplayNameOfinto a string.

IMalloc * pShellMalloc = NULL;    // A pointer to the shell's IMalloc interface
IShellFolder *psfParent;          // A pointer to the parent folder object's IShellFolder interface.
LPITEMIDLIST pidlItem = NULL;     // The item's PIDL.
LPITEMIDLIST pidlRelative = NULL; // The item's PIDL relative to the parent folder.
STRRET str;                       // The display name's STRRET structure.
TCHAR szDisplayName[MAX_PATH];    // The display name's string.
HRESULT hres = SHGetMalloc(&pShellMalloc);
if (FAILED(hres))
{
    return hres;
}
hres = SHBindToParent(pidlItem,
                      IID_IShellFolder,
                      &psfParent,
                      &pidlRelative);
if(SUCCEEDED(hres))
{
    psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL, &str);
    psfParent->Release();
    StrRetToBuf(&str, pidlItem, szDisplayName, ARRAYSIZE(szDisplayName));
}
// Clean up allocated memory
if (pidlRelative)
{
    pShellMalloc->Free(pidlRelative);
}
pShellMalloc->Release();

Requirements

See Also

Reference

Standard Shell Functions
IShellFolder::GetDisplayNameOf