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

ControlTraceW

関数
制御コードを指定してトレースセッションを制御する(Unicode版)。
DLLADVAPI32.dll文字セットUnicode (-W)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

WIN32_ERROR ControlTraceW(
    ULONGLONG TraceId,
    LPCWSTR InstanceName,   // optional
    EVENT_TRACE_PROPERTIES* Properties,
    EVENT_TRACE_CONTROL ControlCode
);

パラメーター

名前型方向説明
TraceIdULONGLONGin制御するトレースセッションのハンドル。0の場合は名前で特定。
InstanceNameLPCWSTRinoptional

イベントトレースセッションの名前、または NULL。TraceHandle が 0 の場合は、InstanceName を 指定する必要があります。

NT Kernel Logger セッションを指定するには、InstanceName を KERNEL_LOGGER_NAME に設定します。

PropertiesEVENT_TRACE_PROPERTIES*inout

初期化済みの EVENT_TRACE_PROPERTIES 構造体へのポインター。この構造体は、いずれかのフィールドを設定する前にゼロクリアしておく必要があります。

ControlCode が EVENT_TRACE_CONTROL_STOP、EVENT_TRACE_CONTROL_QUERY、または EVENT_TRACE_CONTROL_FLUSH を指定する場合は、 EVENT_TRACE_PROPERTIES 構造体の Wnode.BufferSize、Wnode.Guid、LoggerNameOffset、および LogFileNameOffset メンバーのみを設定すれば十分です。セッションがプライベートセッションの場合は、 LogFileMode も設定する必要があります。サイズやオフセットが不明な場合は、最大セッション名長 (1024 文字) と最大ログファイル名長 (1024 文字) を使用してバッファーサイズとオフセットを計算できます。

ControlCode が EVENT_TRACE_CONTROL_UPDATE を指定する場合、入力時には、各メンバーで更新する プロパティの新しい値を指定する必要があります。出力時には、Properties にイベントトレースセッションの プロパティと統計情報が格納されます。次のプロパティを更新できます。

  • EnableFlags: すべてのシステムプロバイダーを無効にするには、このメンバーを 0 に設定します。 有効にする、または有効のままにするシステムプロバイダーを指定するには、0 以外の値を設定します。 これが 0 以外になり得るのは システムロガー の場合のみです。

  • FlushTimer: バッファーをフラッシュするまでの待機時間を変更したい場合に、このメンバーを 設定します。このメンバーが 0 の場合、メンバーは更新されません。

  • LogFileNameOffset: 別のログファイルに切り替える、またはバッファリングモードのトレースを 新しいログファイルにフラッシュしたい場合に、このメンバーを設定します。このメンバーが 0 の場合、 ファイル名は更新されません。オフセットが 0 以外であり、かつログファイル名を変更しない場合、 この関数はエラーを返します。

  • LogFileMode: EVENT_TRACE_REAL_TIME_MODE のオン/オフを切り替えたい場合に、このメンバーを 設定します。リアルタイム消費をオフにするには、このメンバーを 0 に設定します。リアルタイム消費を オンにする (ディスクへの記録に加えてイベントをリアルタイムで配信するセッションを作成する) には、 このメンバーを EVENT_TRACE_REAL_TIME_MODE に設定します。これは現在のモードと OR 演算されます。

  • MaximumBuffers: ETW が使用するバッファーの最大数を変更したい場合に、このメンバーを設定します。 このメンバーが 0 の場合、メンバーは更新されません。

プライベートロガーセッションの場合は、LogFileNameOffset メンバーと FlushTimer メンバーのみを 更新できます。

新しく初期化した EVENT_TRACE_PROPERTIES 構造体を使用する場合は、構造体をゼロクリアしてから、Wnode.BufferSize、Wnode.Guid、 Wnode.Flags、および更新したい値を設定します。

EVENT_TRACE_PROPERTIES 構造体を再利用する場合 (つまり、以前に StartTrace または ControlTrace に 渡した構造体を使用する場合) は、ログファイル名を変更しない限り LogFileNameOffset メンバーを 0 に設定し、 EVENT_TRACE_PROPERTIES.Wnode.Flags を WNODE_FLAG_TRACED_GUID に設定してください。

