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]Address of output variable that 
                              // receives the IEnumOleUndoUnits 
                              // interface pointer
);
 

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.

QuickInfo

  Windows NT: Use version 4.0 or later. New for OC96.
  Windows: Use Windows 95 or later. New for OC96.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.

See Also

IOleUndoManager, IOleUndoUnit