IOleParentUndoUnit::Close

Closes the specified parent undo unit.

HRESULT Close(
  IOleParentUndoUnit* pPUU, 
                 //Pointer to the currently open parent unit
  BOOL fCommit   //Indicates whether to keep or discard the unit
);
 

Parameters

pPUU

[in] Pointer to the currently open parent unit to be closed.

fCommit

[in] Indicates whether to keep or discard the unit. If TRUE, the unit is kept in the collection. If FALSE, the unit is discarded. This parameter is used to allow the client to discard an undo unit under construction if an error or a cancellation occurs.

Return Values

S_OK

The parent unit had open child units and it was successfully closed.

S_FALSE

The parent undo unit did not have an open child and it was successfully closed.

E_INVALIDARG

If pPUU does not match the currently open parent undo unit, then implementations of this method should return E_INVALIDARG without changing any internal state unless the parent unit is blocked.

Remarks

A parent undo unit knows it is being closed when it returns S_FALSE from this method. At that time, it should terminate any communication with other objects which may be giving data to it through private interfaces.

Note to Implementers

To process a Close, a parent undo unit first checks to see if it has an open child unit. If it does not, it returns S_FALSE.

If it does have a child unit open, it calls the Close method on the child. If the child returns S_FALSE, then the parent undo unit verifies that pPUU points to the child unit, and closes that child undo unit. If the child returns S_OK then it handled the Close internally and its parent should do nothing.

If the parent unit is blocked, it should check the pPUU parameter to determine the appropriate return code. If pPUU is pointing to itself, then it should return S_FALSE.

Otherwise, it should return S_OK; the fCommit parameter is ignored; and no action is taken.

If pPUU does not match the currently open parent undo unit, then implementations of this method should return E_INVALIDARG without changing any internal state. The only exception to this is if the unit is blocked.

Note to Callers

An error return indicates a fatal error condition.

The parent unit or undo manager must accept the undo unit if fCommit is TRUE.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later. New for OC96.
  Windows 95/98: Requires Windows 95 or later. New for OC96.
  Header: Declared in ocidl.h.

See Also

IOleUndoManager::Close