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

RtlIpv4StringToAddressExA

関数
文字列をIPv4アドレスとポートへ変換する。
DLLntdll.dll文字セットANSI (-A)呼出規約winapi

シグネチャ

// ntdll.dll  (ANSI / -A)
#include <windows.h>

INT RtlIpv4StringToAddressExA(
    LPCSTR AddressString,
    BOOLEAN Strict,
    IN_ADDR* Address,
    WORD* Port
);

パラメーター

名前方向説明
AddressStringLPCSTRinIPv4 アドレスの NULL 終端文字列表現と、その後に続く省略可能なコロンおよびポート番号の文字列表現を格納したバッファーへのポインター。
StrictBOOLEANin文字列が厳密な 4 部構成のドット区切り 10 進表記で表された IPv4 アドレスでなければならないかどうかを示す値。このパラメーターが TRUE の場合、文字列は 4 つの部分から成るドット区切り 10 進表記でなければなりません。このパラメーターが FALSE の場合、IPv4 アドレスの文字列表現として 4 つの形式のいずれかを使用でき、10 進数、8 進数、または 16 進数の表記が許容されます。詳細については「解説」セクションを参照してください。
AddressIN_ADDR*outIPv4 アドレスのバイナリ表現が格納されるポインター。IPv4 アドレスはネットワークバイトオーダーで格納されます。
PortWORD*outポート番号のバイナリ表現が格納されるポインター。ポート番号はネットワークバイトオーダーで返されます。AddressString パラメーターが指す文字列にポートが指定されていない場合、Port パラメーターはゼロに設定されます。

戻り値の型: INT

公式ドキュメント

IPv4 アドレスとポート番号の文字列表現を、バイナリ形式の IPv4 アドレスとポートに変換します。(ANSI)

戻り値

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

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

戻り値 説明
STATUS_INVALID_PARAMETER

無効なパラメーターが関数に渡されました。このエラーは、Strict パラメーターが TRUE に設定されているにもかかわらず、AddressString パラメーターが指す文字列が IPv4 アドレスの 4 部構成のドット区切り 10 進表記文字列表現を含んでいなかった場合に返されます。また、AddressString パラメーターが指す文字列が IPv4 アドレスの適切な文字列表現を含んでいなかった場合にも返されます。

このエラーコードは Ntstatus.h ヘッダーファイルで定義されています。

解説(Remarks)

RtlIpv4StringToAddressEx 関数は、IPv4 アドレスとポート番号の文字列表現を、バイナリ形式の IPv4 アドレスとポート番号に変換するために使用します。IPv4 アドレスはネットワークオーダー(バイトが左から右へ順に並ぶ)で返されます。ポート番号もネットワークオーダーで返されます。

RtlIpv4StringToAddressEx は便宜的な関数であり、文字列から IP アドレスへの変換を実行するために Windows Sockets で提供される関数へアクセスする際に、Windows Sockets DLL を読み込んでおく必要がありません。

Strict パラメーターが TRUE に設定されている場合、AddressString パラメーターが指す文字列は厳密なドット区切り 10 進表記でなければなりません。この厳密な形式では、4 つの部分を指定する必要があります。各部分はデータの 10 進バイトとして解釈され、左から右へ IPv4 アドレスの 4 バイトに割り当てられます。

Strict パラメーターが FALSE に設定されている場合、AddressString パラメーターが指す文字列は、複数の可能な形式のいずれであってもかまいません。AddressString パラメーターが指すバッファーが 3 部構成のアドレス文字列を含む場合、最後の部分は 16 ビットの量として解釈され、ネットワークアドレスの右端の 2 バイトに配置されます。これにより、3 部構成のアドレス形式は、クラス B ネットワークアドレスを "128.net.host" として指定するのに便利になります。

AddressString パラメーターが指すバッファーが 2 部構成のアドレス文字列を含む場合、最後の部分は 24 ビットの量として解釈され、ネットワークアドレスの右端の 3 バイトに配置されます。これにより、2 部構成のアドレス形式は、クラス A ネットワークアドレスを "net.host" として指定するのに便利になります。AddressString パラメーターが指すバッファーが 1 部構成のアドレス文字列のみを含む場合、その値はバイトの並べ替えを行わずにネットワークアドレスに直接格納されます。

AddressString パラメーターが指すバッファーには、IPv4 アドレス文字列に続けて、省略可能なコロンとポート番号の文字列表現を含めることができます。AddressString パラメーターが指すバッファーにポート番号文字列が含まれている場合、ポート番号のバイナリ表現が Port パラメーターで返されます。AddressString パラメーターが指すバッファーにポート番号が含まれていない場合、Port パラメーターにはゼロが返されます。

