Win32 API 日本語リファレンス
ホーム › System.Diagnostics.Etw › EnableTraceEx

EnableTraceEx

関数
キーワードやレベルを指定して拡張的にプロバイダーを有効化する。
DLLADVAPI32.dll呼出規約winapi対応OSWindows Vista 以降
📘 Microsoft Learn (日本語) · English

シグネチャ

// ADVAPI32.dll
#include <windows.h>

WIN32_ERROR EnableTraceEx(
    const GUID* ProviderId,
    const GUID* SourceId,   // optional
    ULONGLONG TraceId,
    DWORD IsEnabled,
    BYTE Level,
    ULONGLONG MatchAnyKeyword,
    ULONGLONG MatchAllKeyword,
    DWORD EnableProperty,
    EVENT_FILTER_DESCRIPTOR* EnableFilterDesc   // optional
);

パラメーター

名前型方向説明
ProviderIdGUID*in構成対象のイベントプロバイダーのプロバイダー ID (コントロール GUID)。
SourceIdGUID*inoptional

この構成要求の発生元を一意に識別できる GUID。発生元の識別が不要な場合は NULL を指定します (SourceId を &GUID_NULL に設定するのと同等です)。指定した場合、この値はプロバイダーの EnableCallback を呼び出す際の SourceId パラメーターとして使用されます。

メモ

EnableTrace の呼び出しと、対応するプロバイダーの EnableCallback の呼び出しが常に直接対応するとは限りません。たとえば、まだ登録されていないプロバイダーに対して EnableTrace が呼び出された場合、EnableCallback の呼び出しは登録が行われるまで延期されます。また、トレースコンシューマーのセッションが停止された場合、対応する EnableTrace の呼び出しがなくても ETW は EnableCallback を呼び出します。このような場合、EnableTrace は SourceId を GUID_NULL に設定して呼び出されます。

TraceIdULONGLONGinイベントを受け取るトレースセッションのハンドル。
IsEnabledDWORDinプロバイダーからのイベント受信を有効にする場合、またはイベント受信時の設定を調整する場合 (レベルやキーワードの変更など) は 1 を設定します。プロバイダーからのイベント受信を無効にする場合は 0 を設定します。
LevelBYTEin

プロバイダーに書き込ませるイベントの最大レベルを示す値。プロバイダーは通常、MatchAnyKeyword および MatchAllKeyword の条件を満たすことに加え、イベントのレベルがこの値以下である場合にイベントを書き込みます。

Microsoft はレベル 1〜5 のセマンティクスを以下のように定義しています。値が小さいほど深刻度の高いイベントを示します。EnableLevel の各値は、指定したレベルおよびそれより深刻なすべてのレベルを有効にします。たとえば TRACE_LEVEL_WARNING を指定すると、コンシューマーは警告、エラー、および重大イベントを受信します。

値 意味
TRACE_LEVEL_CRITICAL (1) 異常終了または停止イベント
TRACE_LEVEL_ERROR (2) 深刻なエラーイベント
TRACE_LEVEL_WARNING (3) 割り当て失敗などの警告イベント
TRACE_LEVEL_INFORMATION (4) エラー以外の情報イベント
TRACE_LEVEL_VERBOSE (5) 詳細な診断イベント

TRACE_LEVEL 定数は evntrace.h で定義されています。これと同等の WINMETA_LEVEL 定数は winmeta.h で定義されています。

MatchAnyKeywordULONGLONGinプロバイダーに書き込ませるイベントのカテゴリを決定するキーワードの 64 ビットビットマスク。プロバイダーは通常、Level および MatchAllKeyword の条件を満たすことに加え、イベントのキーワードビットがこの値で設定されたビットのいずれかに一致する場合、またはイベントにキーワードビットが設定されていない場合に、イベントを書き込みます。
MatchAllKeywordULONGLONGin

プロバイダーに書き込ませるイベントを制限するキーワードの 64 ビットビットマスク。プロバイダーは通常、Level および MatchAnyKeyword の条件を満たすことに加え、イベントのキーワードビットがこの値で設定されたすべてのビットに一致する場合、またはイベントにキーワードビットが設定されていない場合に、イベントを書き込みます。