Windows 10 バージョン 1703 以降: プロセス間シナリオでのパフォーマンスを向上させるため、 システム全体のプライベートロガーに対してフィルタリング情報を ControlTrace に渡せるように なりました。フィルタリング情報を含めるには、 EVENT_TRACE_PROPERTIES_V2 構造体を使用する必要があります。詳細については、 Configuring and Starting a Private Logger Session を参照してください。

ControlCodeEVENT_TRACE_CONTROLin

要求する制御機能。次のいずれかの値を指定できます。

  • EVENT_TRACE_CONTROL_FLUSH: セッションのアクティブなバッファーをフラッシュします。

    これは、インメモリセッション (EVENT_TRACE_BUFFERING_MODE フラグで開始したセッション) で 使用して、トレースのデータをファイルに書き込むことができます。

    通常、ファイルベースのセッションやリアルタイムセッションをフラッシュする必要はありません。 ETW は、バッファーがいっぱいになったとき (つまり次のイベントを格納する空き容量がなくなったとき)、 トレースセッションの FlushTimer が満了したとき、またはトレースセッションが閉じられたときに、 自動的にバッファーをフラッシュするためです。

    Windows 2000: この値はサポートされていません。

  • EVENT_TRACE_CONTROL_QUERY: セッションのプロパティと統計情報を取得します。

  • EVENT_TRACE_CONTROL_STOP: セッションを停止します。セッションハンドルは無効になります。

  • EVENT_TRACE_CONTROL_UPDATE: セッションのプロパティを更新します。

  • EVENT_TRACE_CONTROL_INCREMENT_FILE: セッションが EVENT_TRACE_FILE_MODE_NEWFILE を 使用している場合、前のファイルがいっぱいになるのを待たずに、ただちに次のファイルに切り替えるよう セッションを更新します。Windows 10 October 2018 Update 以降でサポートされています。

  • EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: ファイルモードセッションをリアルタイムセッションに 変更します (リアルタイム配信を有効にし、ETL ファイルへのイベント書き込みを無効にします)。 Windows 10 October 2020 Update 以降でサポートされています。

メモ

DllMain からバッファーをフラッシュしたりトレースセッションを停止したりするのは安全ではありません (デッドロックを引き起こす可能性があります)。

戻り値の型: WIN32_ERROR

公式ドキュメント

ControlTraceW (Unicode) 関数 (evntrace.h) は、指定したイベントトレースセッションをフラッシュ、クエリ、更新、または停止します。

戻り値

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

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

解説(Remarks)

イベントトレースコントローラーがこの関数を呼び出します。

この関数は、 FlushTrace、 QueryTrace、 StopTrace、および UpdateTrace 関数に代わるものです。

メモ

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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>

