Share via

TraceMessageVa 函式 (evntrace.h)

  • 發行項

RegisterTraceGuids型 (「傳統」) 事件提供者會使用TraceMessageVa函式，使用 va_list 參數將訊息型 (TMF 型 WPP) 事件傳送至事件追蹤會話。

語法

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

參數

[in] LoggerHandle

處理記錄事件的事件追蹤會話。 提供者在其ControlCallback實作中呼叫GetTraceLoggerHandle函式時，會取得控制碼。

[in] MessageFlags

將其他資訊新增至事件的提供者特定資料區段開頭。 事件的提供者特定資料區段只會包含已設定之旗標的資料。 引數資料的變數清單將遵循這項資訊。 此參數可以是下列一或多個值。

  • TRACE_MESSAGE_GUID：在訊息中包含事件追蹤類別 GUID。 MessageGuid參數包含事件追蹤類別 GUID。

  • TRACE_MESSAGE_SEQUENCE：在訊息中包含序號。 序號從一開始。 若要使用此旗標，控制器必須在建立會話時設定 EVENT_TRACE_USE_GLOBAL_SEQUENCE 或 EVENT_TRACE_USE_LOCAL_SEQUENCE 記錄檔模式。

  • TRACE_MESSAGE_SYSTEMINFO：在訊息中包含執行緒識別碼和進程識別碼。

  • TRACE_MESSAGE_TIMESTAMP：在訊息中包含時間戳記。

資訊會依下列順序包含在事件資料中：

  • 序號
  • 事件追蹤類別 GUID
  • 時間戳記
  • 執行緒識別碼
  • 進程識別碼

[in] MessageGuid

識別事件追蹤訊息的類別 GUID。

[in] MessageNumber

可唯一識別每一個訊息出現次數的數位。 您必須定義為此參數指定的值;值應該對應用程式有意義。

[in] MessageArgList

要附加至訊息的變數引數清單。 清單必須由一組引數組成，如下所示。

  • PVOID：引數資料的指標。
  • size_t：引數資料的大小，以位元組為單位。

使用包含 Null 和零指標的引數組終止清單。

呼叫端必須確定引數的大小總和 + 72 不會超過事件追蹤會話緩衝區的大小。

傳回值

如果函式成功，傳回值會ERROR_SUCCESS。

如果函式失敗，傳回值就是其中一個 系統錯誤碼。 下表包含一些常見的錯誤及其原因。

  • ERROR_INVALID_HANDLE

    LoggerHandle為Null或指定 NT 核心記錄器會話控制碼。

  • ERROR_NOT_ENOUGH_MEMORY

    工作階段的可用寫入緩衝區不足。 當事件發生率偏高時，就會發生這種情形，而原因則是磁碟子系統已超載，或是緩衝區數目太少。 TraceMessage會捨棄事件，而不是封鎖直到有更多緩衝區可用為止。

    Windows 2000 和 Windows XP： 不支援。

  • ERROR_OUTOFMEMORY

    事件會被捨棄，因為雖然緩衝集區尚未達到其大小上限，但記憶體不足，無法配置額外的緩衝區，而且沒有緩衝區可供接收事件。

  • ERROR_INVALID_PARAMETER

    MessageFlags 包含不正確值。

  • ERROR_MORE_DATA

    來自單一事件的資料無法跨越多個緩衝區。 追蹤事件受限於事件追蹤會話緩衝區的大小減去 EVENT_TRACE_HEADER 結構的大小。

備註

TMF 型 WPP 提供者會呼叫此函式。

注意

大部分開發人員都不會直接呼叫此函式。 WPP 提供者會使用 tracewpp.exe 所產生的包裝函式，而不是呼叫 ETW API。

如果您不需要從包裝函式存取訊息追蹤功能，您可以呼叫此函式的 TraceMessage 版本。

如果MessageFlags參數不包含TRACE_MESSAGE_GUID旗標，取用者必須使用EventCallback 回呼來接收和處理事件。 如果您未指定TRACE_MESSAGE_GUID旗標，取用者將無法使用EventClassCallback，因為EVENT_TRACE結構的Header.Guid成員將不會包含事件追蹤類別 GUID。

請注意，只有在指定對應的旗標時，才會設定對應至MessageFlags旗標之EVENT_TRACE和EVENT_TRACE_HEADER結構的成員。 例如，只有在您指定TRACE_MESSAGE_SYSTEMINFO旗標時，才會填入EVENT_TRACE_HEADER的ThreadId和ProcessId成員。

需求

   
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 evntrace.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

TraceEvent

TraceEventInstance

TraceMessage