この値は 0 に設定されることがよくあります。

EnablePropertyDWORDin

このプロバイダーからイベントを収集する際に、ETW ランタイムが有効にすべき特別な動作を指定するフラグ。特別な動作を有効にするには、以下のフラグのうち 1 つ以上を指定します。それ以外の場合は EnableProperty を 0 に設定します。

メモ

これらのフラグの一部は、ETW が各イベントに追加情報を含めるべきであることを示します。そのデータはイベントの 拡張データ項目 セクションに書き込まれます。

値 意味
EVENT_ENABLE_PROPERTY_SID ユーザーのセキュリティ識別子 (SID) を拡張データに含めます。
EVENT_ENABLE_PROPERTY_TS_ID ターミナルセッション識別子を拡張データに含めます。
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 トレースセッションはキーワードが 0 のイベントを記録しないようにします。
EnableFilterDescEVENT_FILTER_DESCRIPTOR*inoptional

フィルターデータを指す EVENT_FILTER_DESCRIPTOR 構造体。プロバイダーはこれを使用してデータをフィルター処理し、フィルター条件に一致しないイベントがセッションに書き込まれるのを防ぎます。データのレイアウトおよびイベントのデータへのフィルターの適用方法は、プロバイダーが決定します。セッションがプロバイダーに渡せるフィルターは 1 つだけです。

セッションは TdhEnumerateProviderFilters 関数を呼び出して、プロバイダーが登録時にサポートしているフィルターを調べることができます。

戻り値の型: WIN32_ERROR

公式ドキュメント

トレースセッションのコントローラーは、ETW イベントの構成方法を設定するために EnableTraceEx を呼び出します。

戻り値

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

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

解説(Remarks)

イベントトレースコントローラーは、セッションにイベントを書き込むイベントプロバイダーを構成するためにこの関数を呼び出します。たとえば、コントローラーはこの関数を呼び出して、プロバイダーからのイベント収集を開始したり、プロバイダーから収集するイベントのレベルやキーワードを調整したり、プロバイダーからのイベント収集を停止したりします。

この関数は廃止されました。追加機能を利用するには、新しいコードでは EnableTraceEx2 を使用してください。

ほとんどの場合、EnableTraceEx の呼び出しは次のように EnableTraceEx2 に変換できます。

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

より複雑なシナリオでは、EnableTraceEx の呼び出しは次のように EnableTraceEx2 に変換できます。

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

セッションのプロバイダーを構成する際のセマンティクスに関する詳細は、EnableTraceEx2 のドキュメントを参照してください。

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

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

