Win32 API 日本語リファレンス
ホームNetworking.WinSock › InetNtopW

InetNtopW

関数
バイナリ形式のIPアドレスをUnicode文字列形式に変換する。
DLLWS2_32.dll呼出規約winapi対応OSWindows 8.1 以降

シグネチャ

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

LPWSTR InetNtopW(
    INT Family,
    const void* pAddr,
    LPWSTR pStringBuf,
    UINT_PTR StringBufSize
);

パラメーター

名前方向説明
FamilyINTin

アドレスファミリー。

アドレスファミリーに指定できる値は、Ws2def.h ヘッダーファイルで定義されています。Ws2def.h ヘッダーファイルは Winsock2.h に自動的にインクルードされるため、直接使用しないでください。AF_ アドレスファミリーと PF_ プロトコルファミリーの定数の値は同一である(例: AF_INETPF_INET)ため、どちらの定数を使用してもかまいません。

現在サポートされている値は AF_INET および AF_INET6 です。

意味
AF_INET
2
インターネットプロトコルバージョン 4 (IPv4) アドレスファミリー。このパラメーターを指定すると、この関数は IPv4 アドレス文字列を返します。
AF_INET6
23
インターネットプロトコルバージョン 6 (IPv6) アドレスファミリー。このパラメーターを指定すると、この関数は IPv6 アドレス文字列を返します。
pAddrvoid*in

文字列に変換する、ネットワークバイトオーダーの IP アドレスへのポインター。

Family パラメーターが AF_INET の場合、pAddr パラメーターは変換対象の IPv4 アドレスを格納した IN_ADDR 構造体を指している必要があります。

Family パラメーターが AF_INET6 の場合、pAddr パラメーターは変換対象の IPv6 アドレスを格納した IN6_ADDR 構造体を指している必要があります。

pStringBufLPWSTRout

IP アドレスの NULL 終端の文字列表現を格納するバッファーへのポインター。

IPv4 アドレスの場合、このバッファーは少なくとも 16 文字を保持できる大きさが必要です。

IPv6 アドレスの場合、このバッファーは少なくとも 46 文字を保持できる大きさが必要です。

StringBufSizeUINT_PTRin入力時には、pStringBuf パラメーターが指すバッファーの長さ(文字数)。

戻り値の型: LPWSTR

公式ドキュメント

InetNtop 関数は、IPv4 または IPv6 のインターネットネットワークアドレスを、インターネット標準形式の文字列に変換します。この関数の ANSI 版は inet_ntop です。(InetNtopW)

戻り値

エラーが発生しなかった場合、InetNtop 関数は標準形式の IP アドレスの文字列表現を格納したバッファーへのポインターを返します。

それ以外の場合は NULL が返され、拡張エラー情報を得るには WSAGetLastError を呼び出して固有のエラーコードを取得できます。

関数が失敗した場合、WSAGetLastError が返す拡張エラーコードは、次のいずれかの値になります。

エラーコード 意味
WSAEAFNOSUPPORT
Family パラメーターに指定されたアドレスファミリーがサポートされていません。このエラーは、Family パラメーターに指定された値が AF_INET または AF_INET6 でなかった場合に返されます。
ERROR_INVALID_PARAMETER
関数に無効なパラメーターが渡されました。このエラーは、pStringBuf パラメーターに NULL ポインターが渡された場合、または StringBufSize パラメーターがゼロの場合に返されます。また、pStringBuf パラメーターが指すバッファーの長さが、IP アドレスの文字列表現を受け取るのに十分でない場合にも返されます。

解説(Remarks)

InetNtop 関数は Windows Vista 以降でサポートされています。

InetNtop 関数は、プロトコルに依存しないアドレスから文字列への変換を提供します。InetNtop 関数は、pAddr パラメーターで指定されたインターネットアドレス構造体を受け取り、IP アドレスを表す NULL 終端文字列を返します。inet_ntoa 関数が IPv4 アドレスのみを扱うのに対し、InetNtop 関数は IPv4 アドレスと IPv6 アドレスのいずれも扱えます。

この関数の ANSI 版は、RFC 2553 で定義されている inet_ntop です。詳細については、IETF の Web サイトで入手できる RFC 2553 を参照してください。

InetNtop 関数は、IP アドレスから文字列への変換を行うために Windows Sockets DLL がロードされている必要はありません。

Family パラメーターに AF_INET が指定されている場合、pAddr パラメーターは変換対象の IPv4 アドレスを格納した IN_ADDR 構造体を指している必要があります。pStringBuf パラメーターが指すバッファーに返されるアドレス文字列は、ドット区切り 10 進表記(例として IPv4 アドレスのドット区切り 10 進表記である "192.168.16.0" など)になります。

