ホーム › Networking.WinSock › RtlIpv6StringToAddressExA

RtlIpv6StringToAddressExA

関数

文字列をIPv6アドレスとスコープ・ポートへ変換する。

DLLntdll.dll文字セットANSI (-A)呼出規約winapi

シグネチャ

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

INT RtlIpv6StringToAddressExA(
    LPCSTR AddressString,
    IN6_ADDR* Address,
    DWORD* ScopeId,
    WORD* Port
);

パラメーター

名前	型	方向	説明
AddressString	LPCSTR	in	IPv6 アドレス、スコープ ID、ポート番号の NULL 終端文字列表現を格納したバッファーへのポインター。
Address	IN6_ADDR*	out	IPv6 アドレスのバイナリ表現を格納する場所へのポインター。
ScopeId	DWORD*	out	IPv6 アドレスのスコープ ID を格納する場所へのポインター。AddressString パラメーターにスコープ ID の文字列表現が含まれていない場合、このパラメーターにはゼロが返されます。
Port	WORD*	out	ポート番号を格納する場所へのポインター。ポート番号はネットワークバイトオーダー形式です。AddressString パラメーターにポート番号の文字列表現が含まれていない場合、このパラメーターにはゼロが返されます。

戻り値の型: INT

公式ドキュメント

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

戻り値

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

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

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

解説(Remarks)

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

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

AddressString パラメーターが指す文字列は、IPv6 アドレス文字列の形式の後に、省略可能なパーセント文字とスコープ ID 文字列を続けた形で表現する必要があります。IPv6 アドレスとスコープ ID 文字列は角かっこで囲む必要があります。IPv6 アドレスとスコープ ID 文字列の後の右角かっこの後には、省略可能なコロンとポート番号の文字列表現を続けることができます。IPv6 アドレスの基本的な文字列表現は、コロンで区切られた 8 個の 16 進数で構成されます。連続するゼロの並びは二重コロンに置き換えることができます。IPv6 アドレスの文字列表現中に二重コロンは 1 つしか存在できません。アドレスが IPv4 互換アドレス、IPv4 マップ IPv6 アドレス、または ISATAP アドレスである場合、下位 32 ビットは IPv4 形式のドット区切りオクテット表記で表現できます。詳細については、IETF が公開している RFC 5942 のセクション 5 を参照してください。

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

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

IN6_ADDR 構造体は In6addr.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 RtlIpv6StringToAddressExA(
    LPCSTR AddressString,
    IN6_ADDR* Address,
    DWORD* ScopeId,
    WORD* Port
);

[DllImport("ntdll.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int RtlIpv6StringToAddressExA(
    [MarshalAs(UnmanagedType.LPStr)] string AddressString,   // LPCSTR
    IntPtr Address,   // IN6_ADDR* out
    out uint ScopeId,   // DWORD* out
    out ushort Port   // WORD* out
);

<DllImport("ntdll.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function RtlIpv6StringToAddressExA(
    <MarshalAs(UnmanagedType.LPStr)> AddressString As String,   ' LPCSTR
    Address As IntPtr,   ' IN6_ADDR* out
    <Out> ByRef ScopeId As UInteger,   ' DWORD* out
    <Out> ByRef Port As UShort   ' WORD* out
) As Integer
End Function

' AddressString : LPCSTR
' Address : IN6_ADDR* out
' ScopeId : DWORD* out
' Port : WORD* out
Declare PtrSafe Function RtlIpv6StringToAddressExA Lib "ntdll" ( _
    ByVal AddressString As String, _
    ByVal Address As LongPtr, _
    ByRef ScopeId As Long, _
    ByRef Port As Integer) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RtlIpv6StringToAddressExA = ctypes.windll.ntdll.RtlIpv6StringToAddressExA
RtlIpv6StringToAddressExA.restype = ctypes.c_int
RtlIpv6StringToAddressExA.argtypes = [
    wintypes.LPCSTR,  # AddressString : LPCSTR
    ctypes.c_void_p,  # Address : IN6_ADDR* out
    ctypes.POINTER(wintypes.DWORD),  # ScopeId : DWORD* out
    ctypes.POINTER(ctypes.c_ushort),  # Port : WORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ntdll.dll')
RtlIpv6StringToAddressExA = Fiddle::Function.new(
  lib['RtlIpv6StringToAddressExA'],
  [
    Fiddle::TYPE_VOIDP,  # AddressString : LPCSTR
    Fiddle::TYPE_VOIDP,  # Address : IN6_ADDR* out
    Fiddle::TYPE_VOIDP,  # ScopeId : DWORD* out
    Fiddle::TYPE_VOIDP,  # Port : WORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ntdll")]
extern "system" {
    fn RtlIpv6StringToAddressExA(
        AddressString: *const u8,  // LPCSTR
        Address: *mut IN6_ADDR,  // IN6_ADDR* out
        ScopeId: *mut u32,  // DWORD* 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 RtlIpv6StringToAddressExA([MarshalAs(UnmanagedType.LPStr)] string AddressString, IntPtr Address, out uint ScopeId, out ushort Port);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ntdll_RtlIpv6StringToAddressExA' -Namespace Win32 -PassThru
# $api::RtlIpv6StringToAddressExA(AddressString, Address, ScopeId, Port)

#uselib "ntdll.dll"
#func global RtlIpv6StringToAddressExA "RtlIpv6StringToAddressExA" sptr, sptr, sptr, sptr
; RtlIpv6StringToAddressExA AddressString, varptr(Address), varptr(ScopeId), varptr(Port)   ; 戻り値は stat
; AddressString : LPCSTR -> "sptr"
; Address : IN6_ADDR* out -> "sptr"
; ScopeId : DWORD* out -> "sptr"
; Port : WORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ntdll.dll"
#cfunc global RtlIpv6StringToAddressExA "RtlIpv6StringToAddressExA" str, var, var, var
; res = RtlIpv6StringToAddressExA(AddressString, Address, ScopeId, Port)
; AddressString : LPCSTR -> "str"
; Address : IN6_ADDR* out -> "var"
; ScopeId : DWORD* out -> "var"
; Port : WORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ntdll.dll"
#cfunc global RtlIpv6StringToAddressExA "RtlIpv6StringToAddressExA" str, sptr, sptr, sptr
; res = RtlIpv6StringToAddressExA(AddressString, varptr(Address), varptr(ScopeId), varptr(Port))
; AddressString : LPCSTR -> "str"
; Address : IN6_ADDR* out -> "sptr"
; ScopeId : DWORD* out -> "sptr"
; Port : WORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。