IdmaEnumOfObject

This interface provides the methods for handling enumerators that contain references to DMA Objects.

IdmaEnumOfObject::GetNextObject

This method must be supported in every implementation of this interface.

Syntax
DmaRC IdmaEnumOfObject::GetNextObject (
DmaIndex32 iNumItems,
IUnknown** pArray,
pDmaIndex32 piNumReturned)

Parameters

This function will return the next iNumItems objects in the object enumeration.

If there are N elements remaining, but N is less than iNumItems and greater than zero, then the first N elements of the array will be valid and the method will return DMARC_OK. The actual number will be returned in piNumReturned.

If there are no items to return, *piNumReturned will be set to zero and an error code will be returned.

If an error occurs while generating the first object, an error code will be returned, no objects will be returned, and *piNumReturned will be set to zero. The enumeration will be positioned at the object in error.

If an error occurs while generating an object other than the first object, as many objects as were successfully enumerated will be returned, *piNumReturned will be set to the number of objects successfully returned, and DMARC_OK will be returned. The enumeration will be positioned on the object that caused the error.

If an error is returned, and GetNextObject is called again, an error may or may not be returned, depending upon whether the error condition still exists. If the error condition no longer exists (e.g., a "low memory" condition has been resolved), the numeration of objects will proceed normally starting at the current position of the enumeration.

Once all objects have been enumerated, DMARC_AT_ENUM_END is returned on all subsequent calls

The array pArray will contain references to the IUnknown interface for each of the returned objects. These interfaces must be released using the IUnknown::Release method when no longer needed by the client, and in all circumstances *piNumReturned reflects exactly the number of such interfaces. However, the client application may rely upon the fact that this number will be non-zero only in the case that the method returns DMARC_OK.

Return Values