WIN32_ERROR EnableTraceEx(
    const GUID* ProviderId,
    const GUID* SourceId,   // optional
    ULONGLONG TraceId,
    DWORD IsEnabled,
    BYTE Level,
    ULONGLONG MatchAnyKeyword,
    ULONGLONG MatchAllKeyword,
    DWORD EnableProperty,
    EVENT_FILTER_DESCRIPTOR* EnableFilterDesc   // optional
);
[DllImport("ADVAPI32.dll", ExactSpelling = true)]
static extern uint EnableTraceEx(
    ref Guid ProviderId,   // GUID*
    IntPtr SourceId,   // GUID* optional
    ulong TraceId,   // ULONGLONG
    uint IsEnabled,   // DWORD
    byte Level,   // BYTE
    ulong MatchAnyKeyword,   // ULONGLONG
    ulong MatchAllKeyword,   // ULONGLONG
    uint EnableProperty,   // DWORD
    IntPtr EnableFilterDesc   // EVENT_FILTER_DESCRIPTOR* optional
);
<DllImport("ADVAPI32.dll", ExactSpelling:=True)>
Public Shared Function EnableTraceEx(
    ByRef ProviderId As Guid,   ' GUID*
    SourceId As IntPtr,   ' GUID* optional
    TraceId As ULong,   ' ULONGLONG
    IsEnabled As UInteger,   ' DWORD
    Level As Byte,   ' BYTE
    MatchAnyKeyword As ULong,   ' ULONGLONG
    MatchAllKeyword As ULong,   ' ULONGLONG
    EnableProperty As UInteger,   ' DWORD
    EnableFilterDesc As IntPtr   ' EVENT_FILTER_DESCRIPTOR* optional
) As UInteger
End Function
' ProviderId : GUID*
' SourceId : GUID* optional
' TraceId : ULONGLONG
' IsEnabled : DWORD
' Level : BYTE
' MatchAnyKeyword : ULONGLONG
' MatchAllKeyword : ULONGLONG
' EnableProperty : DWORD
' EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional
Declare PtrSafe Function EnableTraceEx Lib "advapi32" ( _
    ByVal ProviderId As LongPtr, _
    ByVal SourceId As LongPtr, _
    ByVal TraceId As LongLong, _
    ByVal IsEnabled As Long, _
    ByVal Level As Byte, _
    ByVal MatchAnyKeyword As LongLong, _
    ByVal MatchAllKeyword As LongLong, _
    ByVal EnableProperty As Long, _
    ByVal EnableFilterDesc As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

EnableTraceEx = ctypes.windll.advapi32.EnableTraceEx
EnableTraceEx.restype = wintypes.DWORD
EnableTraceEx.argtypes = [
    ctypes.c_void_p,  # ProviderId : GUID*
    ctypes.c_void_p,  # SourceId : GUID* optional
    ctypes.c_ulonglong,  # TraceId : ULONGLONG
    wintypes.DWORD,  # IsEnabled : DWORD
    ctypes.c_ubyte,  # Level : BYTE
    ctypes.c_ulonglong,  # MatchAnyKeyword : ULONGLONG
    ctypes.c_ulonglong,  # MatchAllKeyword : ULONGLONG
    wintypes.DWORD,  # EnableProperty : DWORD
    ctypes.c_void_p,  # EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
EnableTraceEx = Fiddle::Function.new(
  lib['EnableTraceEx'],
  [
    Fiddle::TYPE_VOIDP,  # ProviderId : GUID*
    Fiddle::TYPE_VOIDP,  # SourceId : GUID* optional
    -Fiddle::TYPE_LONG_LONG,  # TraceId : ULONGLONG
    -Fiddle::TYPE_INT,  # IsEnabled : DWORD
    -Fiddle::TYPE_CHAR,  # Level : BYTE
    -Fiddle::TYPE_LONG_LONG,  # MatchAnyKeyword : ULONGLONG
    -Fiddle::TYPE_LONG_LONG,  # MatchAllKeyword : ULONGLONG
    -Fiddle::TYPE_INT,  # EnableProperty : DWORD
    Fiddle::TYPE_VOIDP,  # EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional
  ],
  -Fiddle::TYPE_INT)
#[link(name = "advapi32")]
extern "system" {
    fn EnableTraceEx(
        ProviderId: *const GUID,  // GUID*
        SourceId: *const GUID,  // GUID* optional
        TraceId: u64,  // ULONGLONG
        IsEnabled: u32,  // DWORD
        Level: u8,  // BYTE
        MatchAnyKeyword: u64,  // ULONGLONG
        MatchAllKeyword: u64,  // ULONGLONG
        EnableProperty: u32,  // DWORD
        EnableFilterDesc: *mut EVENT_FILTER_DESCRIPTOR  // EVENT_FILTER_DESCRIPTOR* optional
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ADVAPI32.dll")]
public static extern uint EnableTraceEx(ref Guid ProviderId, IntPtr SourceId, ulong TraceId, uint IsEnabled, byte Level, ulong MatchAnyKeyword, ulong MatchAllKeyword, uint EnableProperty, IntPtr EnableFilterDesc);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_EnableTraceEx' -Namespace Win32 -PassThru
# $api::EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
#uselib "ADVAPI32.dll"
#func global EnableTraceEx "EnableTraceEx" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; EnableTraceEx varptr(ProviderId), varptr(SourceId), TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, varptr(EnableFilterDesc)   ; 戻り値は stat
; ProviderId : GUID* -> "sptr"
; SourceId : GUID* optional -> "sptr"
; TraceId : ULONGLONG -> "sptr"
; IsEnabled : DWORD -> "sptr"
; Level : BYTE -> "sptr"
; MatchAnyKeyword : ULONGLONG -> "sptr"
; MatchAllKeyword : ULONGLONG -> "sptr"
; EnableProperty : DWORD -> "sptr"
; EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> "sptr"
; ※HSP3.7は int64 引数(64bit値渡し)に非対応です。
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数: 
#uselib "ADVAPI32.dll"
#cfunc global EnableTraceEx "EnableTraceEx" var, var, int64, int, int, int64, int64, int, var
; res = EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
; ProviderId : GUID* -> "var"
; SourceId : GUID* optional -> "var"
; TraceId : ULONGLONG -> "int64"
; IsEnabled : DWORD -> "int"
; Level : BYTE -> "int"
; MatchAnyKeyword : ULONGLONG -> "int64"
; MatchAllKeyword : ULONGLONG -> "int64"
; EnableProperty : DWORD -> "int"
; EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
; ※int64 引数の DLL 値渡しは x64 ランタイム(hsp3_64)のみ対応(x86 は未対応)。
出力引数: 
; WIN32_ERROR EnableTraceEx(GUID* ProviderId, GUID* SourceId, ULONGLONG TraceId, DWORD IsEnabled, BYTE Level, ULONGLONG MatchAnyKeyword, ULONGLONG MatchAllKeyword, DWORD EnableProperty, EVENT_FILTER_DESCRIPTOR* EnableFilterDesc)
#uselib "ADVAPI32.dll"
#cfunc global EnableTraceEx "EnableTraceEx" var, var, int64, int, int, int64, int64, int, var
; res = EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
; ProviderId : GUID* -> "var"
; SourceId : GUID* optional -> "var"
; TraceId : ULONGLONG -> "int64"
; IsEnabled : DWORD -> "int"
; Level : BYTE -> "int"
; MatchAnyKeyword : ULONGLONG -> "int64"
; MatchAllKeyword : ULONGLONG -> "int64"
; EnableProperty : DWORD -> "int"
; EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	advapi32 = windows.NewLazySystemDLL("ADVAPI32.dll")
	procEnableTraceEx = advapi32.NewProc("EnableTraceEx")
)

// ProviderId (GUID*), SourceId (GUID* optional), TraceId (ULONGLONG), IsEnabled (DWORD), Level (BYTE), MatchAnyKeyword (ULONGLONG), MatchAllKeyword (ULONGLONG), EnableProperty (DWORD), EnableFilterDesc (EVENT_FILTER_DESCRIPTOR* optional)
r1, _, err := procEnableTraceEx.Call(
	uintptr(ProviderId),
	uintptr(SourceId),
	uintptr(TraceId),
	uintptr(IsEnabled),
	uintptr(Level),
	uintptr(MatchAnyKeyword),
	uintptr(MatchAllKeyword),
	uintptr(EnableProperty),
	uintptr(EnableFilterDesc),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // WIN32_ERROR
function EnableTraceEx(
  ProviderId: PGUID;   // GUID*
  SourceId: PGUID;   // GUID* optional
  TraceId: UInt64;   // ULONGLONG
  IsEnabled: DWORD;   // DWORD
  Level: Byte;   // BYTE
  MatchAnyKeyword: UInt64;   // ULONGLONG
  MatchAllKeyword: UInt64;   // ULONGLONG
  EnableProperty: DWORD;   // DWORD
  EnableFilterDesc: Pointer   // EVENT_FILTER_DESCRIPTOR* optional
): DWORD; stdcall;
  external 'ADVAPI32.dll' name 'EnableTraceEx';
result := DllCall("ADVAPI32\EnableTraceEx"
    , "Ptr", ProviderId   ; GUID*
    , "Ptr", SourceId   ; GUID* optional
    , "Int64", TraceId   ; ULONGLONG
    , "UInt", IsEnabled   ; DWORD
    , "UChar", Level   ; BYTE
    , "Int64", MatchAnyKeyword   ; ULONGLONG
    , "Int64", MatchAllKeyword   ; ULONGLONG
    , "UInt", EnableProperty   ; DWORD
    , "Ptr", EnableFilterDesc   ; EVENT_FILTER_DESCRIPTOR* optional
    , "UInt")   ; return: WIN32_ERROR
●EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc) = DLL("ADVAPI32.dll", "dword EnableTraceEx(void*, void*, qword, dword, byte, qword, qword, dword, void*)")
# 呼び出し: EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
# ProviderId : GUID* -> "void*"
# SourceId : GUID* optional -> "void*"
# TraceId : ULONGLONG -> "qword"
# IsEnabled : DWORD -> "dword"
# Level : BYTE -> "byte"
# MatchAnyKeyword : ULONGLONG -> "qword"
# MatchAllKeyword : ULONGLONG -> "qword"
# EnableProperty : DWORD -> "dword"
# EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "advapi32" fn EnableTraceEx(
    ProviderId: [*c]GUID, // GUID*
    SourceId: [*c]GUID, // GUID* optional
    TraceId: u64, // ULONGLONG
    IsEnabled: u32, // DWORD
    Level: u8, // BYTE
    MatchAnyKeyword: u64, // ULONGLONG
    MatchAllKeyword: u64, // ULONGLONG
    EnableProperty: u32, // DWORD
    EnableFilterDesc: [*c]EVENT_FILTER_DESCRIPTOR // EVENT_FILTER_DESCRIPTOR* optional
) callconv(std.os.windows.WINAPI) u32;
proc EnableTraceEx(
    ProviderId: ptr GUID,  # GUID*
    SourceId: ptr GUID,  # GUID* optional
    TraceId: uint64,  # ULONGLONG
    IsEnabled: uint32,  # DWORD
    Level: uint8,  # BYTE
    MatchAnyKeyword: uint64,  # ULONGLONG
    MatchAllKeyword: uint64,  # ULONGLONG
    EnableProperty: uint32,  # DWORD
    EnableFilterDesc: ptr EVENT_FILTER_DESCRIPTOR  # EVENT_FILTER_DESCRIPTOR* optional
): uint32 {.importc: "EnableTraceEx", stdcall, dynlib: "ADVAPI32.dll".}
pragma(lib, "advapi32");
extern(Windows)
uint EnableTraceEx(
    GUID* ProviderId,   // GUID*
    GUID* SourceId,   // GUID* optional
    ulong TraceId,   // ULONGLONG
    uint IsEnabled,   // DWORD
    ubyte Level,   // BYTE
    ulong MatchAnyKeyword,   // ULONGLONG
    ulong MatchAllKeyword,   // ULONGLONG
    uint EnableProperty,   // DWORD
    EVENT_FILTER_DESCRIPTOR* EnableFilterDesc   // EVENT_FILTER_DESCRIPTOR* optional
);
ccall((:EnableTraceEx, "ADVAPI32.dll"), stdcall, UInt32,
      (Ptr{GUID}, Ptr{GUID}, UInt64, UInt32, UInt8, UInt64, UInt64, UInt32, Ptr{EVENT_FILTER_DESCRIPTOR}),
      ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
# ProviderId : GUID* -> Ptr{GUID}
# SourceId : GUID* optional -> Ptr{GUID}
# TraceId : ULONGLONG -> UInt64
# IsEnabled : DWORD -> UInt32
# Level : BYTE -> UInt8
# MatchAnyKeyword : ULONGLONG -> UInt64
# MatchAllKeyword : ULONGLONG -> UInt64
# EnableProperty : DWORD -> UInt32
# EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> Ptr{EVENT_FILTER_DESCRIPTOR}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
uint32_t EnableTraceEx(
    void* ProviderId,
    void* SourceId,
    uint64_t TraceId,
    uint32_t IsEnabled,
    uint8_t Level,
    uint64_t MatchAnyKeyword,
    uint64_t MatchAllKeyword,
    uint32_t EnableProperty,
    void* EnableFilterDesc);
]]
local advapi32 = ffi.load("advapi32")
-- advapi32.EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
-- ProviderId : GUID*
-- SourceId : GUID* optional
-- TraceId : ULONGLONG
-- IsEnabled : DWORD
-- Level : BYTE
-- MatchAnyKeyword : ULONGLONG
-- MatchAllKeyword : ULONGLONG
-- EnableProperty : DWORD
-- EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('ADVAPI32.dll');
const EnableTraceEx = lib.func('__stdcall', 'EnableTraceEx', 'uint32_t', ['void *', 'void *', 'uint64_t', 'uint32_t', 'uint8_t', 'uint64_t', 'uint64_t', 'uint32_t', 'void *']);
// EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
// ProviderId : GUID* -> 'void *'
// SourceId : GUID* optional -> 'void *'
// TraceId : ULONGLONG -> 'uint64_t'
// IsEnabled : DWORD -> 'uint32_t'
// Level : BYTE -> 'uint8_t'
// MatchAnyKeyword : ULONGLONG -> 'uint64_t'
// MatchAllKeyword : ULONGLONG -> 'uint64_t'
// EnableProperty : DWORD -> 'uint32_t'
// EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ADVAPI32.dll", {
  EnableTraceEx: { parameters: ["pointer", "pointer", "u64", "u32", "u8", "u64", "u64", "u32", "pointer"], result: "u32" },
});
// lib.symbols.EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc)
// ProviderId : GUID* -> "pointer"
// SourceId : GUID* optional -> "pointer"
// TraceId : ULONGLONG -> "u64"
// IsEnabled : DWORD -> "u32"
// Level : BYTE -> "u8"
// MatchAnyKeyword : ULONGLONG -> "u64"
// MatchAllKeyword : ULONGLONG -> "u64"
// EnableProperty : DWORD -> "u32"
// EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> "pointer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
uint32_t EnableTraceEx(
    void* ProviderId,
    void* SourceId,
    uint64_t TraceId,
    uint32_t IsEnabled,
    uint8_t Level,
    uint64_t MatchAnyKeyword,
    uint64_t MatchAllKeyword,
    uint32_t EnableProperty,
    void* EnableFilterDesc);
