ホーム › System.Diagnostics.Etw › RegisterTraceGuidsA

RegisterTraceGuidsA

関数

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

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

シグネチャ

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

DWORD RegisterTraceGuidsA(
    WMIDPREQUEST RequestAddress,
    void* RequestContext,   // optional
    const GUID* ControlGuid,
    DWORD GuidCount,
    TRACE_GUID_REGISTRATION* TraceGuidReg,   // optional
    LPCSTR MofImagePath,   // optional
    LPCSTR 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	LPCSTR	inoptional	このパラメーターはサポートされていません。NULL に設定してください。アプリケーションのセットアップ時に Mofcomp.exe を使用して MOF リソースを登録する必要があります。詳細については、 Publishing Your Event Schema を参照してください。 Windows XP with SP1、Windows XP、Windows 2000: MofResourceName で指定されたリソースを含む DLL または実行可能プログラムのパスを指定する、省略可能な文字列へのポインター。プロバイダーが使用するイベントトレースクラスに関する情報をイベントプロバイダーとコンシューマーが別のメカニズムで共有する場合、このパラメーターは NULL にできます。
MofResourceName	LPCSTR	inoptional	このパラメーターはサポートされていません。NULL に設定してください。アプリケーションのセットアップ時に Mofcomp.exe を使用して MOF リソースを登録する必要があります。詳細については、 Publishing Your Event Schema を参照してください。 Windows XP with SP1、Windows XP、Windows 2000: MofImagePath の文字列リソースを指定する、省略可能な文字列へのポインター。この文字列リソースには、プロバイダーがサポートするイベントトレースクラスを記述するバイナリ MOF ファイルの名前が含まれます。
RegistrationHandle	ULONGLONG*	out	プロバイダーの登録ハンドルを受け取ります。返されたハンドルは、 UnregisterTraceGuids 関数を呼び出すときに使用します。重要 DLL またはドライバーによって作成されたすべての登録ハンドルは、 DLL またはドライバーがアンロードされる前に登録解除する必要があります。プロバイダーが登録解除されていない場合、ETW がプロバイダーのコールバックを呼び出そうとしたときにクラッシュが発生します。

戻り値の型: DWORD

公式ドキュメント

RegisterTraceGuidsA (ANSI) 関数 (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 の呼び出しを代わりに管理します。

この関数は、Classic (Windows 2000 形式) のイベントプロバイダーハンドルを開きます。このハンドルは、 TraceEvent、 TraceEventInstance、 TraceMessage、 TraceMessageVa を介して MOF および TMF ベースの WPP ETW イベントを書き込むために使用できます。

メモ

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

プロバイダーの ControlGuid が以前に登録されて有効化されている場合、同じ ControlGuid を参照する後続の登録は自動的に有効化されます。

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

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

例

RegisterTraceGuids を使用する例については、 Writing Classic Events を参照してください。

メモ

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

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

各言語での呼び出し定義

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

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

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

<DllImport("ADVAPI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function RegisterTraceGuidsA(
    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.LPStr)> MofImagePath As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> MofResourceName As String,   ' LPCSTR 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 : LPCSTR optional
' MofResourceName : LPCSTR optional
' RegistrationHandle : ULONGLONG* out
Declare PtrSafe Function RegisterTraceGuidsA 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 String, _
    ByVal MofResourceName As String, _
    ByRef RegistrationHandle As LongLong) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RegisterTraceGuidsA = ctypes.windll.advapi32.RegisterTraceGuidsA
RegisterTraceGuidsA.restype = wintypes.DWORD
RegisterTraceGuidsA.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.LPCSTR,  # MofImagePath : LPCSTR optional
    wintypes.LPCSTR,  # MofResourceName : LPCSTR optional
    ctypes.POINTER(ctypes.c_ulonglong),  # RegistrationHandle : ULONGLONG* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
RegisterTraceGuidsA = Fiddle::Function.new(
  lib['RegisterTraceGuidsA'],
  [
    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 : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # MofResourceName : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # RegistrationHandle : ULONGLONG* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn RegisterTraceGuidsA(
        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 u8,  // LPCSTR optional
        MofResourceName: *const u8,  // LPCSTR optional
        RegistrationHandle: *mut u64  // ULONGLONG* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

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

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

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global RegisterTraceGuidsA "RegisterTraceGuidsA" sptr, sptr, var, int, var, str, str, var
; res = RegisterTraceGuidsA(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 : LPCSTR optional -> "str"
; MofResourceName : LPCSTR optional -> "str"
; RegistrationHandle : ULONGLONG* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global RegisterTraceGuidsA "RegisterTraceGuidsA" sptr, sptr, sptr, int, sptr, str, str, sptr
; res = RegisterTraceGuidsA(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 : LPCSTR optional -> "str"
; MofResourceName : LPCSTR optional -> "str"
; RegistrationHandle : ULONGLONG* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。