EvtQuery function (winevt.h)

Article
10/13/2021

Runs a query to retrieve events from a channel or log file that match the specified query criteria.

Syntax

EVT_HANDLE EvtQuery(
  [in] EVT_HANDLE Session,
  [in] LPCWSTR    Path,
  [in] LPCWSTR    Query,
  [in] DWORD      Flags
);

Parameters

[in] Session

A remote session handle that the EvtOpenSession function returns. Set to NULL to query for events on the local computer.

[in] Path

The name of the channel or the full path to a log file that contains the events that you want to query. You can specify an .evt, .evtx, or.etl log file. The path is required if the Query parameter contains an XPath query; the path is ignored if the Query parameter contains a structured XML query and the query specifies the path.

[in] Query

A query that specifies the types of events that you want to retrieve. You can specify an XPath 1.0 query or structured XML query. If your XPath contains more than 20 expressions, use a structured XML query. To receive all events, set this parameter to NULL or "*".

[in] Flags

One or more flags that specify the order that you want to receive the events and whether you are querying against a channel or log file. For possible values, see the EVT_QUERY_FLAGS enumeration.

Return value

A handle to the query results if successful; otherwise, NULL. If the function returns NULL, call the GetLastError function to get the error code.

Remarks

To get events from the query results, call the EvtNext function. To retrieve events beginning with a specific event in the results, call the EvtSeek function.

You must call the EvtClose function with the query results handle when done.

You must only use the query handle that this function returns on the same thread that created the handle.

Examples

For an example that shows how to use this function, see Querying for Events.

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

Share via