ホーム › System.Diagnostics.Etw › RegisterTraceGuidsW

RegisterTraceGuidsW

関数

クラシックETWプロバイダーのトレースGUIDを登録する(Unicode版)。

DLLADVAPI32.dll文字セットUnicode (-W)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// ADVAPI32.dll  (Unicode / -W)
#include <windows.h>

DWORD RegisterTraceGuidsW(
    WMIDPREQUEST RequestAddress,
    void* RequestContext,   // optional
    const GUID* ControlGuid,
    DWORD GuidCount,
    TRACE_GUID_REGISTRATION* TraceGuidReg,   // optional
    LPCWSTR MofImagePath,   // optional
    LPCWSTR MofResourceName,   // optional
    ULONGLONG* RegistrationHandle
);

パラメーター

名前	型	方向	説明
RequestAddress	WMIDPREQUEST	in	イベントトレースセッションによってプロバイダーが有効または無効にされたときに通知を受け取る ControlCallback 関数へのポインター。 EnableTrace 関数がこのコールバックをトリガーします。
RequestContext	void*	inoptional	RequestAddress で指定した関数に ETW が渡す、省略可能なプロバイダー定義のコンテキストへのポインター。
ControlGuid	GUID*	in	登録するプロバイダーのコントロール GUID (プロバイダー ID)。
GuidCount	DWORD	in	TraceGuidReg 配列の要素数。TraceGuidReg が NULL の場合は、このパラメーターに 0 を設定します。
TraceGuidReg	TRACE_GUID_REGISTRATION*	inoptional	TRACE_GUID_REGISTRATION 構造体の配列へのポインター。各要素は、プロバイダーが提供するイベントのカテゴリを識別します。入力時、各構造体の Guid メンバーには、登録するプロバイダーが割り当てたイベントトレースクラス GUID を格納します。クラス GUID は、プロバイダーが提供するイベントのカテゴリを識別します。プロバイダーは、イベントをログに記録するために TraceEvent 関数を呼び出すときに、同じクラス GUID を使用して EVENT_TRACE_HEADER の Guid メンバーを設定します。出力時、RegHandle メンバーは、そのイベントのクラス GUID 登録に対するハンドルを受け取ります。プロバイダーが TraceEventInstance 関数を呼び出す場合は、 TRACE_GUID_REGISTRATION の RegHandle メンバーを使用して、 EVENT_INSTANCE_HEADER の RegHandle メンバーを設定します。プロバイダーがイベントをログに記録するために TraceEvent 関数のみを呼び出す場合、このパラメーターは NULL にできます。プロバイダーがイベントをログに記録するために TraceEventInstance 関数を呼び出す場合、このパラメーターを NULL にすることはできません。
MofImagePath	LPCWSTR	inoptional	このパラメーターはサポートされていません。NULL を設定してください。アプリケーションのセットアップ時に Mofcomp.exe を使用して MOF リソースを登録してください。詳細については、イベントスキーマの公開を参照してください。 Windows XP with SP1、Windows XP、および Windows 2000: MofResourceName で指定されたリソースを含む DLL または実行可能プログラムのパスを指定する、省略可能な文字列へのポインター。イベントプロバイダーとコンシューマーが、プロバイダーの使用するイベントトレースクラスに関する情報を共有するために別の仕組みを使用する場合、このパラメーターは NULL にできます。
MofResourceName	LPCWSTR	inoptional	このパラメーターはサポートされていません。NULL を設定してください。アプリケーションのセットアップ時に Mofcomp.exe を使用して MOF リソースを登録してください。詳細については、イベントスキーマの公開を参照してください。 Windows XP with SP1、Windows XP、および Windows 2000: MofImagePath の文字列リソースを指定する、省略可能な文字列へのポインター。この文字列リソースには、プロバイダーがサポートするイベントトレースクラスを記述したバイナリ MOF ファイルの名前が含まれます。
RegistrationHandle	ULONGLONG*	out	プロバイダーの登録ハンドルを受け取ります。返されたハンドルは、 UnregisterTraceGuids 関数を呼び出すときに使用します。重要 DLL またはドライバーが作成したすべての登録ハンドルは、その DLL またはドライバーがアンロードされる前に登録解除する必要があります。プロバイダーが登録解除されていない場合、 ETW がプロバイダーのコールバックを呼び出そうとしたときにクラッシュが発生します。

戻り値の型: DWORD

公式ドキュメント

RegisterTraceGuidsW (Unicode) 関数 (evntrace.h) は今後使用しない関数であり、新しいコードでは代替として提供されている関数を使用してください。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値はシステムエラーコードのいずれかです。以下に、代表的なエラーとその原因を示します。

重要

コントローラーがプロバイダーを有効にするために EnableTrace を呼び出した時点でプロバイダーがまだ RegisterTraceGuids を呼び出していない場合、この関数は ControlCallback が返した値を返すこともあります。この場合、登録が成功していれば、RegisterTraceGuids はそのコールバックの戻り値を返します。