C, "ADVAPI32.dll");
// $ffi->EnableTraceEx(ProviderId, SourceId, TraceId, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc);
// ProviderId : GUID*
// SourceId : GUID* optional
// TraceId : ULONGLONG
// IsEnabled : DWORD
// Level : BYTE
// MatchAnyKeyword : ULONGLONG
// MatchAllKeyword : ULONGLONG
// EnableProperty : DWORD
// EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Advapi32 extends StdCallLibrary {
    Advapi32 INSTANCE = Native.load("advapi32", Advapi32.class);
    int EnableTraceEx(
        Pointer ProviderId,   // GUID*
        Pointer SourceId,   // GUID* optional
        long TraceId,   // ULONGLONG
        int IsEnabled,   // DWORD
        byte Level,   // BYTE
        long MatchAnyKeyword,   // ULONGLONG
        long MatchAllKeyword,   // ULONGLONG
        int EnableProperty,   // DWORD
        Pointer EnableFilterDesc   // EVENT_FILTER_DESCRIPTOR* optional
    );
}
@[Link("advapi32")]
lib LibADVAPI32
  fun EnableTraceEx = EnableTraceEx(
    ProviderId : GUID*,   # GUID*
    SourceId : GUID*,   # GUID* optional
    TraceId : UInt64,   # ULONGLONG
    IsEnabled : UInt32,   # DWORD
    Level : UInt8,   # BYTE
    MatchAnyKeyword : UInt64,   # ULONGLONG
    MatchAllKeyword : UInt64,   # ULONGLONG
    EnableProperty : UInt32,   # DWORD
    EnableFilterDesc : EVENT_FILTER_DESCRIPTOR*   # EVENT_FILTER_DESCRIPTOR* optional
  ) : UInt32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef EnableTraceExNative = Uint32 Function(Pointer<Void>, Pointer<Void>, Uint64, Uint32, Uint8, Uint64, Uint64, Uint32, Pointer<Void>);
