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

CloseTrace

関数
ProcessTraceで開いたトレースハンドルを閉じる。
DLLADVAPI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

WIN32_ERROR CloseTrace(
    PROCESSTRACE_HANDLE TraceHandle
);

パラメーター

名前方向説明
TraceHandlePROCESSTRACE_HANDLEin閉じるトレース処理セッションへのハンドル。 OpenTrace 関数がこのハンドルを返します。

戻り値の型: WIN32_ERROR

公式ドキュメント

CloseTrace 関数は、作成されたトレース処理セッションを閉じます。

戻り値

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

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

解説(Remarks)

コンシューマーは、OpenTrace が返したトレース ハンドルを閉じるためにこの関数を呼び出します。

重要

この関数を使用して StartTrace が返したトレース ハンドルを閉じないでください。

ログ ファイルからイベントを処理している場合は、 ProcessTrace 関数が 戻った後にのみこの関数を呼び出します。ただし、リアルタイム イベントを処理している場合は、 ProcessTrace が戻る前にこの関数を呼び出すことができます。(トレース処理を停止する別の方法として、 BufferCallback から FALSE を返す方法もあります。)

ProcessTrace が戻る前にこの関数を呼び出した場合、CloseTrace 関数は ERROR_CTX_CLOSE_PENDING を返します。ERROR_CTX_CLOSE_PENDING コードは、 CloseTrace 関数の呼び出しが成功したことを示します。ProcessTrace 関数は、 以前にキューに入れられたすべてのイベントを処理した後にイベントの処理を停止します (CloseTrace 関数を呼び出した後、ProcessTrace は新しいイベントを受信しません)。 CloseTrace 関数は、BufferCallbackEventCallback、または EventClassCallback コールバックから呼び出すことができます。

Windows Vista より前: CloseTrace は、 ProcessTrace が戻った後にのみ呼び出すことができます。

CloseTrace を使用する例については、 TDH を使用したイベント データの取得を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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 CloseTrace(
    PROCESSTRACE_HANDLE TraceHandle
);
[DllImport("ADVAPI32.dll", ExactSpelling = true)]
static extern uint CloseTrace(
    PROCESSTRACE_HANDLE TraceHandle   // PROCESSTRACE_HANDLE
);
<DllImport("ADVAPI32.dll", ExactSpelling:=True)>
Public Shared Function CloseTrace(
    TraceHandle As PROCESSTRACE_HANDLE   ' PROCESSTRACE_HANDLE
) As UInteger
End Function
' TraceHandle : PROCESSTRACE_HANDLE
Declare PtrSafe Function CloseTrace Lib "advapi32" ( _
    ByVal TraceHandle As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

CloseTrace = ctypes.windll.advapi32.CloseTrace
CloseTrace.restype = wintypes.DWORD
CloseTrace.argtypes = [
    PROCESSTRACE_HANDLE,  # TraceHandle : PROCESSTRACE_HANDLE
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
CloseTrace = Fiddle::Function.new(
  lib['CloseTrace'],
  [
    Fiddle::TYPE_VOIDP,  # TraceHandle : PROCESSTRACE_HANDLE
  ],
  -Fiddle::TYPE_INT)
#[link(name = "advapi32")]
extern "system" {
    fn CloseTrace(
        TraceHandle: PROCESSTRACE_HANDLE  // PROCESSTRACE_HANDLE
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ADVAPI32.dll")]
public static extern uint CloseTrace(PROCESSTRACE_HANDLE TraceHandle);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_CloseTrace' -Namespace Win32 -PassThru
# $api::CloseTrace(TraceHandle)
#uselib "ADVAPI32.dll"
#func global CloseTrace "CloseTrace" sptr
; CloseTrace TraceHandle   ; 戻り値は stat
; TraceHandle : PROCESSTRACE_HANDLE -> "sptr"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "ADVAPI32.dll"
#cfunc global CloseTrace "CloseTrace" int
; res = CloseTrace(TraceHandle)
; TraceHandle : PROCESSTRACE_HANDLE -> "int"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; WIN32_ERROR CloseTrace(PROCESSTRACE_HANDLE TraceHandle)
#uselib "ADVAPI32.dll"
#cfunc global CloseTrace "CloseTrace" int
; res = CloseTrace(TraceHandle)
; TraceHandle : PROCESSTRACE_HANDLE -> "int"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	advapi32 = windows.NewLazySystemDLL("ADVAPI32.dll")
	procCloseTrace = advapi32.NewProc("CloseTrace")
)

// TraceHandle (PROCESSTRACE_HANDLE)
r1, _, err := procCloseTrace.Call(
	uintptr(TraceHandle),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // WIN32_ERROR
function CloseTrace(
  TraceHandle: PROCESSTRACE_HANDLE   // PROCESSTRACE_HANDLE
): DWORD; stdcall;
  external 'ADVAPI32.dll' name 'CloseTrace';
result := DllCall("ADVAPI32\CloseTrace"
    , "Ptr", TraceHandle   ; PROCESSTRACE_HANDLE
    , "UInt")   ; return: WIN32_ERROR
●CloseTrace(TraceHandle) = DLL("ADVAPI32.dll", "dword CloseTrace(void*)")
# 呼び出し: CloseTrace(TraceHandle)
# TraceHandle : PROCESSTRACE_HANDLE -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "advapi32" fn CloseTrace(
    TraceHandle: PROCESSTRACE_HANDLE // PROCESSTRACE_HANDLE
) callconv(std.os.windows.WINAPI) u32;
proc CloseTrace(
    TraceHandle: PROCESSTRACE_HANDLE  # PROCESSTRACE_HANDLE
): uint32 {.importc: "CloseTrace", stdcall, dynlib: "ADVAPI32.dll".}
pragma(lib, "advapi32");
extern(Windows)
uint CloseTrace(
    PROCESSTRACE_HANDLE TraceHandle   // PROCESSTRACE_HANDLE
);
ccall((:CloseTrace, "ADVAPI32.dll"), stdcall, UInt32,
      (PROCESSTRACE_HANDLE,),
      TraceHandle)
# TraceHandle : PROCESSTRACE_HANDLE -> PROCESSTRACE_HANDLE
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
uint32_t CloseTrace(
    PROCESSTRACE_HANDLE TraceHandle);
]]
local advapi32 = ffi.load("advapi32")
-- advapi32.CloseTrace(TraceHandle)
-- TraceHandle : PROCESSTRACE_HANDLE
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('ADVAPI32.dll');
const CloseTrace = lib.func('__stdcall', 'CloseTrace', 'uint32_t', ['PROCESSTRACE_HANDLE']);
// CloseTrace(TraceHandle)
// TraceHandle : PROCESSTRACE_HANDLE -> 'PROCESSTRACE_HANDLE'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ADVAPI32.dll", {
  CloseTrace: { parameters: ["buffer"], result: "u32" },
});
// lib.symbols.CloseTrace(TraceHandle)
// TraceHandle : PROCESSTRACE_HANDLE -> "buffer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
uint32_t CloseTrace(
    PROCESSTRACE_HANDLE TraceHandle);