Family パラメーターに AF_INET6 が指定されている場合、pAddr パラメーターは変換対象の IPv6 アドレスを格納した IN6_ADDR 構造体を指している必要があります。pStringBuf パラメーターが指すバッファーに返されるアドレス文字列は、インターネット標準形式になります。基本的な文字列表現は、コロンで区切られた 8 個の 16 進数で構成されます。連続するゼロの並びはダブルコロンに置き換えられます。IPv6 アドレスの文字列表現中にダブルコロンは 1 つしか使用できません。アドレスが IPv4 互換アドレスの場合、下位 32 ビットは IPv4 形式のドット区切りオクテット表記で表現されます。

pStringBuf パラメーターが指すバッファーの長さが、IP アドレスの文字列表現を受け取るのに十分でない場合、InetNtopERROR_INVALID_PARAMETER を返します。

UNICODE または _UNICODE が定義されている場合、InetNtop はこの関数の Unicode 版である InetNtopW として定義されます。pStringBuf パラメーターは PWSTR データ型として定義されます。

UNICODE または _UNICODE が定義されていない場合、InetNtop はこの関数の ANSI 版である InetNtopA として定義されます。この関数の ANSI 版は常に inet_ntop として定義されます。pStringBuf パラメーターは PSTR データ型として定義されます。

IN_ADDR 構造体は Inaddr.h ヘッダーファイルで定義されています。

IN6_ADDR 構造体は In6addr.h ヘッダーファイルで定義されています。

Windows Vista 以降では、RtlIpv4AddressToString 関数および RtlIpv4AddressToStringEx 関数を使用して、IN_ADDR 構造体として表現された IPv4 アドレスを、インターネット標準のドット区切り 10 進表記による IPv4 アドレスの文字列表現に変換できます。Windows Vista 以降では、RtlIpv6AddressToString 関数および RtlIpv6AddressToStringEx 関数を使用して、IN6_ADDR 構造体として表現された IPv6 アドレスを文字列表現に変換できます。RtlIpv6AddressToStringEx 関数は、IPv6 アドレス、スコープ ID、ポートを標準形式の IPv6 文字列に変換できるため、より柔軟です。

Windows 8.1 および Windows Server 2012 R2: InetNtopW 関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

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

各言語での呼び出し定義

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

