November 8th, 2017

How can I control which parts of the shell namespace the INamespaceWalk::Walk operation will walk into?

The INamespace­Walk::Walk method initiates a depth-first traversal of the shell namespace, subject to constraints controlled by the various parameters (such as maximum search depth). If you pass an object which implements the INamespace­Walk­CB interface, you can monitor the progress of the namespace walk and also influence how it proceeds.

The Enter­Folder method is called when the namespace walk finds an object in the shell namespace with the SFGAO_FOLDER attribute. You can perform whatever actions you wish in response to this callout, and you can provide limited feedback to the namespace walk operation:

  • Return S_OK to allow the namespace walk to recurse into the folder. The folder is eligible to be reported by INamespace­Walk::Get­ID­Array­Result.
  • Return S_FALSE to prevent the namespace walk from recursing into the folder. The folder is eligible to be reported by INamespace­Walk::Get­ID­Array­Result.
  • Return a COM error HRESULT to abandon the namespace walk operation. The error code you return will be the return value of the INamespace­Walk::Walk method.

The Found­Item method is called when the namespace walk finds an object in the shell namespace without the SFGAO_FOLDER attribute. Again, you can perform whatever actions you wish in response to this callout, and you can provide limited feedback to the namespace walk operation:

  • Return S_OK to allow the namespace walk to continue. The item will be reported by INamespace­Walk::Get­ID­Array­Result.
  • Return a COM error HRESULT to abandon the namespace walk operation. The error code you return will be the return value of the INamespace­Walk::Walk method.

Note that “allow the namespace walk to recurse into the folder” and “eligible to be reported by INamespace­Walk::Get­ID­Array­Result” are both conditional upon how the namespace walk is configured. For example, if recursing into the folder would exceed the recursion depth, then recursion won’t occur even if you say “Sure, go ahead” in your Enter­Folder handler.

The Leave­Folder method is called when the namespace walk has finished enumerating the contents of a folder. It is the counterpart to Enter­Folder. This is your chance to perform any cleanup or other actions. (For example, if you are counting the number of items in each folder, this tells you that the enumeration of a folder is complete, and you can save the totals to wherever you intend to save them.) The return value here does not affect the namespace walk.

Let’s go with the table again:

Operation S_OK S_FALSE COM error
Enter­Folder
Allow recursion
Allow reporting
Continue
Block recursion
Allow reporting
Continue
Block recursion
Block reporting
Abandon
Found­Item
Allow reporting
Continue
Not allowed
Block reporting
Abandon
Leave­Folder Continue Not allowed Continue

The boxes marked “Not allowed” indicate that returning S_FALSE is not allowed for those methods.

Exercise 1: A customer had the following question. Maybe you can answer it.

We are using INamespace­Walk::Walk, and we’re passing the NSWF_TRAVERSE_STREAM_JUNCTIONS flag so that it recurses into CAB folders, but it’s also recursing into ZIP folders. How can we stop it from recursing into ZIP folders?

Exercise 2: Suppose you want to process at most the first 100 files. How would you stop the namespace walk operation after 100 files have been processed?

Topics
Code

Author

Raymond has been involved in the evolution of Windows for more than 30 years. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie-jeebies. The Web site spawned a book, coincidentally also titled The Old New Thing (Addison Wesley 2007). He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information.

0 comments

Discussion are closed.