UNICODE または _UNICODE のいずれかが定義されている場合、RtlIpv4StringToAddressEx はこの関数の Unicode 版である RtlIpv4StringToAddressExW として定義されます。AddressString パラメーターは PCWSTR データ型として定義されます。

UNICODE と _UNICODE のいずれも定義されていない場合、RtlIpv4StringToAddressEx はこの関数の ANSI 版である RtlIpv4StringToAddressExA として定義されます。AddressString パラメーターは PCSTR データ型として定義されます。

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

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

各言語での呼び出し定義

// ntdll.dll  (ANSI / -A)
#include <windows.h>

INT RtlIpv4StringToAddressExA(
    LPCSTR AddressString,
    BOOLEAN Strict,
    IN_ADDR* Address,
    WORD* Port
);
[DllImport("ntdll.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int RtlIpv4StringToAddressExA(
    [MarshalAs(UnmanagedType.LPStr)] string AddressString,   // LPCSTR
    [MarshalAs(UnmanagedType.U1)] bool Strict,   // BOOLEAN
    IntPtr Address,   // IN_ADDR* out
    out ushort Port   // WORD* out
);
<DllImport("ntdll.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function RtlIpv4StringToAddressExA(
    <MarshalAs(UnmanagedType.LPStr)> AddressString As String,   ' LPCSTR
    <MarshalAs(UnmanagedType.U1)> Strict As Boolean,   ' BOOLEAN
    Address As IntPtr,   ' IN_ADDR* out
    <Out> ByRef Port As UShort   ' WORD* out
) As Integer
End Function
' AddressString : LPCSTR
' Strict : BOOLEAN
' Address : IN_ADDR* out
' Port : WORD* out
Declare PtrSafe Function RtlIpv4StringToAddressExA Lib "ntdll" ( _
    ByVal AddressString As String, _
    ByVal Strict As Byte, _
    ByVal Address As LongPtr, _
    ByRef Port As Integer) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

RtlIpv4StringToAddressExA = ctypes.windll.ntdll.RtlIpv4StringToAddressExA
RtlIpv4StringToAddressExA.restype = ctypes.c_int
RtlIpv4StringToAddressExA.argtypes = [
    wintypes.LPCSTR,  # AddressString : LPCSTR
    wintypes.BOOLEAN,  # Strict : BOOLEAN
    ctypes.c_void_p,  # Address : IN_ADDR* out
    ctypes.POINTER(ctypes.c_ushort),  # Port : WORD* out
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ntdll.dll')
RtlIpv4StringToAddressExA = Fiddle::Function.new(
  lib['RtlIpv4StringToAddressExA'],
  [
    Fiddle::TYPE_VOIDP,  # AddressString : LPCSTR
    Fiddle::TYPE_CHAR,  # Strict : BOOLEAN
    Fiddle::TYPE_VOIDP,  # Address : IN_ADDR* out
    Fiddle::TYPE_VOIDP,  # Port : WORD* out
  ],
  Fiddle::TYPE_INT)
#[link(name = "ntdll")]
extern "system" {
    fn RtlIpv4StringToAddressExA(
        AddressString: *const u8,  // LPCSTR
        Strict: u8,  // BOOLEAN
        Address: *mut IN_ADDR,  // IN_ADDR* out
        Port: *mut u16  // WORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ntdll.dll", CharSet = CharSet.Ansi)]
public static extern int RtlIpv4StringToAddressExA([MarshalAs(UnmanagedType.LPStr)] string AddressString, [MarshalAs(UnmanagedType.U1)] bool Strict, IntPtr Address, out ushort Port);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ntdll_RtlIpv4StringToAddressExA' -Namespace Win32 -PassThru
# $api::RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
#uselib "ntdll.dll"
#func global RtlIpv4StringToAddressExA "RtlIpv4StringToAddressExA" sptr, sptr, sptr, sptr
; RtlIpv4StringToAddressExA AddressString, Strict, varptr(Address), varptr(Port)   ; 戻り値は stat
; AddressString : LPCSTR -> "sptr"
; Strict : BOOLEAN -> "sptr"
; Address : IN_ADDR* out -> "sptr"
; Port : WORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "ntdll.dll"
#cfunc global RtlIpv4StringToAddressExA "RtlIpv4StringToAddressExA" str, int, var, var
; res = RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
; AddressString : LPCSTR -> "str"
; Strict : BOOLEAN -> "int"
; Address : IN_ADDR* out -> "var"
; Port : WORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; INT RtlIpv4StringToAddressExA(LPCSTR AddressString, BOOLEAN Strict, IN_ADDR* Address, WORD* Port)
#uselib "ntdll.dll"
#cfunc global RtlIpv4StringToAddressExA "RtlIpv4StringToAddressExA" str, int, var, var
; res = RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
; AddressString : LPCSTR -> "str"
; Strict : BOOLEAN -> "int"
; Address : IN_ADDR* out -> "var"
; Port : WORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	ntdll = windows.NewLazySystemDLL("ntdll.dll")
	procRtlIpv4StringToAddressExA = ntdll.NewProc("RtlIpv4StringToAddressExA")
)

// AddressString (LPCSTR), Strict (BOOLEAN), Address (IN_ADDR* out), Port (WORD* out)
r1, _, err := procRtlIpv4StringToAddressExA.Call(
	uintptr(unsafe.Pointer(windows.BytePtrFromString(AddressString))),
	uintptr(Strict),
	uintptr(Address),
	uintptr(Port),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT
function RtlIpv4StringToAddressExA(
  AddressString: PAnsiChar;   // LPCSTR
  Strict: ByteBool;   // BOOLEAN
  Address: Pointer;   // IN_ADDR* out
  Port: Pointer   // WORD* out
): Integer; stdcall;
  external 'ntdll.dll' name 'RtlIpv4StringToAddressExA';
result := DllCall("ntdll\RtlIpv4StringToAddressExA"
    , "AStr", AddressString   ; LPCSTR
    , "Char", Strict   ; BOOLEAN
    , "Ptr", Address   ; IN_ADDR* out
    , "Ptr", Port   ; WORD* out
    , "Int")   ; return: INT
●RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port) = DLL("ntdll.dll", "int RtlIpv4StringToAddressExA(char*, byte, void*, void*)")
# 呼び出し: RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
# AddressString : LPCSTR -> "char*"
# Strict : BOOLEAN -> "byte"
# Address : IN_ADDR* out -> "void*"
# Port : WORD* out -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "ntdll" fn RtlIpv4StringToAddressExA(
    AddressString: [*c]const u8, // LPCSTR
    Strict: u8, // BOOLEAN
    Address: [*c]IN_ADDR, // IN_ADDR* out
    Port: [*c]u16 // WORD* out
) callconv(std.os.windows.WINAPI) i32;
proc RtlIpv4StringToAddressExA(
    AddressString: cstring,  # LPCSTR
    Strict: uint8,  # BOOLEAN
    Address: ptr IN_ADDR,  # IN_ADDR* out
    Port: ptr uint16  # WORD* out
): int32 {.importc: "RtlIpv4StringToAddressExA", stdcall, dynlib: "ntdll.dll".}
pragma(lib, "ntdll");
extern(Windows)
int RtlIpv4StringToAddressExA(
    const(char)* AddressString,   // LPCSTR
    ubyte Strict,   // BOOLEAN
    IN_ADDR* Address,   // IN_ADDR* out
    ushort* Port   // WORD* out
);
ccall((:RtlIpv4StringToAddressExA, "ntdll.dll"), stdcall, Int32,
      (Cstring, UInt8, Ptr{IN_ADDR}, Ptr{UInt16}),
      AddressString, Strict, Address, Port)
# AddressString : LPCSTR -> Cstring
# Strict : BOOLEAN -> UInt8
# Address : IN_ADDR* out -> Ptr{IN_ADDR}
# Port : WORD* out -> Ptr{UInt16}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t RtlIpv4StringToAddressExA(
    const char* AddressString,
    uint8_t Strict,
    void* Address,
    uint16_t* Port);
]]
local ntdll = ffi.load("ntdll")
-- ntdll.RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
-- AddressString : LPCSTR
-- Strict : BOOLEAN
-- Address : IN_ADDR* out
-- Port : WORD* out
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('ntdll.dll');
const RtlIpv4StringToAddressExA = lib.func('__stdcall', 'RtlIpv4StringToAddressExA', 'int32_t', ['str', 'uint8_t', 'void *', 'uint16_t *']);
// RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
// AddressString : LPCSTR -> 'str'
// Strict : BOOLEAN -> 'uint8_t'
// Address : IN_ADDR* out -> 'void *'
// Port : WORD* out -> 'uint16_t *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ntdll.dll", {
  RtlIpv4StringToAddressExA: { parameters: ["buffer", "u8", "pointer", "pointer"], result: "i32" },
});
// lib.symbols.RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port)
// AddressString : LPCSTR -> "buffer"
// Strict : BOOLEAN -> "u8"
// Address : IN_ADDR* out -> "pointer"
// Port : WORD* out -> "pointer"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t RtlIpv4StringToAddressExA(
    const char* AddressString,
    uint8_t Strict,
    void* Address,
    uint16_t* Port);
