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

バッファー バッファーのサイズ (バイト単位)。 関数が成功した場合、このパラメーターは使用されるバッファーのサイズを受け取ります。 バッファーが小さすぎる場合、関数は ERROR_INSUFFICIENT_BUFFERを返し、このパラメーターを必要なバッファー サイズに設定します。 入力時にバッファー サイズが 0 の場合、バッファーにデータは返されません。このパラメーターは必要なバッファー サイズを受け取ります。

[out, optional] Buffer

書式設定されたプロパティ値を含む呼び出し元によって割り当てられたバッファー。 必要なバッファー サイズを確認するには、このパラメーターを NULL に設定し、 BufferSize を 0 に設定します。

[out] UserDataConsumed

使用されるイベント データの長さ (バイト単位)。 この値を使用して、UserData パラメーターと UserDataLength パラメーターの値を調整します。 「解説」を参照してください。

戻り値

成功した場合は、ERROR_SUCCESSを返します。 それ以外の場合、この関数は、他の戻りコードに加えて、次のいずれかのリターン コードを返します。

注釈

通常、この関数はループで呼び出します。 TRACE_EVENT_INFOを使用 します。ループを制御する TopLevelPropertyCount メンバー ( TdhGetEventInformation 関数 は 、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 アドレスと見なされます。

• EVENT_PROPERTY_INFO構造体の InType メンバーがTDH_INTYPE_BINARY
• EVENT_PROPERTY_INFO構造体の OutType メンバーがTDH_OUTTYPE_IPV6
• EVENT_PROPERTY_INFO構造体の Length メンバーは 0 です。

例

この関数を呼び出す方法を示す例については、「 TdhFormatProperty を使用してイベント データを使用する」を参照してください。

要件