C, "ADVAPI32.dll");
// $ffi->CloseTrace(TraceHandle);
// TraceHandle : PROCESSTRACE_HANDLE
// 構造体/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 CloseTrace(
        PROCESSTRACE_HANDLE /* extends Structure (by value) */ TraceHandle   // PROCESSTRACE_HANDLE
    );
}
@[Link("advapi32")]
lib LibADVAPI32
  fun CloseTrace = CloseTrace(
    TraceHandle : PROCESSTRACE_HANDLE   # PROCESSTRACE_HANDLE
  ) : UInt32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef CloseTraceNative = Uint32 Function(PROCESSTRACE_HANDLE);
typedef CloseTraceDart = int Function(int);
final CloseTrace = DynamicLibrary.open('ADVAPI32.dll')
    .lookupFunction<CloseTraceNative, CloseTraceDart>('CloseTrace');
// TraceHandle : PROCESSTRACE_HANDLE -> PROCESSTRACE_HANDLE
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function CloseTrace(
  TraceHandle: PROCESSTRACE_HANDLE   // PROCESSTRACE_HANDLE
): DWORD; stdcall;
  external 'ADVAPI32.dll' name 'CloseTrace';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "CloseTrace"
  c_CloseTrace :: PROCESSTRACE_HANDLE -> IO Word32
-- TraceHandle : PROCESSTRACE_HANDLE -> PROCESSTRACE_HANDLE
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
-- ※値渡し構造体は GHC FFI で直接渡せません。Ptr で渡すラッパ(C側)経由にしてください。
open Ctypes
open Foreign

let closetrace =
  foreign "CloseTrace"
    (PROCESSTRACE_HANDLE @-> returning uint32_t)
(* TraceHandle : PROCESSTRACE_HANDLE -> PROCESSTRACE_HANDLE *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library advapi32 (t "ADVAPI32.dll"))
(cffi:use-foreign-library advapi32)

(cffi:defcfun ("CloseTrace" close-trace :convention :stdcall) :uint32
  (trace-handle (:struct processtrace-handle)))   ; PROCESSTRACE_HANDLE
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $CloseTrace = Win32::API::More->new('ADVAPI32',
    'DWORD CloseTrace(LPVOID TraceHandle)');
# my $ret = $CloseTrace->Call($TraceHandle);
# TraceHandle : PROCESSTRACE_HANDLE -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

使用する型