EtwWrite 函式（wdm.h）

發行項
02/07/2025

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 函式是相當於 user-mode 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
    }              

//

要求

要求	價值
目標平臺	普遍
標頭	wdm.h （包括 Wdm.h、 Ntddk.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	任何層級（請參閱批注一節。