Win32 API 日本語リファレンス
ホームNetworkManagement.IpHelper › IcmpCloseHandle

IcmpCloseHandle

関数
ICMPエコー要求用に開いたハンドルを閉じる。
DLLIPHLPAPI.dll呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

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

BOOL IcmpCloseHandle(
    HANDLE IcmpHandle
);

パラメーター

名前方向説明
IcmpHandleHANDLEin閉じるハンドル。このハンドルは、IcmpCreateFile または Icmp6CreateFile の呼び出しによって返されたものでなければなりません。

戻り値の型: BOOL

公式ドキュメント

IcmpCloseHandle 関数は、IcmpCreateFile 関数または Icmp6CreateFile 関数の呼び出しによって開かれたハンドルを閉じます。

戻り値

ハンドルが正常に閉じられた場合、戻り値は TRUE です。それ以外の場合は FALSE です。拡張エラー情報を取得するには、 GetLastError 関数を呼び出してください。

解説(Remarks)

IcmpCloseHandle 関数は、Windows 2000 では Icmp.dll からエクスポートされます。IcmpCloseHandle 関数は、Windows XP 以降では Iphlpapi.dll からエクスポートされます。この関数を使用する際に Windows のバージョンチェックを行うことは推奨されません。Windows 2000、Windows XP、Windows Server 2003 およびそれ以降の Windows バージョンにわたってこの関数の移植性を必要とするアプリケーションは、Icmp.lib ファイルまたは Iphlpapi.lib ファイルのいずれにも静的にリンクすべきではありません。代わりに、アプリケーションは LoadLibraryGetProcAddress の呼び出しによって、Iphlpapi.dll 内に IcmpCloseHandle が存在するかどうかを確認すべきです。それが失敗した場合は、LoadLibraryGetProcAddress の呼び出しによって、Icmp.dll 内に IcmpCloseHandle が存在するかどうかを確認すべきです。

Iphlpapi.h ヘッダーファイルの include ディレクティブは、Icmpapi.h ヘッダーファイルより前に配置する必要があることに注意してください。

次の例では、ICMP エコー要求を発行できるハンドルを開いて閉じます。

#include <windows.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>

#pragma comment(lib, "iphlpapi.lib")

void main()
{
    HANDLE hIcmpFile;
    BOOL bRetVal; 

    hIcmpFile = IcmpCreateFile();
    if (hIcmpFile == INVALID_HANDLE_VALUE)
      printf("IcmpCreateFile failed with error: %ld\n", GetLastError() );
    else 
    {
      printf("\tHandle created.\n");

      bRetVal = IcmpCloseHandle(hIcmpFile);
      if (bRetVal)
          printf("\tHandle was closed\n");
      else
          printf("IcmpCloseHandle failed with error: %ld\n", GetLastError() );
    }
}

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

各言語での呼び出し定義

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

BOOL IcmpCloseHandle(
    HANDLE IcmpHandle
);
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("IPHLPAPI.dll", SetLastError = true, ExactSpelling = true)]
static extern bool IcmpCloseHandle(
    IntPtr IcmpHandle   // HANDLE
);
<DllImport("IPHLPAPI.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function IcmpCloseHandle(
    IcmpHandle As IntPtr   ' HANDLE
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
' IcmpHandle : HANDLE
Declare PtrSafe Function IcmpCloseHandle Lib "iphlpapi" ( _
    ByVal IcmpHandle As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

IcmpCloseHandle = ctypes.windll.iphlpapi.IcmpCloseHandle
IcmpCloseHandle.restype = wintypes.BOOL
IcmpCloseHandle.argtypes = [
    wintypes.HANDLE,  # IcmpHandle : HANDLE
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('IPHLPAPI.dll')
IcmpCloseHandle = Fiddle::Function.new(
  lib['IcmpCloseHandle'],
  [
    Fiddle::TYPE_VOIDP,  # IcmpHandle : HANDLE
  ],
  Fiddle::TYPE_INT)
#[link(name = "iphlpapi")]
extern "system" {
    fn IcmpCloseHandle(
        IcmpHandle: *mut core::ffi::c_void  // HANDLE
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("IPHLPAPI.dll", SetLastError = true)]
public static extern bool IcmpCloseHandle(IntPtr IcmpHandle);
"@
$api = Add-Type -MemberDefinition $sig -Name 'IPHLPAPI_IcmpCloseHandle' -Namespace Win32 -PassThru
# $api::IcmpCloseHandle(IcmpHandle)
#uselib "IPHLPAPI.dll"
#func global IcmpCloseHandle "IcmpCloseHandle" sptr
; IcmpCloseHandle IcmpHandle   ; 戻り値は stat
; IcmpHandle : HANDLE -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "IPHLPAPI.dll"
#cfunc global IcmpCloseHandle "IcmpCloseHandle" sptr
; res = IcmpCloseHandle(IcmpHandle)
; IcmpHandle : HANDLE -> "sptr"
; BOOL IcmpCloseHandle(HANDLE IcmpHandle)
#uselib "IPHLPAPI.dll"
#cfunc global IcmpCloseHandle "IcmpCloseHandle" intptr
; res = IcmpCloseHandle(IcmpHandle)
; IcmpHandle : HANDLE -> "intptr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	iphlpapi = windows.NewLazySystemDLL("IPHLPAPI.dll")
	procIcmpCloseHandle = iphlpapi.NewProc("IcmpCloseHandle")
)

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

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

typedef IcmpCloseHandleNative = Int32 Function(Pointer<Void>);
typedef IcmpCloseHandleDart = int Function(Pointer<Void>);
final IcmpCloseHandle = DynamicLibrary.open('IPHLPAPI.dll')
    .lookupFunction<IcmpCloseHandleNative, IcmpCloseHandleDart>('IcmpCloseHandle');
// IcmpHandle : HANDLE -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function IcmpCloseHandle(
  IcmpHandle: THandle   // HANDLE
): BOOL; stdcall;
  external 'IPHLPAPI.dll' name 'IcmpCloseHandle';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "IcmpCloseHandle"
  c_IcmpCloseHandle :: Ptr () -> IO CInt
-- IcmpHandle : HANDLE -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let icmpclosehandle =
  foreign "IcmpCloseHandle"
    ((ptr void) @-> returning int32_t)
(* IcmpHandle : HANDLE -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library iphlpapi (t "IPHLPAPI.dll"))
(cffi:use-foreign-library iphlpapi)

(cffi:defcfun ("IcmpCloseHandle" icmp-close-handle :convention :stdcall) :int32
  (icmp-handle :pointer))   ; HANDLE
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $IcmpCloseHandle = Win32::API::More->new('IPHLPAPI',
    'BOOL IcmpCloseHandle(HANDLE IcmpHandle)');
# my $ret = $IcmpCloseHandle->Call($IcmpHandle);
# IcmpHandle : HANDLE -> HANDLE
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

公式の関連項目