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
程式庫	Wevtapi.lib
Dll	Wevtapi.dll

另請參閱

EVT_SUBSCRIBE_CALLBACK

EvtQuery