C, "ntdll.dll");
// $ffi->RtlIpv4StringToAddressExA(AddressString, Strict, Address, Port);
// AddressString : LPCSTR
// Strict : BOOLEAN
// Address : IN_ADDR* out
// Port : WORD* out
// 構造体/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 Ntdll extends StdCallLibrary {
    Ntdll INSTANCE = Native.load("ntdll", Ntdll.class, W32APIOptions.ASCII_OPTIONS);
    int RtlIpv4StringToAddressExA(
        String AddressString,   // LPCSTR
        byte Strict,   // BOOLEAN
        Pointer Address,   // IN_ADDR* out
        ShortByReference Port   // WORD* out
    );
}
@[Link("ntdll")]
lib Libntdll
  fun RtlIpv4StringToAddressExA = RtlIpv4StringToAddressExA(
    AddressString : UInt8*,   # LPCSTR
    Strict : UInt8,   # BOOLEAN
    Address : IN_ADDR*,   # IN_ADDR* out
    Port : UInt16*   # WORD* out
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef RtlIpv4StringToAddressExANative = Int32 Function(Pointer<Utf8>, Uint8, Pointer<Void>, Pointer<Uint16>);
typedef RtlIpv4StringToAddressExADart = int Function(Pointer<Utf8>, int, Pointer<Void>, Pointer<Uint16>);
final RtlIpv4StringToAddressExA = DynamicLibrary.open('ntdll.dll')
    .lookupFunction<RtlIpv4StringToAddressExANative, RtlIpv4StringToAddressExADart>('RtlIpv4StringToAddressExA');
// AddressString : LPCSTR -> Pointer<Utf8>
// Strict : BOOLEAN -> Uint8
// Address : IN_ADDR* out -> Pointer<Void>
// Port : WORD* out -> Pointer<Uint16>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function RtlIpv4StringToAddressExA(
  AddressString: PAnsiChar;   // LPCSTR
  Strict: ByteBool;   // BOOLEAN
  Address: Pointer;   // IN_ADDR* out
  Port: Pointer   // WORD* out
): Integer; stdcall;
  external 'ntdll.dll' name 'RtlIpv4StringToAddressExA';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "RtlIpv4StringToAddressExA"
  c_RtlIpv4StringToAddressExA :: CString -> Word8 -> Ptr () -> Ptr Word16 -> IO Int32
