Share via

EventWriteString 函式 (evntprov.h)

  • 發行項

寫入包含字串做為其資料的 ETW 事件。 不應該使用此函式。

語法

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

參數

[in] RegHandle

提供者的註冊控制碼。 控制碼來自 EventRegister。 產生的事件將使用與控制碼相關聯的 ProviderId。

[in] Level

用來描述事件的嚴重性或重要性的 8 位數位。

重要

ProviderId、Level 和 Keyword 是篩選事件的主要方法。 其他類型的篩選是可行的，但額外負荷較高。 一律將非零層級和關鍵字指派給每個事件。

如需事件層級的詳細資訊 ，請參閱EVENT_DESCRIPTOR 。

[in] Keyword

64 位位元遮罩，用來指出事件類別集合中的事件成員資格。

重要

ProviderId、Level 和 Keyword 是篩選事件的主要方法。 其他類型的篩選是可行的，但額外負荷較高。 一律將非零層級和關鍵字指派給每個事件。

如需事件關鍵字的詳細資訊 ，請參閱EVENT_DESCRIPTOR 。

[in] String

要寫入為事件資料的 NUL 終止字串。

傳回值

如果成功或錯誤碼，則傳回 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 事件，發行組建通常應該忽略錯誤碼。

備註

此 API 不實用，不應使用。

  • 大部分的 ETW 分析工具都不支援不含資訊清單的僅限字串事件。
  • 如果沒有資訊清單，事件 (的重要資訊，例如提供者名稱、事件識別碼和事件名稱) 無法使用，因此即使分析工具支援僅限字串的事件，產生的事件仍難以使用。
  • 使用資訊清單時，此函式的行為幾乎與具有單一字串欄位之資訊清單型事件的程式碼完全相同。 不過，追蹤分析工具更能支援以資訊清單為基礎的事件。 此外，針對具有單一字串欄位的事件所產生 MC.exe 的程式碼比 EventWriteString 函式更有效率。

請考慮下列替代方案，而不是使用此 API：

  • 使用 TraceLoggingProvider.h 來撰寫 ETW 分析工具支援良好的事件、不使用資訊清單運作，以及包含提供者名稱和事件名稱等中繼資料。
  • 撰寫檢測資訊清單。 建立具有單一 NUL 終止字串值的簡單事件。 即使沒有資訊清單，您也可以撰寫和收集事件。 您只需要解碼所收集追蹤的資訊清單。

EventWriteString 會寫入包含指定字串之資料承載的事件。 此 API 幾乎相當於下列程式碼：

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

產生的事件與 EventWrite 所產生的任何其他事件相同，不同之處在于產生的事件已設定 EVENT_HEADER_FLAG_STRING_ONLY 旗標 (請參閱 EVENT_HEADER ，以取得事件旗標) 的相關資訊。

請注意，事件是以識別碼、版本、Opcode、工作和通道設定為 0 所撰寫。

請注意，事件會使用目前線程的活動識別碼。

即使解碼器找不到事件提供者的任何其他解碼資訊， EVENT_HEADER_FLAG_STRING_ONLY旗標 的 ETW 分析工具仍可擷取字串值。 不過，如果沒有資訊清單，工具將無法判斷事件的提供者名稱。

需求

   
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntprov.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

EventWrite

TraceLoggingProvider.h