typedef EnableTraceExDart = int Function(Pointer<Void>, Pointer<Void>, int, int, int, int, int, int, Pointer<Void>);
final EnableTraceEx = DynamicLibrary.open('ADVAPI32.dll')
    .lookupFunction<EnableTraceExNative, EnableTraceExDart>('EnableTraceEx');
// ProviderId : GUID* -> Pointer<Void>
// SourceId : GUID* optional -> Pointer<Void>
// TraceId : ULONGLONG -> Uint64
// IsEnabled : DWORD -> Uint32
// Level : BYTE -> Uint8
// MatchAnyKeyword : ULONGLONG -> Uint64
// MatchAllKeyword : ULONGLONG -> Uint64
// EnableProperty : DWORD -> Uint32
// EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function EnableTraceEx(
  ProviderId: PGUID;   // GUID*
  SourceId: PGUID;   // GUID* optional
  TraceId: UInt64;   // ULONGLONG
  IsEnabled: DWORD;   // DWORD
  Level: Byte;   // BYTE
  MatchAnyKeyword: UInt64;   // ULONGLONG
  MatchAllKeyword: UInt64;   // ULONGLONG
  EnableProperty: DWORD;   // DWORD
  EnableFilterDesc: Pointer   // EVENT_FILTER_DESCRIPTOR* optional
): DWORD; stdcall;
  external 'ADVAPI32.dll' name 'EnableTraceEx';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "EnableTraceEx"
  c_EnableTraceEx :: Ptr () -> Ptr () -> Word64 -> Word32 -> Word8 -> Word64 -> Word64 -> Word32 -> Ptr () -> IO Word32
