INamespaceWalk

指定したルートノードから名前空間をたどるメソッドを公開します。たどる深さを指定でき、たどったすべてのノードのIDを格納した配列を任意で返します。

名前空間の内容を表示したり、その内容に対して操作を実行したりするには、このインターフェイスを使用します。INamespaceWalk を使用すると、名前空間内で到達可能なすべてのノードを項目識別子リストへのポインター（PIDL）として取得でき、それらを用いて各ノードの IShellFolder オブジェクトを取得できます。

INamespaceWalk の既定の実装のクラス識別子（CLSID）は CLSID_NamespaceWalker です。INamespaceWalk オブジェクトは、CoCreateInstance を使用して CLSID_NamespaceWalker に関連付けられたクラスの未初期化オブジェクトを1つ作成することで取得できます。このインターフェイスのIIDは IID_INamespaceWalk です。

指定したルートから指定した深さまで、名前空間の再帰的なたどりを開始します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

NSWF_SHOW_PROGRESS フラグを渡さず、かつ pnswcb パラメーターが指すオブジェクトが IActionProgress を実装している場合、INamespaceWalk::Walk メソッドは、操作をキャンセルすべきかどうかを判断するために IActionProgress::QueryCancel メソッドを定期的に呼び出します。

INamespaceWalk::Walk によって開始された名前空間のたどりで見つかったオブジェクトの一覧を取得します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

INamespaceWalk::GetIDArrayResult を使用するには、INamespaceWalk::Walk の呼び出しで NSWF_DONT_ACCUMULATE_RESULT を指定できません。

この配列を解放するのは呼び出し元アプリケーションの責任です。各PIDLに対して、および配列自体に対して1回、CoTaskMemFree を呼び出してください。

例

次の例では、INamespaceWalk インスタンスを作成し、デスクトップからたどりを開始して、デスクトップフォルダーとその直下の子のみをたどり、たどりで取得したPIDLを取得し、その配列を解放します。

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; 
}