TdhFormatProperty-Funktion (tdh.h)

Artikel
08/26/2023

Formatiert einen Eigenschaftswert für die Anzeige.

Syntax

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
);

Parameter

[in] EventInfo

Eine TRACE_EVENT_INFO-Struktur , die die Ereignisinformationen enthält. Rufen Sie zum Abrufen dieser Struktur die TdhGetEventInformation-Funktion auf.

[in, optional] MapInfo

Eine EVENT_MAP_INFO Struktur , die Ganzzahl- und Bitwerte Zeichenfolgen zuordnet. Rufen Sie zum Abrufen dieser Struktur die TdhGetEventMapInformation-Funktion auf. Verwenden Sie zum Abrufen des Namens der Karte den MapNameOffset-Member der EVENT_PROPERTY_INFO-Struktur. Wenn Sie die Zuordnungsinformationen für eine zugeordnete Eigenschaft nicht angeben, formatiert die Funktion den Ganzzahl- oder Bitwert.

[in] PointerSize

Die Größe eines Zeigers in den Ereignisdaten. Um die Größe zu erhalten, greifen Sie auf die EVENT_RECORD zu. EventHeader.Flags-Member . Die Zeigergröße beträgt 4 Byte, wenn das flag EVENT_HEADER_FLAG_32_BIT_HEADER festgelegt ist. Andernfalls beträgt dies 8 Byte, wenn das flag EVENT_HEADER_FLAG_64_BIT_HEADER festgelegt ist. Die EVENT_RECORD-Struktur (evntcons.h) wird an Ihre [PEVENT_RECORD_CALLBACK Rückruffunktion] übergeben.

[in] PropertyInType

Der Eingabetyp der Eigenschaft. Verwenden Sie den InType-Member der EVENT_PROPERTY_INFO-Struktur , um diesen Parameter festzulegen.

[in] PropertyOutType

Der Ausgabetyp der Eigenschaft. Verwenden Sie den OutType-Member der EVENT_PROPERTY_INFO-Struktur , um diesen Parameter festzulegen.

[in] PropertyLength

Die Länge der Eigenschaft in Bytes. Verwenden Sie den Length-Member der EVENT_PROPERTY_INFO-Struktur , um diesen Parameter festzulegen.

[in] UserDataLength

Die Größe des UserData-Puffers in Bytes. Siehe Hinweise.

[in] UserData

Der Puffer, der die Ereignisdaten enthält. Siehe Hinweise.

[in, out] BufferSize

Die Größe des Pufferpuffers in Bytes. Wenn die Funktion erfolgreich ist, empfängt dieser Parameter die Größe des verwendeten Puffers. Wenn der Puffer zu klein ist, gibt die Funktion ERROR_INSUFFICIENT_BUFFER zurück und legt diesen Parameter auf die erforderliche Puffergröße fest. Wenn die Puffergröße bei der Eingabe null ist, werden keine Daten im Puffer zurückgegeben, und dieser Parameter empfängt die erforderliche Puffergröße.

[out, optional] Buffer

Ein vom Aufrufer zugeordneter Puffer, der den formatierten Eigenschaftswert enthält. Um die erforderliche Puffergröße zu bestimmen, legen Sie diesen Parameter auf NULL und BufferSize auf 0 (null) fest.

[out] UserDataConsumed

Die Länge der verbrauchten Ereignisdaten in Bytes. Verwenden Sie diesen Wert, um die Werte der Parameter UserData und UserDataLength anzupassen. Siehe Hinweise.

Rückgabewert

Gibt bei erfolgreicher Ausführung ERROR_SUCCESS zurück. Andernfalls gibt diese Funktion zusätzlich zu anderen einen der folgenden Rückgabecodes zurück.

Rückgabecode	Beschreibung
ERROR_INSUFFICIENT_BUFFER	Die Größe des pBuffer-Puffers ist zu klein. Verwenden Sie die erforderliche Puffergröße, die in pBufferSize festgelegt ist, um einen neuen Puffer zuzuweisen.
ERROR_INVALID_PARAMETER	Mindestens einer der Parameter ist ungültig.
ERROR_EVT_INVALID_EVENT_DATA	Die Ereignisdaten stimmen nicht mit der Ereignisdefinition im Manifest überein.

Hinweise

In der Regel rufen Sie diese Funktion in einer Schleife auf. Verwenden Sie die TRACE_EVENT_INFO. TopLevelPropertyCount-Member zum Steuern der Schleife (die TdhGetEventInformation-Funktion gibt die TRACE_EVENT_INFO-Struktur zurück). Bevor Sie in die Schleife wechseln, legen Sie die Parameter UserData und UserDataLength auf den Wert der Member UserData bzw . UserDataLength der EVENT_RECORD-Struktur fest. Die EVENT_RECORD-Struktur wird an Ihre [PEVENT_RECORD_CALLBACK Rückruffunktion] übergeben.

Bestimmen Sie, ob es sich bei der Eigenschaft um ein Array handelt. Die -Eigenschaft ist ein Array, wenn die EVENT_PROPERTY_INFO. Flags-Member ist auf PropertyParamCount festgelegt, oder der EVENT_PROPERTY_INFO.count-Member ist größer als 1. Rufen Sie die TdhFormatProperty-Funktion in einer Schleife basierend auf der Anzahl der Elemente im Array auf.

Nachdem Sie die TdhFormatProperty-Funktion aufgerufen haben , verwenden Sie den Parameterwert UserDataConsumed , um die neuen Werte der Parameter UserData und UserDataLength festzulegen (Subtrah UserDataConsumed von UserDataLength , und verwenden Sie UserDataLength , um den UserData-Zeiger zu erhöhen).

Wenn die Eigenschaft eine IP-V6-Adresse ist, müssen Sie den PropertyLength-Parameter auf die Größe der IN6_ADDR-Struktur festlegen. Die -Eigenschaft gilt als IP-V6-Adresse, wenn die folgenden Bedingungen erfüllt sind:

Das InType-Element der EVENT_PROPERTY_INFO-Struktur ist TDH_INTYPE_BINARY
Das OutType-Element der EVENT_PROPERTY_INFO-Struktur ist TDH_OUTTYPE_IPV6
Der Length-Member der EVENT_PROPERTY_INFO-Struktur ist 0.

Beispiele

Ein Beispiel zum Aufrufen dieser Funktion finden Sie unter Verwenden von TdhFormatProperty zum Nutzen von Ereignisdaten.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	tdh.h
Bibliothek	Tdh.lib
DLL	Tdh.dll

Freigeben über