-- ProviderId : GUID* -> Ptr ()
-- SourceId : GUID* optional -> Ptr ()
-- TraceId : ULONGLONG -> Word64
-- IsEnabled : DWORD -> Word32
-- Level : BYTE -> Word8
-- MatchAnyKeyword : ULONGLONG -> Word64
-- MatchAllKeyword : ULONGLONG -> Word64
-- EnableProperty : DWORD -> Word32
-- EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let enabletraceex =
  foreign "EnableTraceEx"
    ((ptr void) @-> (ptr void) @-> uint64_t @-> uint32_t @-> uint8_t @-> uint64_t @-> uint64_t @-> uint32_t @-> (ptr void) @-> returning uint32_t)
(* ProviderId : GUID* -> (ptr void) *)
(* SourceId : GUID* optional -> (ptr void) *)
(* TraceId : ULONGLONG -> uint64_t *)
(* IsEnabled : DWORD -> uint32_t *)
(* Level : BYTE -> uint8_t *)
(* MatchAnyKeyword : ULONGLONG -> uint64_t *)
(* MatchAllKeyword : ULONGLONG -> uint64_t *)
(* EnableProperty : DWORD -> uint32_t *)
(* EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library advapi32 (t "ADVAPI32.dll"))
(cffi:use-foreign-library advapi32)