ERROR_INVALID_PARAMETER

次のいずれかに該当します。
- RequestAddress が NULL である。
- ControlGuid が NULL である。
- RegistrationHandle が NULL である。
Windows XP および Windows 2000: TraceGuidReg が NULL であるか、GuidCount が 0 以下である。

解説(Remarks)

メモ

ほとんどの開発者は、この関数を直接呼び出すことはありません。通常、開発者は ETW フレームワークを使用します。たとえば、TMF ベースの WPP は、RegisterTraceGuids、 TraceMessage、および UnregisterTraceGuids の呼び出しを代わりに管理します。

この関数は、クラシック (Windows 2000 スタイル) のイベントプロバイダーハンドルを開きます。このハンドルを使用すると、 TraceEvent、 TraceEventInstance、 TraceMessage、および TraceMessageVa を介して、 MOF ベースおよび TMF ベースの WPP ETW イベントを書き込めます。

メモ

EventWrite を介してマニフェストベースまたは TraceLogging ベースの ETW イベントを書き込む Windows Vista スタイルのプロバイダーハンドルを開くには、 EventRegister を使用します。

プロバイダーの ControlGuid が既に登録されて有効になっている場合、同じ ControlGuid を参照する以降の登録は自動的に有効になります。

1 つのプロセスは最大 1,024 個のプロバイダー GUID を登録できますが、プロセスが登録するプロバイダーの数は 1 つか 2 つに抑えてください。この上限には、この関数および EventRegister 関数を使用して登録したものが含まれます。

Windows Vista より前: プロセスが登録できるプロバイダーの数に制限はありません。

例

RegisterTraceGuids を使用する例については、クラシックイベントの書き込みを参照してください。

メモ

evntrace.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版と Unicode 版を自動的に選択するエイリアスとして RegisterTraceGuids を定義しています。エンコードニュートラルなエイリアスの使用と、エンコードニュートラルでないコードを混在させると、不一致によりコンパイルエラーまたは実行時エラーが発生する可能性があります。詳細については、関数プロトタイプの規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ADVAPI32.dll  (Unicode / -W)
#include <windows.h>

DWORD RegisterTraceGuidsW(
    WMIDPREQUEST RequestAddress,
    void* RequestContext,   // optional
    const GUID* ControlGuid,
    DWORD GuidCount,
    TRACE_GUID_REGISTRATION* TraceGuidReg,   // optional
    LPCWSTR MofImagePath,   // optional
    LPCWSTR MofResourceName,   // optional
    ULONGLONG* RegistrationHandle
);

