EventWrite 函式 (evntprov.h)
寫入使用目前線程活動識別碼的 ETW 事件。
語法
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
參數
[in] RegHandle
提供者的註冊控制碼。 控制碼來自 EventRegister。 產生的事件將使用與控制碼相關聯的 ProviderId。
[in] EventDescriptor
使用 事件資訊EVENT_DESCRIPTOR (中繼資料) ，包括識別碼、版本、層級、關鍵字、通道、Opcode 和工作。
重要
ProviderId、Level 和 Keyword 是篩選事件的主要方法。 其他類型的篩選是可行的，但額外負荷較高。 一律將非零層級和關鍵字指派給每個事件。
[in] UserDataCount
UserData中的EVENT_DATA_DESCRIPTOR結構數目。 最大數目為 128。
[in, optional] UserData
UserDataCount的陣列EVENT_DATA_DESCRIPTOR結構，描述要包含在事件中的資料。 如果UserDataCount為零，則 UserData可能是Null。
每個 EVENT_DATA_DESCRIPTOR 都會描述事件中要包含的一個記憶體區塊。 指定的區塊會依序串連，沒有填補或對齊方式，以形成事件內容。 如果使用以資訊清單為基礎的解碼，事件內容必須符合與資訊清單中事件相關聯之範本中指定的配置。
傳回值
如果成功或錯誤碼，則傳回 ERROR_SUCCESS 。 可能的錯誤碼包括下列各項：
- ERROR_INVALID_PARAMETER：一或多個參數無效。
- ERROR_INVALID_HANDLE：提供者的註冊控制碼無效。
- ERROR_ARITHMETIC_OVERFLOW：事件大小大於允許的最大 (64KB - 標頭) 。
- ERROR_MORE_DATA：會話緩衝區大小對事件而言太小。
- ERROR_NOT_ENOUGH_MEMORY：當填滿緩衝區嘗試排清到磁片時發生，但磁片 IO 的速度不夠快。 當磁片變慢且事件流量過重時，就會發生這種情況。 最後，沒有任何可用 (空的) 緩衝區，而且會卸載事件。
- STATUS_LOG_FILE_FULL：即時播放檔案已滿。 事件不會記錄到會話，直到即時取用者從播放檔案取用事件為止。
錯誤碼主要是用於偵錯和診斷案例。 大部分的生產程式碼應該繼續執行並繼續報告事件，即使無法撰寫 ETW 事件，發行組建通常應該忽略錯誤碼。
備註
大部分的事件提供者都不會直接呼叫 EventWrite 。 相反地，大部分的事件提供者都是使用 ETW 架構來實作，以包裝 對 EventRegister、 EventWrite和 EventUnregister的呼叫。 例如，您可以 撰寫事件資訊清單 ，然後使用 訊息編譯 程式為事件產生 C/C++ 程式碼，或者您可以使用 TraceLogging 來避免資訊清單的需求。
EventWrite 會根據 RegHandle) 、Level、Keyword 和其他事件特性所決定的 ProviderId (，將事件路由傳送至適當的追蹤會話。 如果沒有追蹤會話正在錄製此事件，此函式不會執行任何動作，並 傳回ERROR_SUCCESS。
若要減少任何追蹤會話未記錄之事件的效能影響，您可以呼叫 EventEnabled 來判斷是否有任何追蹤會話正在記錄事件，再準備資料和呼叫 EventWrite。
EventWrite 會將事件的活動識別碼設定為目前線程的活動識別碼。 EventWrite 不會在 事件中包含相關的活動識別碼。 若要指定不同的活動識別碼或新增相關的活動識別碼，請使用 EventWriteTransfer。
EventWrite相當於EventWriteEx，Filter為 0、旗標為 0、ActivityId為Null，以及 RelatedActivityId的Null。
需求
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | evntprov.h |
| 程式庫 | Advapi32.lib |
| Dll | Advapi32.dll |