INamespaceWalk::GetIDArrayResult method (shobjidl_core.h)

Gets a list of objects found during a namespace walk initiated by INamespaceWalk::Walk.

Syntax

HRESULT GetIDArrayResult(
  [out] UINT             *pcItems,
  [out] PIDLIST_ABSOLUTE **prgpidl
);

Parameters

[out] pcItems

Type: UINT*

The number of items stored in pppidl

[out] prgpidl

Type: LPITEMIDLIST**

The address of a pointer to an array of PIDLs representing the items found during the namespace walk.

Return value

Type: HRESULT

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

Remarks

To use INamespaceWalk::GetIDArrayResult, NSWF_DONT_ACCUMULATE_RESULT cannot be specified in the call to INamespaceWalk::Walk.

It is the responsibility of the calling application to free this array. Call CoTaskMemFree for each PIDL as well as once for the array itself.

Examples

The following example creates the INamespaceWalk instance, begins the walk at the desktop, walks only the desktop folder and its immediate children, retrieves the PIDLs retrieved in the walk, and frees their array.

void NamespaceWalk_Example()
{
    // Note that error checking has been omitted for clarity.
    
    INamespaceWalk *pnsw = NULL;
    IShellFolder *psfDesktop = NULL;

    // Get a pointer to the desktop to use as our root node
    hr = SHGetDesktopFolder(&psfDesktop);

    // Create the INamespaceWalk instance
    hr = CoCreateInstance(CLSID_NamespaceWalker, 
                          NULL, 
                          CLSCTX_INPROC,
                          IID_INamespaceWalk,
                          (void **)&pnsw);

    // Walk the desktop folder and one level of subfolders    
    hr = pnsw->Walk(psfDesktop, NSWF_NONE_IMPLIES_ALL, 1, NULL);

    UINT cItems;
    PIDLIST_ABSOLUTE *ppidls;
    
    // Retrieve the array of PIDLs gathered in the walk
    hr = pnsw->GetIDArrayResult(&cItems, &ppidls);

    // Perform some action using the PIDLs

    // The calling function is responsible for freeing the PIDL array
    FreeIDListArrayFull(ppidls, cItems);
    
    return;
}

void FreeIDListArrayFull(PIDLIST_ABSOLUTE *ppidls, UINT cItems)
{ 
    // Free the array elements
    for (UINT i = 0; i < cItems; i++) 
    { 
        CoTaskMemFree(ppidls[i]); 
    } 
    
    // Free the array itself
    CoTaskMemFree(ppidls);
    
    return; 
}

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)
Library	Shell32.lib
DLL	Shell32.dll (version 6.0 or later)