EtwWrite 函式 (wdm.h)
EtwWrite 函式是在核心模式驅動程式程式代碼中發佈事件的追蹤函式。
語法
NTSTATUS EtwWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
參數
[in] RegHandle
事件提供者註冊句柄的指標，如果事件提供者註冊成功， 則 EtwRegister 函式會傳回此指標。
[in] EventDescriptor
EVENT_DESCRIPTOR 結構的指標。
[in, optional] ActivityId
標識符，表示與事件相關聯的活動。 ActivityID 提供將相關事件分組的方式，並用於端對端追蹤。
[in] UserDataCount
UserData 中的EVENT_DATA_DESCRIPTOR結構數目。
[in, optional] UserData
EVENT_DATA_DESCRIPTOR 結構的陣列指標。
傳回值
如果事件已成功發佈， EtwWrite 會傳回STATUS_SUCCESS。
如果事件提供者註冊句柄的指標無效， EtwWrite 會傳回STATUS_INVALID_HANDLE。 呼叫 EtwWrite 之前，必須先註冊事件提供者。 如果 EtwWrite 無法記錄事件，也可以傳回STATUS_INVALID_HANDLE。
如果 UserDataCount 中指定的EVENT_DATA_DESCRIPTOR結構數目大於 128) 允許的最大 (數目， EtwWrite 會傳回STATUS_INVALID_PARAMETER。
如果指定 ActivityID ，但記憶體不足，無法記錄與事件相關聯的數據， EtwWrite 會傳回STATUS_NO_MEMORY。
如果未啟用任何會話的提供者， EtwWrite 會傳回STATUS_SUCCESS，而且不會記錄事件。
事件可能會因為數個原因而遺失;例如，如果事件速率太高，或事件大小大於緩衝區大小，則為 。 在這些情況下， EventsLost 計數器是對應記錄器之EVENT_TRACE_PROPERTIES結構的成員，會以未記錄的事件數目來更新。
備註
EtwWrite 函式是與使用者模式 EventWrite 函式相等的核心模式。 若要確保您發行的事件有取用者，您可以在呼叫 EtwWrite 之前呼叫 EtwEventEnabled 或 EtwProviderEnabled。
您必須先向 EtwRegister 註冊提供者，才能呼叫 EtwWrite 函式來發佈事件。 應該不會進行任何追蹤呼叫，其落在 EtwRegister 和 EtwUnregister 函式所系結的程式代碼之外。 為了獲得最佳效能，您可以在 DriverEntry 例程中呼叫 EtwRegister 函式和 DriverUnload 例程中的 EtwUnregister 函式。
如果您使用 EtwWrite 函式中的選擇性 UserData 參數來記錄其他事件數據，您可以使用 EventDataDescCreate 宏來簡化EVENT_DATA_DESCRIPTOR結構的建立。 下列範例會使用 EventDataDescCreate 宏，以裝置名稱及其狀態初始化EVENT_DATA_DESCRIPTOR結構。 EventDataDescCreate 宏會儲存數據 (指標，也就是不會儲存數據) 的複本。 指標必須維持有效狀態，直到 呼叫 EtwWrite 傳回為止。
您可以在任何 IRQL 呼叫 EtwWrite 。 不過，當 IRQL 大於APC_LEVEL時，傳遞至 EtwWrite、EtwWriteEx、EtwWriteString、EtwWriteTransfer 函式的任何數據都不得分頁。 也就是說，在 IRQL 上執行的任何核心模式例程大於APC_LEVEL都無法存取可分頁的記憶體。 傳遞至 EtwWrite、EtwWriteEx、EtwWriteString 和 EtwWriteTransfer 函式的數據必須位於系統空間記憶體中，不論 IRQL 是什麼。
範例
//
// Register the provider with ETW in DriverEntry
// Unregister the provider in DriverUnload
//
// Build the EVENT_DATA_DESCRIPTOR structures using
// the EventDataDescCreate macros
if (RegHandle != (REGHANDLE)NULL) {
//
// Log an Event with : DeviceNameLength
// DeviceName
// Status
//
EventDataDescCreate(&EventDataDescriptor[0],
(PVOID)&DeviceName.Length,
sizeof(USHORT));
EventDataDescCreate(&EventDataDescriptor[1],
(PVOID)DeviceName.Buffer,
DeviceName.Length);
EventDataDescCreate(&EventDataDescriptor[2],
(PVOID)&Status,
sizeof(ULONG));
EtwWrite(RegHandle, // Handle from EtwRegister
&StartEvent, // EventDescriptor
NULL, // Activity ID
3, // Number of data items
EventDataDescriptor); // Array of data descriptors
}
//
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Universal |
| 標頭 | wdm.h (包括 Wdm.h、Ntddk.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | 任何層級 (請參閱批注一節。) |