ホーム › Networking.WinSock › RtlIpv4StringToAddressW

RtlIpv4StringToAddressW

関数

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

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

シグネチャ

// ntdll.dll  (Unicode / -W)
#include <windows.h>

INT RtlIpv4StringToAddressW(
    LPCWSTR S,
    BOOLEAN Strict,
    LPCWSTR* Terminator,
    IN_ADDR* Addr
);

パラメーター

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

戻り値の型: INT

公式ドキュメント

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

戻り値

関数が成功した場合、戻り値は 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 を定義します。エンコーディングニュートラルなエイリアスの使用を、エンコーディングニュートラルでないコードと混在させると、不整合が生じてコンパイルエラーまたは実行時エラーを引き起こす可能性があります。詳細については、関数プロトタイプの規約を参照してください。

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

各言語での呼び出し定義

// ntdll.dll  (Unicode / -W)
#include <windows.h>

INT RtlIpv4StringToAddressW(
    LPCWSTR S,
    BOOLEAN Strict,
    LPCWSTR* Terminator,
    IN_ADDR* Addr
);

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

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

' S : LPCWSTR
' Strict : BOOLEAN
' Terminator : LPCWSTR* out
' Addr : IN_ADDR* out
Declare PtrSafe Function RtlIpv4StringToAddressW Lib "ntdll" ( _
    ByVal S As LongPtr, _
    ByVal Strict As Byte, _
    ByVal Terminator As LongPtr, _
    ByVal Addr As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ntdll.dll')
RtlIpv4StringToAddressW = Fiddle::Function.new(
  lib['RtlIpv4StringToAddressW'],
  [
    Fiddle::TYPE_VOIDP,  # S : LPCWSTR
    Fiddle::TYPE_CHAR,  # Strict : BOOLEAN
    Fiddle::TYPE_VOIDP,  # Terminator : LPCWSTR* out
    Fiddle::TYPE_VOIDP,  # Addr : IN_ADDR* out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "ntdll")]
extern "system" {
    fn RtlIpv4StringToAddressW(
        S: *const u16,  // LPCWSTR
        Strict: u8,  // BOOLEAN
        Terminator: *const *const u16,  // LPCWSTR* 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.Unicode)]
public static extern int RtlIpv4StringToAddressW([MarshalAs(UnmanagedType.LPWStr)] string S, [MarshalAs(UnmanagedType.U1)] bool Strict, IntPtr Terminator, IntPtr Addr);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ntdll_RtlIpv4StringToAddressW' -Namespace Win32 -PassThru
# $api::RtlIpv4StringToAddressW(S, Strict, Terminator, Addr)

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

出力引数:

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