(cffi:defcfun ("EnableTraceEx" enable-trace-ex :convention :stdcall) :uint32
  (provider-id :pointer)   ; GUID*
  (source-id :pointer)   ; GUID* optional
  (trace-id :uint64)   ; ULONGLONG
  (is-enabled :uint32)   ; DWORD
  (level :uint8)   ; BYTE
  (match-any-keyword :uint64)   ; ULONGLONG
  (match-all-keyword :uint64)   ; ULONGLONG
  (enable-property :uint32)   ; DWORD
  (enable-filter-desc :pointer))   ; EVENT_FILTER_DESCRIPTOR* optional
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $EnableTraceEx = Win32::API::More->new('ADVAPI32',
    'DWORD EnableTraceEx(LPVOID ProviderId, LPVOID SourceId, UINT64 TraceId, DWORD IsEnabled, BYTE Level, UINT64 MatchAnyKeyword, UINT64 MatchAllKeyword, DWORD EnableProperty, LPVOID EnableFilterDesc)');
# my $ret = $EnableTraceEx->Call($ProviderId, $SourceId, $TraceId, $IsEnabled, $Level, $MatchAnyKeyword, $MatchAllKeyword, $EnableProperty, $EnableFilterDesc);
# ProviderId : GUID* -> LPVOID
# SourceId : GUID* optional -> LPVOID
# TraceId : ULONGLONG -> UINT64
# IsEnabled : DWORD -> DWORD
# Level : BYTE -> BYTE
# MatchAnyKeyword : ULONGLONG -> UINT64
# MatchAllKeyword : ULONGLONG -> UINT64
# EnableProperty : DWORD -> DWORD
# EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* optional -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

類似 API
使用する型