evtSubscribe 函数 (winevt.h)

  • 项目

创建一个订阅，该订阅将从与指定查询条件匹配的通道或日志文件接收当前和将来的事件。

语法

EVT_HANDLE EvtSubscribe(
  [in] EVT_HANDLE             Session,
  [in] HANDLE                 SignalEvent,
  [in] LPCWSTR                ChannelPath,
  [in] LPCWSTR                Query,
  [in] EVT_HANDLE             Bookmark,
  [in] PVOID                  Context,
  [in] EVT_SUBSCRIBE_CALLBACK Callback,
  [in] DWORD                  Flags
);

参数

[in] Session

EvtOpenSession 函数返回的远程会话句柄。 设置为 NULL 以订阅本地计算机上的事件。

[in] SignalEvent

事件对象的句柄，服务将在有匹配查询条件的新事件可用时发出信号。 如果 Callback 参数不为 NULL，此参数必须为 NULL。

[in] ChannelPath

包含要订阅的事件管理员或操作通道的名称， (无法订阅分析或调试通道) 。 如果 Query 参数包含 XPath 查询，则路径是必需的;如果 Query 参数包含结构化 XML 查询，则忽略路径。

[in] Query

一个查询，指定希望订阅服务返回的事件类型。 可以指定 XPath 1.0 查询或结构化 XML 查询。 如果 XPath 包含的表达式超过 20 个，请使用结构化 XML 查询。 若要接收所有事件，请将此参数设置为 NULL 或“*”。

[in] Bookmark

书签的句柄，用于标识订阅的起点。 若要获取书签句柄，请调用 EvtCreateBookmark 函数。 如果 Flags 参数包含 EvtSubscribeStartAfterBookmark 标志，则必须设置此参数;否则为 NULL。

[in] Context

一个调用方定义的上下文值，订阅服务在每次传递事件时将传递给指定的回调。

[in] Callback

指向将接收订阅事件的 EVT_SUBSCRIBE_CALLBACK 回调函数的指针。 如果 SignalEvent 参数不为 NULL，此参数必须为 NULL。

[in] Flags

指定何时开始订阅事件的一个或多个标志。 例如，如果指定 EvtSubscribeStartAtOldestRecord，则服务将检索与查询条件匹配的所有当前和将来事件;但是，如果指定 EvtSubscribeToFutureEvents，则服务仅返回与查询条件匹配的未来事件。 有关可能的值，请参阅 EVT_SUBSCRIBE_FLAGS 枚举。

返回值

如果成功，则为订阅的句柄;否则为 NULL。 如果函数返回 NULL，请调用 GetLastError 函数以获取错误代码。 完成后，必须使用订阅句柄调用 EvtClose 函数。

注解

若要取消订阅，请将返回的订阅句柄传递给 EvtClose 函数。

有两种订阅模型：轮询模型和推送模型。 在推送模型中，实现订阅回调并将 Callback 参数设置为实现。 如果 (或) 发生错误，服务将为每个与查询条件匹配的事件调用回调。

在轮询模型中，创建服务发出信号的事件对象。 收到信号时，可以使用订阅句柄调用 EvtNext 函数来枚举事件。 必须对枚举的每个事件调用 EvtClose 函数。 然后重置对象并等待服务再次发出信号。 此过程将重复，直到取消订阅。

示例

有关演示如何使用此函数的示例，请参阅 订阅事件。

要求

   
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 winevt.h
Library Wevtapi.lib
DLL Wevtapi.dll

另请参阅

EVT_SUBSCRIBE_CALLBACK

EvtQuery