CoSetCancelObject

[This is preliminary documentation and subject to change.]

Sets (registers) or resets (unregisters) a cancel object for use during subsequent cancel operations on the current thread.

HRESULT CoSetCancelObject(
  IUnknown *pUnk  //Cancel object to be set or reset
);
 

Parameters

pUnk

Pointer to the IUnknown interface on the cancel object to be set or reset on the current thread. If NULL, the topmost cancel object is reset.

Return Values

This function supports the standard return values E_FAIL, E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The cancel object was successfully set or reset.

E_ACCESSDENIED

The cancel object cannot be set or reset at this time because of a block on cancel operations.

Remarks

For objects that support standard marshaling, the proxy object begins marshaling a method call by calling CoSetCancelObject to register a cancel object for the current thread.

CoSetCancelObject calls QueryInterface for ICancelMethodCalls on the cancel object. If the cancel object does not implement ICancelMethodCalls, CoSetCancelObject fails with E_NOINTERFACE. To disable cancel operations on a custom-marshaled interface, the implementation of ICancelMethodCalls::Cancel should do nothing but return E_NOTIMPL, E_FAIL, or some other appropriate value.

Before returning control to the client, the proxy unregisters the cancel object by calling CoSetCancelObject again, passing NULL as the parameter. In this case, CoSetCancelObject unregisters the cancel object and sets the next object in the cancel stack as the topmost cancel object. It is important that CoSetCancelObject be called when a method is called and again when it returns so the stack of cancel objects corresponds to the calling stack on the thread.

CoSetCancelObject calls IUnknown::AddRef on objects that it registers and Release on objects that it unregisters.

CoSetCancelObject does not set or reset cancel objects for asynchronous methods.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in objbase.h.
  Import Library: Included as a resource in ole32.dll.