IEnumOleUndoUnits
The IEnumOleUndoUnits
interface enumerates the undo units on the undo or redo stack.
When to Implement
The undo
manager implements this method to enumerate a list of undo units on the undo or
redo stack.
When to Use
Use the IEnumOleUndoUnits
interface to enumerate all the top level undo units on the undo or redo stack.
The
prototypes of the methods are as follows:
HRESULT Next(
|
ULONG cUndoUnits , |
//[in]Number of undo units returned in rgpcd |
|
CONNECTDATA **rgpcd , |
//[out]Array to receive enumerated undo units |
|
ULONG *pcFetched |
//[out]Pointer to actual number of undo units |
|
); |
|
HRESULT Skip(
|
ULONG cUndoUnits |
//[in]Number of undo units to skip |
|
); |
|
HRESULT Reset(void);
HRESULT Clone(
|
IEnumOleUndoUnits** ppEnum |
//[out]Indirect pointer to newly created enumerator |
|
); |
|
Remarks
IEnumOleUndoUnits::Next
Enumerates
the next specified number of undo units in the enumerator s list, returning
them in rgpcd along with the actual number of enumerated elements in pcFetched.
The caller is
responsible for calling the Release method for each element in the array
once this method returns successfully. If cUndoUnits is greater than
one, the caller must also pass a non-NULL pointer to pcFetched to get
the number of pointers it has to release.
E_NOTIMPL is
not allowed as a return value. If an error value is returned, no entries in the
rgpcd array are valid on exit and require no release.
IEnumOleUndoUnits::Skip
Instructs the
enumerator to skip the next specified number of elements in the enumerator so
that the next call to IEnumOleUndoUnits::Next will not return those elements.
IEnumOleUndoUnits::Reset
Instructs the
enumerator to position itself at the beginning of the list of elements.
There is no
guarantee that the same set of elements will be enumerated on each pass through
the list. It depends on the collection being enumerated. It is too expensive
for some collections, such as files in a directory, to maintain a specific
state.
IEnumOleUndoUnits::Clone
Creates
another undo unit enumerator with the same state as the current enumerator to
iterate over the same list. This method makes it possible to record a point in
the enumeration sequence in order to return to that point at a later time.
The caller
must release this new enumerator separately from the first enumerator.
See Also
IOleUndoManager, IOleUndoUnit