Author: Jacob Levy

## The e4_StorageVisitor Class

The e4_StorageVisitor class enables a program to iterate over all open storages. The order in which the currently open storages are visited is implementation dependent. The class provides methods to return the current storage and to continue to the next storage to be visited, and to determine if there are more storages to be visited.

The following code fragment shows a typical use of the e4_StorageVisitor class:

>     e4_Storage s("mystorage", E4_METAKIT);
>     if (!s.IsValid()) {...}
>     ...
>     e4_StorageVisitor sv();
>     e4_Storage cs;
>     while (sv.CurrentStorageAndAdvance(cs)) {
>         if (!cs.IsValid()) {...}
>         if (cs == s) {
>             cerr << "Found our storage, "
>                  << cs.GetName() << ", " <<
>                  << s.GetName()  << ".\n";
>         }
>     }

The storage visitor sv is initialized to visit all storages that are currently open. We iterate over each storage in turn, and when we reach the storage s, we print a message to stderr.

The following methods are provided by the e4_StorageVisitor class:

e4_StorageVisitor Methods and Constructors
e4_StorageVisitor() | Default constructor. Creates an instance of e4_StorageVisitor that is initialized and ready to visit all currently open storages in an implementation dependent manner. It is undefined and implementation dependent whether the visitor will see storages that are opened after it was created.
e4_StorageVisitor(const e4_StorageVisitor &referrer) | Copy constructor. Creates an instance of e4_StorageVisitor that is initialized to start visiting storages from the storage currently visited by referrer. The new instance and referrer will visit all remaining subsequent storages in the same order.
~e4_StorageVisitor() | Destructor. Destroys this instance and decrements the reference count on the currently visited storage, if any.
e4_StorageVisitor &operator=(const e4_StorageVisitor &referrer) | Assignment operator. After the assignment, this instance will visit storages in the same order as referrer.
bool operator==(const e4_StorageVisitor &comp) | Returns true if comp refers to the same instance of e4_StorageVisitor as this instance.
bool operator!=(const e4_StorageVisitor &comp) | Returns true if comp does not refer to the same instance of e4_StorageVisitor as this instance.
bool IsDone() | Returns true if this instance has no more storages to visit or if the current storage being visited is invalid.
bool IsValid() | Returns true if this instance is not valid. An instance can become invalid if the storage it currently is visiting is closed. In that case the instance cannot continue to the next storage to be visited with the NextStorage method and cannot retrieve the current instance being visited with the CurrentStorage method.
bool CurrentStorage(e4_Storage &s) | Returns true if the current storage being visited is valid and is successfully retrieved in s. You can call this method any number of times to retrieve the currently visited storage; it does not advance the visitor to the next storage in line. This method will return true and retrieve the current valid storage being visited even after IsDone() becomes true.
bool NextStorage(e4_Storage &s) | Returns true if the visitor is successfully advanced to the next storage to be visited and if that storage is valid and is successfully retrieved in s. Each time you call this method, the visitor advances to the next storage and returns it in s.
bool Advance() | Returns true if the visitor is successfully advanced to the next storage to be visited and if that storage is valid.
bool CurrentStorageAndAdvance(e4_Storage &s) | Returns true if the current storage being visited is successfully retrieved in s. An attempt is made to advance the visitor to the next storage; if this fails, subsequent calls to IsDone() return true.