ホーム › Networking.WinSock › RtlIpv4StringToAddressA

RtlIpv4StringToAddressA

関数

文字列をIPv4アドレス構造体へ変換する。

DLLntdll.dll文字セットANSI (-A)呼出規約winapi対応OSWindows Vista 以降

シグネチャ

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

INT RtlIpv4StringToAddressA(
    LPCSTR S,
    BOOLEAN Strict,
    LPCSTR* Terminator,
    IN_ADDR* Addr
);

パラメーター

名前	型	方向	説明
S	LPCSTR	in	IPv4 アドレスの NULL 終端文字列表現を格納したバッファへのポインターです。
Strict	BOOLEAN	in	文字列を厳密な 4 部構成のドット区切り 10 進表記で表された IPv4 アドレスにする必要があるかどうかを示す値です。このパラメーターが TRUE の場合、文字列は 4 部構成のドット区切り 10 進表記でなければなりません。このパラメーターが FALSE の場合、10 進数、8 進数、または 16 進数表記による 4 通りの形式のいずれかを使用できます。詳細については、「解説」セクションを参照してください。
Terminator	LPCSTR*	out	変換された文字列を終了させた文字へのポインターを受け取るパラメーターです。これは、呼び出し元が文字列からさらに情報を抽出するために使用できます。
Addr	IN_ADDR*	out	IPv4 アドレスのバイナリ表現を格納するポインターです。

戻り値の型: INT

公式ドキュメント

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

戻り値

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

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

戻り値コード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが関数に渡されました。このエラーは、Strict パラメーターが TRUE に設定されているのに、S パラメーターが指す文字列が IPv4 アドレスの 4 部構成のドット区切り 10 進表記を含んでいない場合に返されます。また、S パラメーターが指す文字列が IPv4 アドレスの適切な文字列表現を含んでいない場合にも返されます。このエラーコードは Ntstatus.h ヘッダーファイルで定義されています。
その他	返されたエラーのメッセージ文字列を取得するには、 FormatMessage を使用してください。

戻り値コード

説明

STATUS_INVALID_PARAMETER

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

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

その他

返されたエラーのメッセージ文字列を取得するには、 FormatMessage を使用してください。

解説(Remarks)

RtlIpv4StringToAddress 関数は、IPv4 アドレスの文字列表現を、ネットワークオーダー(バイトが左から右に並ぶ順序)で返される IPv4 アドレスに変換するために使用されます。

RtlIpv4StringToAddress は、文字列から IP アドレスへの変換を実行するために Windows Sockets が提供する関数にアクセスする際に、Windows Sockets DLL の読み込みを必要としない便利な関数です。

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

Strict パラメーターが FALSE に設定されている場合、S パラメーターが指す文字列は、いくつかの形式のいずれであっても構いません。S パラメーターが指すバッファに 3 部構成のアドレス文字列が含まれている場合、最後の部分は 16 ビット値として解釈され、ネットワークアドレスの右端の 2 バイトに配置されます。これにより、3 部構成のアドレス形式は "128.net.host" のようにクラス B ネットワークアドレスを指定するのに便利です。S パラメーターが指すバッファに 2 部構成のアドレス文字列が含まれている場合、最後の部分は 24 ビット値として解釈され、ネットワークアドレスの右端の 3 バイトに配置されます。これにより、2 部構成のアドレス形式は "net.host" のようにクラス A ネットワークアドレスを指定するのに便利です。S パラメーターが指すバッファに 1 部構成のアドレス文字列のみが含まれている場合、その値はバイトの並べ替えなしでネットワークアドレスに直接格納されます。

成功した場合、Terminator パラメーターは、変換された文字列を終了させた文字を指します。これにより、アプリケーションは IP アドレスに加えて追加情報を含む文字列を RtlIpv4StringToAddress 関数に渡し、残りの情報を解析できます。

UNICODE または _UNICODE のいずれかが定義されている場合、RtlIpv4StringToAddress はこの関数の Unicode バージョンである RtlIpv4StringToAddressW として定義されます。S パラメーターは PCWSTR データ型として定義され、Terminator パラメーターは LPCWSTR データ型として定義されます。

UNICODE と _UNICODE のいずれも定義されていない場合、RtlIpv4StringToAddress はこの関数の ANSI バージョンである RtlIpv4StringToAddressA として定義されます。S および Terminator パラメーターは PCSTR データ型として定義されます。

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

メモ