LPWSTR InetNtopW(
    INT Family,
    const void* pAddr,
    LPWSTR pStringBuf,
    UINT_PTR StringBufSize
);
[DllImport("WS2_32.dll", ExactSpelling = true)]
static extern IntPtr InetNtopW(
    int Family,   // INT
    IntPtr pAddr,   // void*
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pStringBuf,   // LPWSTR out
    UIntPtr StringBufSize   // UINT_PTR
);
<DllImport("WS2_32.dll", ExactSpelling:=True)>
Public Shared Function InetNtopW(
    Family As Integer,   ' INT
    pAddr As IntPtr,   ' void*
    <MarshalAs(UnmanagedType.LPWStr)> pStringBuf As System.Text.StringBuilder,   ' LPWSTR out
    StringBufSize As UIntPtr   ' UINT_PTR
) As IntPtr
End Function
' Family : INT
' pAddr : void*
' pStringBuf : LPWSTR out
' StringBufSize : UINT_PTR
Declare PtrSafe Function InetNtopW Lib "ws2_32" ( _
    ByVal Family As Long, _
    ByVal pAddr As LongPtr, _
    ByVal pStringBuf As LongPtr, _
    ByVal StringBufSize As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

InetNtopW = ctypes.windll.ws2_32.InetNtopW
InetNtopW.restype = wintypes.LPWSTR
InetNtopW.argtypes = [
    ctypes.c_int,  # Family : INT
    ctypes.POINTER(None),  # pAddr : void*
    wintypes.LPWSTR,  # pStringBuf : LPWSTR out
    ctypes.c_size_t,  # StringBufSize : UINT_PTR
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
InetNtopW = Fiddle::Function.new(
  lib['InetNtopW'],
  [
    Fiddle::TYPE_INT,  # Family : INT
    Fiddle::TYPE_VOIDP,  # pAddr : void*
    Fiddle::TYPE_VOIDP,  # pStringBuf : LPWSTR out
    Fiddle::TYPE_UINTPTR_T,  # StringBufSize : UINT_PTR
  ],
  Fiddle::TYPE_VOIDP)
#[link(name = "ws2_32")]
extern "system" {
    fn InetNtopW(
        Family: i32,  // INT
        pAddr: *const (),  // void*
        pStringBuf: *mut u16,  // LPWSTR out
        StringBufSize: usize  // UINT_PTR
    ) -> *mut u16;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("WS2_32.dll")]
public static extern IntPtr InetNtopW(int Family, IntPtr pAddr, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pStringBuf, UIntPtr StringBufSize);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_InetNtopW' -Namespace Win32 -PassThru
# $api::InetNtopW(Family, pAddr, pStringBuf, StringBufSize)
#uselib "WS2_32.dll"
#func global InetNtopW "InetNtopW" sptr, sptr, sptr, sptr
; InetNtopW Family, pAddr, varptr(pStringBuf), StringBufSize   ; 戻り値は stat
; Family : INT -> "sptr"
; pAddr : void* -> "sptr"
; pStringBuf : LPWSTR out -> "sptr"
; StringBufSize : UINT_PTR -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "WS2_32.dll"
#cfunc global InetNtopW "InetNtopW" int, sptr, var, sptr
; res = InetNtopW(Family, pAddr, pStringBuf, StringBufSize)
; Family : INT -> "int"
; pAddr : void* -> "sptr"
; pStringBuf : LPWSTR out -> "var"
; StringBufSize : UINT_PTR -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; LPWSTR InetNtopW(INT Family, void* pAddr, LPWSTR pStringBuf, UINT_PTR StringBufSize)
#uselib "WS2_32.dll"
#cfunc global InetNtopW "InetNtopW" int, intptr, var, intptr
; res = InetNtopW(Family, pAddr, pStringBuf, StringBufSize)
; Family : INT -> "int"
; pAddr : void* -> "intptr"
; pStringBuf : LPWSTR out -> "var"
; StringBufSize : UINT_PTR -> "intptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	ws2_32 = windows.NewLazySystemDLL("WS2_32.dll")
	procInetNtopW = ws2_32.NewProc("InetNtopW")
)

// Family (INT), pAddr (void*), pStringBuf (LPWSTR out), StringBufSize (UINT_PTR)
r1, _, err := procInetNtopW.Call(
	uintptr(Family),
	uintptr(pAddr),
	uintptr(pStringBuf),
	uintptr(StringBufSize),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // LPWSTR
function InetNtopW(
  Family: Integer;   // INT
  pAddr: Pointer;   // void*
  pStringBuf: PWideChar;   // LPWSTR out
  StringBufSize: NativeUInt   // UINT_PTR
): PWideChar; stdcall;
  external 'WS2_32.dll' name 'InetNtopW';
result := DllCall("WS2_32\InetNtopW"
    , "Int", Family   ; INT
    , "Ptr", pAddr   ; void*
    , "Ptr", pStringBuf   ; LPWSTR out
    , "UPtr", StringBufSize   ; UINT_PTR
    , "Ptr")   ; return: LPWSTR
●InetNtopW(Family, pAddr, pStringBuf, StringBufSize) = DLL("WS2_32.dll", "char* InetNtopW(int, void*, char*, int)")
# 呼び出し: InetNtopW(Family, pAddr, pStringBuf, StringBufSize)
# Family : INT -> "int"
# pAddr : void* -> "void*"
# pStringBuf : LPWSTR out -> "char*"
# StringBufSize : UINT_PTR -> "int"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

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

typedef InetNtopWNative = Pointer<Utf16> Function(Int32, Pointer<Void>, Pointer<Utf16>, UintPtr);
typedef InetNtopWDart = Pointer<Utf16> Function(int, Pointer<Void>, Pointer<Utf16>, int);
final InetNtopW = DynamicLibrary.open('WS2_32.dll')
    .lookupFunction<InetNtopWNative, InetNtopWDart>('InetNtopW');
// Family : INT -> Int32
// pAddr : void* -> Pointer<Void>
// pStringBuf : LPWSTR out -> Pointer<Utf16>
// StringBufSize : UINT_PTR -> UintPtr
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function InetNtopW(
  Family: Integer;   // INT
  pAddr: Pointer;   // void*
  pStringBuf: PWideChar;   // LPWSTR out
  StringBufSize: NativeUInt   // UINT_PTR
): PWideChar; stdcall;
  external 'WS2_32.dll' name 'InetNtopW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "InetNtopW"
  c_InetNtopW :: Int32 -> Ptr () -> CWString -> CUIntPtr -> IO CWString
-- Family : INT -> Int32
-- pAddr : void* -> Ptr ()
-- pStringBuf : LPWSTR out -> CWString
-- StringBufSize : UINT_PTR -> CUIntPtr
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let inetntopw =
  foreign "InetNtopW"
    (int32_t @-> (ptr void) @-> (ptr uint16_t) @-> size_t @-> returning (ptr uint16_t))
(* Family : INT -> int32_t *)
(* pAddr : void* -> (ptr void) *)
(* pStringBuf : LPWSTR out -> (ptr uint16_t) *)
(* StringBufSize : UINT_PTR -> size_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library ws2_32 (t "WS2_32.dll"))
(cffi:use-foreign-library ws2_32)

(cffi:defcfun ("InetNtopW" inet-ntop-w :convention :stdcall) (:string :encoding :utf-16le)
  (family :int32)   ; INT
  (p-addr :pointer)   ; void*
  (p-string-buf :pointer)   ; LPWSTR out
  (string-buf-size :uint64))   ; UINT_PTR
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $InetNtopW = Win32::API::More->new('WS2_32',
    'LPWSTR InetNtopW(int Family, LPVOID pAddr, LPWSTR pStringBuf, WPARAM StringBufSize)');
# my $ret = $InetNtopW->Call($Family, $pAddr, $pStringBuf, $StringBufSize);
# Family : INT -> int
# pAddr : void* -> LPVOID
# pStringBuf : LPWSTR out -> LPWSTR
# StringBufSize : UINT_PTR -> WPARAM
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

公式の関連項目