Expand Minimize

SHBindToParent function

Takes a pointer to a fully qualified item identifier list (PIDL), and returns a specified interface pointer on the parent object.

Syntax


HRESULT SHBindToParent(
  _In_   PCIDLIST_ABSOLUTE pidl,
  _In_   REFIID riid,
  _Out_  VOID **ppv,
  _Out_  PCUITEMID_CHILD *ppidlLast
);

Parameters

pidl [in]

Type: PCIDLIST_ABSOLUTE

The item's PIDL.

riid [in]

Type: REFIID

The REFIID of one of the interfaces exposed by the item's parent object.

ppv [out]

Type: VOID**

A pointer to the interface specified by riid. You must release the object when you are finished.

ppidlLast [out]

Type: PCUITEMID_CHILD*

The item's PIDL 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.

Note  SHBindToParent does not allocate a new PIDL; it simply receives a pointer through this parameter. Therefore, you are not responsible for freeing this resource.

Return value

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Examples

The following code fragment uses SHBindToParent to retrieve the display name from an item's PIDL. The StrRetToBuf function is used to convert the STRRET structure returned by IShellFolder::GetDisplayNameOf into a string.


// pidlItem is the item's PIDL
// pidlRelative is the item's PIDL relative to the parent folder                   

IShellFolder* psfParent;           /* A pointer to the parent folder object's 
                                      IShellFolder interface. */
STRRET str;                        // The display name's STRRET structure.
TCHAR szDisplayName[MAX_PATH];     // The display name's string.

HRESULT hres = SHBindToParent(pidlItem,
                              IID_IShellFolder, 
                              (void**) &psfParent, 
                              &pidlRelative);

if(SUCCEEDED(hres))
{
    psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL, &str);
    psfParent->Release();

    StrRetToBuf(&str, 
                pidlItem, 
                szDisplayName, 
                sizeof(szDisplayName)/sizeof((szDisplayName)[0]));
}

Requirements

Minimum supported client

Windows 2000 Professional, Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Shlobj.h

Library

Shell32.lib

DLL

Shell32.dll (version 5.0 or later)

 

 

Community Additions

ADD
Show:
© 2014 Microsoft