WIN32_ERROR ControlTraceW(
    ULONGLONG TraceId,
    LPCWSTR InstanceName,   // optional
    EVENT_TRACE_PROPERTIES* Properties,
    EVENT_TRACE_CONTROL ControlCode
);
[DllImport("ADVAPI32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint ControlTraceW(
    ulong TraceId,   // ULONGLONG
    [MarshalAs(UnmanagedType.LPWStr)] string InstanceName,   // LPCWSTR optional
    IntPtr Properties,   // EVENT_TRACE_PROPERTIES* in/out
    uint ControlCode   // EVENT_TRACE_CONTROL
);
<DllImport("ADVAPI32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function ControlTraceW(
    TraceId As ULong,   ' ULONGLONG
    <MarshalAs(UnmanagedType.LPWStr)> InstanceName As String,   ' LPCWSTR optional
    Properties As IntPtr,   ' EVENT_TRACE_PROPERTIES* in/out
    ControlCode As UInteger   ' EVENT_TRACE_CONTROL
) As UInteger
End Function
' TraceId : ULONGLONG
' InstanceName : LPCWSTR optional
' Properties : EVENT_TRACE_PROPERTIES* in/out
' ControlCode : EVENT_TRACE_CONTROL
Declare PtrSafe Function ControlTraceW Lib "advapi32" ( _
    ByVal TraceId As LongLong, _
    ByVal InstanceName As LongPtr, _
    ByVal Properties As LongPtr, _
    ByVal ControlCode As Long) 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

ControlTraceW = ctypes.windll.advapi32.ControlTraceW
ControlTraceW.restype = wintypes.DWORD
ControlTraceW.argtypes = [
    ctypes.c_ulonglong,  # TraceId : ULONGLONG
    wintypes.LPCWSTR,  # InstanceName : LPCWSTR optional
    ctypes.c_void_p,  # Properties : EVENT_TRACE_PROPERTIES* in/out
    wintypes.DWORD,  # ControlCode : EVENT_TRACE_CONTROL
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
ControlTraceW = Fiddle::Function.new(
  lib['ControlTraceW'],
  [
    -Fiddle::TYPE_LONG_LONG,  # TraceId : ULONGLONG
    Fiddle::TYPE_VOIDP,  # InstanceName : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # Properties : EVENT_TRACE_PROPERTIES* in/out
    -Fiddle::TYPE_INT,  # ControlCode : EVENT_TRACE_CONTROL
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "advapi32")]
extern "system" {
    fn ControlTraceW(
        TraceId: u64,  // ULONGLONG
        InstanceName: *const u16,  // LPCWSTR optional
        Properties: *mut EVENT_TRACE_PROPERTIES,  // EVENT_TRACE_PROPERTIES* in/out
        ControlCode: u32  // EVENT_TRACE_CONTROL
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ADVAPI32.dll", CharSet = CharSet.Unicode)]
public static extern uint ControlTraceW(ulong TraceId, [MarshalAs(UnmanagedType.LPWStr)] string InstanceName, IntPtr Properties, uint ControlCode);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_ControlTraceW' -Namespace Win32 -PassThru
# $api::ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
#uselib "ADVAPI32.dll"
#func global ControlTraceW "ControlTraceW" wptr, wptr, wptr, wptr
; ControlTraceW TraceId, InstanceName, varptr(Properties), ControlCode   ; 戻り値は stat
; TraceId : ULONGLONG -> "wptr"
; InstanceName : LPCWSTR optional -> "wptr"
; Properties : EVENT_TRACE_PROPERTIES* in/out -> "wptr"
; ControlCode : EVENT_TRACE_CONTROL -> "wptr"
; ※HSP3.7は int64 引数(64bit値渡し)に非対応です。
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "ADVAPI32.dll"
#cfunc global ControlTraceW "ControlTraceW" int64, wstr, var, int
; res = ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
; TraceId : ULONGLONG -> "int64"
; InstanceName : LPCWSTR optional -> "wstr"
; Properties : EVENT_TRACE_PROPERTIES* in/out -> "var"
; ControlCode : EVENT_TRACE_CONTROL -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
; ※int64 引数の DLL 値渡しは x64 ランタイム(hsp3_64)のみ対応(x86 は未対応)。
出力引数:
; WIN32_ERROR ControlTraceW(ULONGLONG TraceId, LPCWSTR InstanceName, EVENT_TRACE_PROPERTIES* Properties, EVENT_TRACE_CONTROL ControlCode)
#uselib "ADVAPI32.dll"
#cfunc global ControlTraceW "ControlTraceW" int64, wstr, var, int
; res = ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
; TraceId : ULONGLONG -> "int64"
; InstanceName : LPCWSTR optional -> "wstr"
; Properties : EVENT_TRACE_PROPERTIES* in/out -> "var"
; ControlCode : EVENT_TRACE_CONTROL -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	advapi32 = windows.NewLazySystemDLL("ADVAPI32.dll")
	procControlTraceW = advapi32.NewProc("ControlTraceW")
)

// TraceId (ULONGLONG), InstanceName (LPCWSTR optional), Properties (EVENT_TRACE_PROPERTIES* in/out), ControlCode (EVENT_TRACE_CONTROL)
r1, _, err := procControlTraceW.Call(
	uintptr(TraceId),
	uintptr(unsafe.Pointer(windows.StringToUTF16Ptr(InstanceName))),
	uintptr(Properties),
	uintptr(ControlCode),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // WIN32_ERROR
function ControlTraceW(
  TraceId: UInt64;   // ULONGLONG
  InstanceName: PWideChar;   // LPCWSTR optional
  Properties: Pointer;   // EVENT_TRACE_PROPERTIES* in/out
  ControlCode: DWORD   // EVENT_TRACE_CONTROL
): DWORD; stdcall;
  external 'ADVAPI32.dll' name 'ControlTraceW';
result := DllCall("ADVAPI32\ControlTraceW"
    , "Int64", TraceId   ; ULONGLONG
    , "WStr", InstanceName   ; LPCWSTR optional
    , "Ptr", Properties   ; EVENT_TRACE_PROPERTIES* in/out
    , "UInt", ControlCode   ; EVENT_TRACE_CONTROL
    , "UInt")   ; return: WIN32_ERROR
●ControlTraceW(TraceId, InstanceName, Properties, ControlCode) = DLL("ADVAPI32.dll", "dword ControlTraceW(qword, char*, void*, dword)")
# 呼び出し: ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
# TraceId : ULONGLONG -> "qword"
# InstanceName : LPCWSTR optional -> "char*"
# Properties : EVENT_TRACE_PROPERTIES* in/out -> "void*"
# ControlCode : EVENT_TRACE_CONTROL -> "dword"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※-W(Unicode)関数。なでしこ1はANSIのため -A 版の利用を推奨。
const std = @import("std");

extern "advapi32" fn ControlTraceW(
    TraceId: u64, // ULONGLONG
    InstanceName: [*c]const u16, // LPCWSTR optional
    Properties: [*c]EVENT_TRACE_PROPERTIES, // EVENT_TRACE_PROPERTIES* in/out
    ControlCode: u32 // EVENT_TRACE_CONTROL
) callconv(std.os.windows.WINAPI) u32;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc ControlTraceW(
    TraceId: uint64,  # ULONGLONG
    InstanceName: WideCString,  # LPCWSTR optional
    Properties: ptr EVENT_TRACE_PROPERTIES,  # EVENT_TRACE_PROPERTIES* in/out
    ControlCode: uint32  # EVENT_TRACE_CONTROL
): uint32 {.importc: "ControlTraceW", stdcall, dynlib: "ADVAPI32.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "advapi32");
extern(Windows)
uint ControlTraceW(
    ulong TraceId,   // ULONGLONG
    const(wchar)* InstanceName,   // LPCWSTR optional
    EVENT_TRACE_PROPERTIES* Properties,   // EVENT_TRACE_PROPERTIES* in/out
    uint ControlCode   // EVENT_TRACE_CONTROL
);
ccall((:ControlTraceW, "ADVAPI32.dll"), stdcall, UInt32,
      (UInt64, Cwstring, Ptr{EVENT_TRACE_PROPERTIES}, UInt32),
      TraceId, InstanceName, Properties, ControlCode)
# TraceId : ULONGLONG -> UInt64
# InstanceName : LPCWSTR optional -> Cwstring
# Properties : EVENT_TRACE_PROPERTIES* in/out -> Ptr{EVENT_TRACE_PROPERTIES}
# ControlCode : EVENT_TRACE_CONTROL -> UInt32
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
uint32_t ControlTraceW(
    uint64_t TraceId,
    const uint16_t* InstanceName,
    void* Properties,
    uint32_t ControlCode);
]]
local advapi32 = ffi.load("advapi32")
-- advapi32.ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
-- TraceId : ULONGLONG
-- InstanceName : LPCWSTR optional
-- Properties : EVENT_TRACE_PROPERTIES* in/out
-- ControlCode : EVENT_TRACE_CONTROL
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
const koffi = require('koffi');
const lib = koffi.load('ADVAPI32.dll');
const ControlTraceW = lib.func('__stdcall', 'ControlTraceW', 'uint32_t', ['uint64_t', 'str16', 'void *', 'uint32_t']);
// ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
// TraceId : ULONGLONG -> 'uint64_t'
// InstanceName : LPCWSTR optional -> 'str16'
// Properties : EVENT_TRACE_PROPERTIES* in/out -> 'void *'
// ControlCode : EVENT_TRACE_CONTROL -> 'uint32_t'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ADVAPI32.dll", {
  ControlTraceW: { parameters: ["u64", "buffer", "pointer", "u32"], result: "u32" },
});
// lib.symbols.ControlTraceW(TraceId, InstanceName, Properties, ControlCode)
// TraceId : ULONGLONG -> "u64"
// InstanceName : LPCWSTR optional -> "buffer"
// Properties : EVENT_TRACE_PROPERTIES* in/out -> "pointer"
// ControlCode : EVENT_TRACE_CONTROL -> "u32"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
uint32_t ControlTraceW(
    uint64_t TraceId,
    const uint16_t* InstanceName,
    void* Properties,
    uint32_t ControlCode);
C, "ADVAPI32.dll");
// $ffi->ControlTraceW(TraceId, InstanceName, Properties, ControlCode);
// TraceId : ULONGLONG
// InstanceName : LPCWSTR optional
// Properties : EVENT_TRACE_PROPERTIES* in/out
// ControlCode : EVENT_TRACE_CONTROL
// 構造体/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, W32APIOptions.UNICODE_OPTIONS);
    int ControlTraceW(
        long TraceId,   // ULONGLONG
        WString InstanceName,   // LPCWSTR optional
        Pointer Properties,   // EVENT_TRACE_PROPERTIES* in/out
        int ControlCode   // EVENT_TRACE_CONTROL
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("advapi32")]
lib LibADVAPI32
  fun ControlTraceW = ControlTraceW(
    TraceId : UInt64,   # ULONGLONG
    InstanceName : UInt16*,   # LPCWSTR optional
    Properties : EVENT_TRACE_PROPERTIES*,   # EVENT_TRACE_PROPERTIES* in/out
    ControlCode : UInt32   # EVENT_TRACE_CONTROL
  ) : UInt32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef ControlTraceWNative = Uint32 Function(Uint64, Pointer<Utf16>, Pointer<Void>, Uint32);
