All VDS objects that are listed in Storage Management Objects--except for the service object--are returned by means of enumeration objects. For an example of how these objects are created and used, see section 4.3.

When the client calls a method to request an enumeration, the server creates an enumeration object that implements the IEnumVdsObject interface and returns the interface pointer to the client to allow it to enumerate through the requested objects. The server maintains this object until the client releases all references to the interface. For each enumeration object, the server maintains the following information:

Objects Being Enumerated: A list of pointers to the VDS objects being enumerated.

• When the enumeration object is created, the server populates this list with the objects to return, dictated by the particular specification of the method that the client calls.

• The server does not list the same object more than once.

• After the list is populated, the server does not reorder the entries in the list.

• If a new VDS object is added to the server, the server does not add the object to the list of objects being enumerated.

• If a VDS object is removed from the server, the server does not remove the object from the list of objects being enumerated. If the client later accesses the removed object, the server returns VDS_E_OBJECT_DELETED whenever the client attempts to access the object interface methods.

Index: A value that keeps track of which object to return next to the client, when the client requests more objects from the enumeration.

• When the enumeration object is created, this value is initialized to the index of the first VDS object (whether this is 0, 1, or any other value is an implementation detail) in the list of objects being enumerated.

• If the client requests a certain number of objects from the enumeration by means of the IEnumVdsObject::Next (Opnum 3) method, the server returns the requested number of pointers to the objects in the list, starting at the current index value. However, if the server reaches the end of the list, the server returns the remaining pointers to the objects in the list, and indicates the actual number of objects that are returned to the client and the return code of S_FALSE. The server increments the index by the number of objects that are returned to the client.

• If the client requests to skip a certain number of objects in the enumeration by means of the IEnumVdsObject::Skip (Opnum 4) method, the server increments the index by that number.

• If the index goes past the end of the list, all subsequent requests for more objects from the enumeration will return zero pointers and a return code of S_FALSE until the enumeration is reset.

• If the client calls the IEnumVdsObject::Reset (Opnum 5) method, the server sets the index back to the first object in the list.