Edit

EvtCancel function (winevt.h)

  • Article

Cancels all pending operations on a handle.

Syntax

BOOL EvtCancel(
  EVT_HANDLE Object
);

Parameters

Object

The handle whose operation you want to cancel. You can cancel the following operations:

To cancel the EvtClearLog, EvtExportLog, EvtQuery, and EvtSubscribe operations, you must pass the session handle. To specify the default session (local session), set this parameter to NULL.

Return value

Return code/value Description
TRUE
 The function succeeded.
FALSE
 The function failed. To get the error code, call the GetLastError function.

Remarks

Use this function to cancel long-running operations. For example, calling the EvtNext function could theoretically take a long time due to the filtering of thousands of event records. Calling EvtCancel would stop the EvtNext function from processing further event records. Note that the function may not be able to stop the operation immediately.

You must call the EvtClose function to close the handle when done.

The following procedure describes how to cancel a long-running operation.

To cancel a long-running operation

  1. Thread A calls a long running operation (for example, the EvtSeek function).
  2. Thread B wants to cancel and close all operations, so thread B calls the EvtCancel function.
  3. Thread B then waits for all pending calls to complete (by synchronizing with thread A). Because the EvtCancel function was called, thread A should complete soon after the call to the EvtCancel was made.
  4. After thread A has fully completed the operation (EvtSeek), thread B can close the query result handle using the EvtClose function.
The operation being stopped will return with an error code of ERROR_CANCELLED.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header winevt.h
Library Wevtapi.lib
DLL Wevtapi.dll