-- AddressString : LPCSTR -> CString
-- Strict : BOOLEAN -> Word8
-- Address : IN_ADDR* out -> Ptr ()
-- Port : WORD* out -> Ptr Word16
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let rtlipv4stringtoaddressexa =
  foreign "RtlIpv4StringToAddressExA"
    (string @-> uint8_t @-> (ptr void) @-> (ptr uint16_t) @-> returning int32_t)
(* AddressString : LPCSTR -> string *)
(* Strict : BOOLEAN -> uint8_t *)
(* Address : IN_ADDR* out -> (ptr void) *)
(* Port : WORD* out -> (ptr uint16_t) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library ntdll (t "ntdll.dll"))
(cffi:use-foreign-library ntdll)

(cffi:defcfun ("RtlIpv4StringToAddressExA" rtl-ipv4-string-to-address-ex-a :convention :stdcall) :int32
  (address-string :string)   ; LPCSTR
  (strict :uint8)   ; BOOLEAN
  (address :pointer)   ; IN_ADDR* out
  (port :pointer))   ; WORD* out
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $RtlIpv4StringToAddressExA = Win32::API::More->new('ntdll',
    'int RtlIpv4StringToAddressExA(LPCSTR AddressString, BYTE Strict, LPVOID Address, LPVOID Port)');
# my $ret = $RtlIpv4StringToAddressExA->Call($AddressString, $Strict, $Address, $Port);
# AddressString : LPCSTR -> LPCSTR
# Strict : BOOLEAN -> BYTE
# Address : IN_ADDR* out -> LPVOID
# Port : WORD* out -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

文字セット違い
類似 API
公式の関連項目
使用する型