TdhFormatProperty 函式 (tdh.h)

  • 發行項

格式化要顯示的屬性值。

語法

TDHSTATUS TdhFormatProperty(
  [in]            PTRACE_EVENT_INFO EventInfo,
  [in, optional]  PEVENT_MAP_INFO   MapInfo,
  [in]            ULONG             PointerSize,
  [in]            USHORT            PropertyInType,
  [in]            USHORT            PropertyOutType,
  [in]            USHORT            PropertyLength,
  [in]            USHORT            UserDataLength,
  [in]            PBYTE             UserData,
  [in, out]       PULONG            BufferSize,
  [out, optional] PWCHAR            Buffer,
  [out]           PUSHORT           UserDataConsumed
);

參數

[in] EventInfo

包含事件資訊的 TRACE_EVENT_INFO結構 。 若要取得此結構，請呼叫 TdhGetEventInformation 函式。

[in, optional] MapInfo

EVENT_MAP_INFO 結構，會將整數和位值對應至字串。 若要取得此結構，請呼叫 TdhGetEventMapInformation 函式。 若要取得地圖的名稱，請使用 EVENT_PROPERTY_INFO 結構的MapNameOffset 成員。 如果您未提供對應屬性的對應資訊，函式會格式化整數或位值。

[in] PointerSize

事件數據中的指標值大小。 若要取得大小，請存取 EVENT_RECORD。EventHeader.Flags 成員。 如果已設定EVENT_HEADER_FLAG_32_BIT_HEADER旗標，則指標大小為 4 個字節;否則，如果已設定EVENT_HEADER_FLAG_64_BIT_HEADER旗標，則為8個字節。 EVENT_RECORD結構 (evntcons.h) 會傳遞至您的 [PEVENT_RECORD_CALLBACK 回呼函式]。

[in] PropertyInType

屬性的輸入類型。 使用 EVENT_PROPERTY_INFO 結構的InType 成員來設定此參數。

[in] PropertyOutType

屬性的輸出類型。 使用 EVENT_PROPERTY_INFO 結構的OutType 成員來設定此參數。

[in] PropertyLength

屬性的長度，以位元組為單位。 使用 EVENT_PROPERTY_INFO 結構的Length 成員來設定此參數。

[in] UserDataLength

UserData 緩衝區的大小，以位元組為單位。 請參閱＜備註＞。

[in] UserData

包含事件數據的緩衝區。 請參閱＜備註＞。

[in, out] BufferSize

Buffer 緩衝區的大小，以位元組為單位。 如果函式成功，此參數會收到所使用的緩衝區大小。 如果緩衝區太小，函式會傳回ERROR_INSUFFICIENT_BUFFER，並將此參數設定為所需的緩衝區大小。 如果輸入上的緩衝區大小為零，則緩衝區中不會傳回任何數據，而且此參數會收到所需的緩衝區大小。

[out, optional] Buffer

呼叫端配置的緩衝區，其中包含格式化的屬性值。 若要判斷所需的緩衝區大小，請將此參數設定為 NULL ，並將 BufferSize 設定為零。

[out] UserDataConsumed

已取用事件數據的長度，以位元組為單位。 使用此值來調整 UserData 和 UserDataLength 參數的值。 請參閱＜備註＞。

傳回值

如果成功，則傳回ERROR_SUCCESS。 否則，除了其他傳回碼之外，此函式還會傳回下列其中一個傳回碼。

傳回碼 Description
ERROR_INSUFFICIENT_BUFFER pBuffer 緩衝區的大小太小。 使用 pBufferSize 中設定的必要緩衝區大小來配置新的緩衝區。
ERROR_INVALID_PARAMETER 一或多個參數無效。
ERROR_EVT_INVALID_EVENT_DATA 事件數據不符合指令清單中的事件定義。

備註

一般而言，您會在迴圈中呼叫此函式。 使用 TRACE_EVENT_INFO。TdhGetEventInformation 函式 (控制迴圈的 TopLevelPropertyCount 成員會傳回 TRACE_EVENT_INFO結構) 。 進入迴圈之前，您會將UserData和UserDataLength參數分別設定為 EVENT_RECORD結構的UserData和UserDataLength成員的值。 EVENT_RECORD結構會傳遞至您的 [PEVENT_RECORD_CALLBACK回呼函式]。

判斷屬性是否為陣列。 如果EVENT_PROPERTY_INFO，則此屬性為陣列 。Flags 成員設定為 PropertyParamCount，或 EVENT_PROPERTY_INFO.count 成員大於 1。 根據陣列中的元素數目，在迴圈中呼叫 TdhFormatProperty 函式。

呼叫 TdhFormatProperty 函式之後，請使用 UserDataConsumed 參數值來設定 UserData 和 UserDataLength 參數的新值， (從 UserDataLength 減去 UserDataConsumed，並使用 UserDataLength 遞增 UserData 指標) 。

如果屬性是IP V6位址，您必須將 PropertyLength 參數設定為 IN6_ADDR 結構的大小。 如果符合下列條件，則會將 屬性視為IP V6 位址：

範例

如需示範如何呼叫此函式的範例，請參閱 使用 TdhFormatProperty 取用事件數據。

規格需求

需求 值
最低支援的用戶端 Windows 7 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 R2 [僅限桌面應用程式]
目標平台 Windows
標頭 tdh.h
程式庫 Tdh.lib
Dll Tdh.dll