The INamespaceWalk::
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 INamespaceWalkCB
interface, you can monitor the progress of the namespace walk and also influence how it proceeds.
The EnterFolder
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 byINamespaceWalk::
GetIDArrayResult
. - Return
S_FALSE
to prevent the namespace walk from recursing into the folder. The folder is eligible to be reported byINamespaceWalk::
GetIDArrayResult
. - Return a COM error
HRESULT
to abandon the namespace walk operation. The error code you return will be the return value of theINamespaceWalk::
Walk
method.
The FoundItem
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 byINamespaceWalk::
GetIDArrayResult
. - Return a COM error
HRESULT
to abandon the namespace walk operation. The error code you return will be the return value of theINamespaceWalk::
Walk
method.
Note that “allow the namespace walk to recurse into the folder” and “eligible to be reported by INamespaceWalk::
GetIDArrayResult
” 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 EnterFolder
handler.
The LeaveFolder
method is called when the namespace walk has finished enumerating the contents of a folder. It is the counterpart to EnterFolder
. 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 |
---|---|---|---|
EnterFolder |
Allow recursion
Allow reporting Continue |
Block recursion
Allow reporting Continue |
Block recursion
Block reporting Abandon |
FoundItem |
Allow reporting
Continue |
Not allowed |
Block reporting
Abandon |
LeaveFolder |
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
INamespaceWalk::
Walk
, and we’re passing theNSWF_
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?
0 comments