typedef ControlTraceWDart = int Function(int, Pointer<Utf16>, Pointer<Void>, int);
final ControlTraceW = DynamicLibrary.open('ADVAPI32.dll')
    .lookupFunction<ControlTraceWNative, ControlTraceWDart>('ControlTraceW');
// TraceId : ULONGLONG -> Uint64
// InstanceName : LPCWSTR optional -> Pointer<Utf16>
// Properties : EVENT_TRACE_PROPERTIES* in/out -> Pointer<Void>
// ControlCode : EVENT_TRACE_CONTROL -> Uint32
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function ControlTraceW(
  TraceId: UInt64;   // ULONGLONG
  InstanceName: PWideChar;   // LPCWSTR optional
  Properties: Pointer;   // EVENT_TRACE_PROPERTIES* in/out
  ControlCode: DWORD   // EVENT_TRACE_CONTROL
): DWORD; stdcall;
  external 'ADVAPI32.dll' name 'ControlTraceW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "ControlTraceW"
  c_ControlTraceW :: Word64 -> CWString -> Ptr () -> Word32 -> IO Word32
-- TraceId : ULONGLONG -> Word64
-- InstanceName : LPCWSTR optional -> CWString
-- Properties : EVENT_TRACE_PROPERTIES* in/out -> Ptr ()
-- ControlCode : EVENT_TRACE_CONTROL -> Word32
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let controltracew =
  foreign "ControlTraceW"
    (uint64_t @-> (ptr uint16_t) @-> (ptr void) @-> uint32_t @-> returning uint32_t)