[DllImport("ADVAPI32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint RegisterTraceGuidsW(
    IntPtr RequestAddress,   // WMIDPREQUEST
    IntPtr RequestContext,   // void* optional
    ref Guid ControlGuid,   // GUID*
    uint GuidCount,   // DWORD
    IntPtr TraceGuidReg,   // TRACE_GUID_REGISTRATION* optional
    [MarshalAs(UnmanagedType.LPWStr)] string MofImagePath,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string MofResourceName,   // LPCWSTR optional
    out ulong RegistrationHandle   // ULONGLONG* out
);

<DllImport("ADVAPI32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function RegisterTraceGuidsW(
    RequestAddress As IntPtr,   ' WMIDPREQUEST
    RequestContext As IntPtr,   ' void* optional
    ByRef ControlGuid As Guid,   ' GUID*
    GuidCount As UInteger,   ' DWORD
    TraceGuidReg As IntPtr,   ' TRACE_GUID_REGISTRATION* optional
    <MarshalAs(UnmanagedType.LPWStr)> MofImagePath As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> MofResourceName As String,   ' LPCWSTR optional
    <Out> ByRef RegistrationHandle As ULong   ' ULONGLONG* out
) As UInteger
End Function

' RequestAddress : WMIDPREQUEST
' RequestContext : void* optional
' ControlGuid : GUID*
' GuidCount : DWORD
' TraceGuidReg : TRACE_GUID_REGISTRATION* optional
' MofImagePath : LPCWSTR optional
' MofResourceName : LPCWSTR optional
' RegistrationHandle : ULONGLONG* out
Declare PtrSafe Function RegisterTraceGuidsW Lib "advapi32" ( _
    ByVal RequestAddress As LongPtr, _
    ByVal RequestContext As LongPtr, _
    ByVal ControlGuid As LongPtr, _
    ByVal GuidCount As Long, _
    ByVal TraceGuidReg As LongPtr, _
    ByVal MofImagePath As LongPtr, _
    ByVal MofResourceName As LongPtr, _
    ByRef RegistrationHandle As LongLong) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RegisterTraceGuidsW = ctypes.windll.advapi32.RegisterTraceGuidsW
RegisterTraceGuidsW.restype = wintypes.DWORD
RegisterTraceGuidsW.argtypes = [
    ctypes.c_void_p,  # RequestAddress : WMIDPREQUEST
    ctypes.POINTER(None),  # RequestContext : void* optional
    ctypes.c_void_p,  # ControlGuid : GUID*
    wintypes.DWORD,  # GuidCount : DWORD
    ctypes.c_void_p,  # TraceGuidReg : TRACE_GUID_REGISTRATION* optional
    wintypes.LPCWSTR,  # MofImagePath : LPCWSTR optional
    wintypes.LPCWSTR,  # MofResourceName : LPCWSTR optional
    ctypes.POINTER(ctypes.c_ulonglong),  # RegistrationHandle : ULONGLONG* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
RegisterTraceGuidsW = Fiddle::Function.new(
  lib['RegisterTraceGuidsW'],
  [
    Fiddle::TYPE_VOIDP,  # RequestAddress : WMIDPREQUEST
    Fiddle::TYPE_VOIDP,  # RequestContext : void* optional
    Fiddle::TYPE_VOIDP,  # ControlGuid : GUID*
    -Fiddle::TYPE_INT,  # GuidCount : DWORD
    Fiddle::TYPE_VOIDP,  # TraceGuidReg : TRACE_GUID_REGISTRATION* optional
    Fiddle::TYPE_VOIDP,  # MofImagePath : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # MofResourceName : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # RegistrationHandle : ULONGLONG* out
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "advapi32")]
extern "system" {
    fn RegisterTraceGuidsW(
        RequestAddress: *const core::ffi::c_void,  // WMIDPREQUEST
        RequestContext: *mut (),  // void* optional
        ControlGuid: *const GUID,  // GUID*
        GuidCount: u32,  // DWORD
        TraceGuidReg: *mut TRACE_GUID_REGISTRATION,  // TRACE_GUID_REGISTRATION* optional
        MofImagePath: *const u16,  // LPCWSTR optional
        MofResourceName: *const u16,  // LPCWSTR optional
        RegistrationHandle: *mut u64  // ULONGLONG* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ADVAPI32.dll", CharSet = CharSet.Unicode)]
public static extern uint RegisterTraceGuidsW(IntPtr RequestAddress, IntPtr RequestContext, ref Guid ControlGuid, uint GuidCount, IntPtr TraceGuidReg, [MarshalAs(UnmanagedType.LPWStr)] string MofImagePath, [MarshalAs(UnmanagedType.LPWStr)] string MofResourceName, out ulong RegistrationHandle);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_RegisterTraceGuidsW' -Namespace Win32 -PassThru
# $api::RegisterTraceGuidsW(RequestAddress, RequestContext, ControlGuid, GuidCount, TraceGuidReg, MofImagePath, MofResourceName, RegistrationHandle)

#uselib "ADVAPI32.dll"
#func global RegisterTraceGuidsW "RegisterTraceGuidsW" wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr
; RegisterTraceGuidsW RequestAddress, RequestContext, varptr(ControlGuid), GuidCount, varptr(TraceGuidReg), MofImagePath, MofResourceName, varptr(RegistrationHandle)   ; 戻り値は stat
; RequestAddress : WMIDPREQUEST -> "wptr"
; RequestContext : void* optional -> "wptr"
; ControlGuid : GUID* -> "wptr"
; GuidCount : DWORD -> "wptr"
; TraceGuidReg : TRACE_GUID_REGISTRATION* optional -> "wptr"
; MofImagePath : LPCWSTR optional -> "wptr"
; MofResourceName : LPCWSTR optional -> "wptr"
; RegistrationHandle : ULONGLONG* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global RegisterTraceGuidsW "RegisterTraceGuidsW" sptr, sptr, var, int, var, wstr, wstr, var
; res = RegisterTraceGuidsW(RequestAddress, RequestContext, ControlGuid, GuidCount, TraceGuidReg, MofImagePath, MofResourceName, RegistrationHandle)
; RequestAddress : WMIDPREQUEST -> "sptr"
; RequestContext : void* optional -> "sptr"
; ControlGuid : GUID* -> "var"
; GuidCount : DWORD -> "int"
; TraceGuidReg : TRACE_GUID_REGISTRATION* optional -> "var"
; MofImagePath : LPCWSTR optional -> "wstr"
; MofResourceName : LPCWSTR optional -> "wstr"
; RegistrationHandle : ULONGLONG* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global RegisterTraceGuidsW "RegisterTraceGuidsW" sptr, sptr, sptr, int, sptr, wstr, wstr, sptr
; res = RegisterTraceGuidsW(RequestAddress, RequestContext, varptr(ControlGuid), GuidCount, varptr(TraceGuidReg), MofImagePath, MofResourceName, varptr(RegistrationHandle))
; RequestAddress : WMIDPREQUEST -> "sptr"
; RequestContext : void* optional -> "sptr"
; ControlGuid : GUID* -> "sptr"
; GuidCount : DWORD -> "int"
; TraceGuidReg : TRACE_GUID_REGISTRATION* optional -> "sptr"
; MofImagePath : LPCWSTR optional -> "wstr"
; MofResourceName : LPCWSTR optional -> "wstr"
; RegistrationHandle : ULONGLONG* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。