ip2string.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI バージョンまたは Unicode バージョンを自動的に選択するエイリアスとして RtlIpv4StringToAddress を定義します。エンコーディング中立のエイリアスの使用を、エンコーディング中立ではないコードと混在させると、コンパイルエラーや実行時エラーを引き起こす不一致につながる可能性があります。詳細については、「Conventions for Function Prototypes」を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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 RtlIpv4StringToAddressA(
    LPCSTR S,
    BOOLEAN Strict,
    LPCSTR* Terminator,
    IN_ADDR* Addr
);

[DllImport("ntdll.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int RtlIpv4StringToAddressA(
    [MarshalAs(UnmanagedType.LPStr)] string S,   // LPCSTR
    [MarshalAs(UnmanagedType.U1)] bool Strict,   // BOOLEAN
    IntPtr Terminator,   // LPCSTR* out
    IntPtr Addr   // IN_ADDR* out
);

<DllImport("ntdll.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function RtlIpv4StringToAddressA(
    <MarshalAs(UnmanagedType.LPStr)> S As String,   ' LPCSTR
    <MarshalAs(UnmanagedType.U1)> Strict As Boolean,   ' BOOLEAN
    Terminator As IntPtr,   ' LPCSTR* out
    Addr As IntPtr   ' IN_ADDR* out
) As Integer
End Function

' S : LPCSTR
' Strict : BOOLEAN
' Terminator : LPCSTR* out
' Addr : IN_ADDR* out
Declare PtrSafe Function RtlIpv4StringToAddressA Lib "ntdll" ( _
    ByVal S As String, _
    ByVal Strict As Byte, _
    ByVal Terminator As LongPtr, _
    ByVal Addr As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RtlIpv4StringToAddressA = ctypes.windll.ntdll.RtlIpv4StringToAddressA
RtlIpv4StringToAddressA.restype = ctypes.c_int
RtlIpv4StringToAddressA.argtypes = [
    wintypes.LPCSTR,  # S : LPCSTR
    wintypes.BOOLEAN,  # Strict : BOOLEAN
    ctypes.c_void_p,  # Terminator : LPCSTR* out
    ctypes.c_void_p,  # Addr : IN_ADDR* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ntdll.dll')
RtlIpv4StringToAddressA = Fiddle::Function.new(
  lib['RtlIpv4StringToAddressA'],
  [
    Fiddle::TYPE_VOIDP,  # S : LPCSTR
    Fiddle::TYPE_CHAR,  # Strict : BOOLEAN
    Fiddle::TYPE_VOIDP,  # Terminator : LPCSTR* out
    Fiddle::TYPE_VOIDP,  # Addr : IN_ADDR* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ntdll")]
extern "system" {
    fn RtlIpv4StringToAddressA(
        S: *const u8,  // LPCSTR
        Strict: u8,  // BOOLEAN
        Terminator: *const *const u8,  // LPCSTR* out
        Addr: *mut IN_ADDR  // IN_ADDR* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ntdll.dll", CharSet = CharSet.Ansi)]
public static extern int RtlIpv4StringToAddressA([MarshalAs(UnmanagedType.LPStr)] string S, [MarshalAs(UnmanagedType.U1)] bool Strict, IntPtr Terminator, IntPtr Addr);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ntdll_RtlIpv4StringToAddressA' -Namespace Win32 -PassThru
# $api::RtlIpv4StringToAddressA(S, Strict, Terminator, Addr)

#uselib "ntdll.dll"
#func global RtlIpv4StringToAddressA "RtlIpv4StringToAddressA" sptr, sptr, sptr, sptr
; RtlIpv4StringToAddressA S, Strict, varptr(Terminator), varptr(Addr)   ; 戻り値は stat
; S : LPCSTR -> "sptr"
; Strict : BOOLEAN -> "sptr"
; Terminator : LPCSTR* out -> "sptr"
; Addr : IN_ADDR* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ntdll.dll"
#cfunc global RtlIpv4StringToAddressA "RtlIpv4StringToAddressA" str, int, var, var
; res = RtlIpv4StringToAddressA(S, Strict, Terminator, Addr)
; S : LPCSTR -> "str"
; Strict : BOOLEAN -> "int"
; Terminator : LPCSTR* out -> "var"
; Addr : IN_ADDR* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ntdll.dll"
#cfunc global RtlIpv4StringToAddressA "RtlIpv4StringToAddressA" str, int, sptr, sptr
; res = RtlIpv4StringToAddressA(S, Strict, varptr(Terminator), varptr(Addr))
; S : LPCSTR -> "str"
; Strict : BOOLEAN -> "int"
; Terminator : LPCSTR* out -> "sptr"
; Addr : IN_ADDR* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。