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

IcmpCreateFile

関数
ICMPエコー要求送信用のハンドルを作成する。
DLLIPHLPAPI.dll呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

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

HANDLE IcmpCreateFile(void);

パラメーターなし。戻り値: HANDLE

公式ドキュメント

IcmpCreateFile 関数は、IPv4 ICMP エコー要求を発行できるハンドルを開きます。

戻り値

IcmpCreateFile 関数は、成功した場合に開いたハンドルを返します。失敗した場合、この関数は INVALID_HANDLE_VALUE を返します。拡張エラー情報を取得するには GetLastError 関数を呼び出してください。

解説(Remarks)

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

IPv6 では、Icmp6CreateFileIcmp6SendEcho2、および Icmp6ParseReplies 関数を使用してください。

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

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

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

// Need to link with Iplhlapi.lib
#pragma comment(lib, "IPHLPAPI.lib")

void main()
{
    HANDLE hIcmpFile;

    hIcmpFile = IcmpCreateFile();
    if (hIcmpFile == INVALID_HANDLE_VALUE) {
      printf("\tUnable to open handle.\n");
      printf("IcmpCreatefile returned error: %ld\n", GetLastError() );
    }
    else {
      printf("\tHandle created.\n");
      // Need to close the handle when done using it
      IcmpCloseHandle(hIcmpFile);
    }  
}
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

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

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

IcmpCreateFile = ctypes.windll.iphlpapi.IcmpCreateFile
IcmpCreateFile.restype = ctypes.c_void_p
IcmpCreateFile.argtypes = []
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

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

var (
	iphlpapi = windows.NewLazySystemDLL("IPHLPAPI.dll")
	procIcmpCreateFile = iphlpapi.NewProc("IcmpCreateFile")
)

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

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

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

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

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

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

関連項目

公式の関連項目