(* TraceId : ULONGLONG -> uint64_t *)
(* InstanceName : LPCWSTR optional -> (ptr uint16_t) *)
(* Properties : EVENT_TRACE_PROPERTIES* in/out -> (ptr void) *)
(* ControlCode : EVENT_TRACE_CONTROL -> uint32_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library advapi32 (t "ADVAPI32.dll"))
(cffi:use-foreign-library advapi32)

(cffi:defcfun ("ControlTraceW" control-trace-w :convention :stdcall) :uint32
  (trace-id :uint64)   ; ULONGLONG
  (instance-name (:string :encoding :utf-16le))   ; LPCWSTR optional
  (properties :pointer)   ; EVENT_TRACE_PROPERTIES* in/out
  (control-code :uint32))   ; EVENT_TRACE_CONTROL
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $ControlTraceW = Win32::API::More->new('ADVAPI32',
    'DWORD ControlTraceW(UINT64 TraceId, LPCWSTR InstanceName, LPVOID Properties, DWORD ControlCode)');
# my $ret = $ControlTraceW->Call($TraceId, $InstanceName, $Properties, $ControlCode);
# TraceId : ULONGLONG -> UINT64
# InstanceName : LPCWSTR optional -> LPCWSTR
# Properties : EVENT_TRACE_PROPERTIES* in/out -> LPVOID
# ControlCode : EVENT_TRACE_CONTROL -> DWORD
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い
使用する型