ホーム › Networking.WinSock › RtlIpv6AddressToStringExA

RtlIpv6AddressToStringExA

関数

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

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

シグネチャ

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

INT RtlIpv6AddressToStringExA(
    const IN6_ADDR* Address,
    DWORD ScopeId,
    WORD Port,
    LPSTR AddressString,
    DWORD* AddressStringLength
);

パラメーター

名前	型	方向	説明
Address	IN6_ADDR*	in	ネットワークバイト順の IPv6 アドレス。
ScopeId	DWORD	in	ネットワークバイト順の IPv6 アドレスのスコープ ID。このパラメーターは省略可能です。
Port	WORD	in	ネットワークバイト順形式のポート番号。このパラメーターは省略可能です。
AddressString	LPSTR	out	IP アドレス、スコープ ID、ポートの NULL 終端文字列表現を受け取るバッファーへのポインター。このバッファーは、少なくとも INET6_ADDRSTRLEN 文字を保持できる大きさが必要です。INET6_ADDRSTRLEN 値は Ws2ipdef.h ヘッダーファイルで定義されています。
AddressStringLength	DWORD*	inout	入力時には、AddressString パラメーターが指すバッファーに収まる文字数(NULL 終端文字を含む)を指定します。出力時には、このパラメーターには AddressString パラメーターが指すバッファーに実際に書き込まれた文字数が格納されます。

戻り値の型: INT

公式ドキュメント

IPv6 アドレス、スコープ ID、ポート番号を文字列に変換します。(ANSI)

戻り値

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

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

戻り値	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが関数に渡されました。このエラーは、AddressString または AddressStringLength パラメーターに NULL ポインターが渡された場合に返されます。また、AddressString パラメーターが指すバッファーの長さが、IPv6 アドレス、スコープ ID、ポートの文字列表現を受け取るのに十分でない場合にも返されます。
その他	FormatMessage を使用して、返されたエラーのメッセージ文字列を取得してください。

戻り値

説明

STATUS_INVALID_PARAMETER

無効なパラメーターが関数に渡されました。このエラーは、AddressString または AddressStringLength パラメーターに NULL ポインターが渡された場合に返されます。また、AddressString パラメーターが指すバッファーの長さが、IPv6 アドレス、スコープ ID、ポートの文字列表現を受け取るのに十分でない場合にも返されます。

その他

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

解説(Remarks)

RtlIpv6AddressToStringEx 関数は、IPv6 アドレス、スコープ ID、ポート番号を、インターネット形式の IPv6 アドレスの文字列表現に続けてスコープ ID の文字列表現、さらにポートの文字列表現を連結した文字列表現に変換するために使用されます。スコープ ID とポート番号は省略可能なパラメーターです。

返される IPv6 アドレスの基本的な文字列表現は、コロンで区切られた 8 個の 16 進数で構成されます。連続する 0 の 16 進数の並びは二重コロンに置き換えられます。IPv6 アドレスの文字列表現に二重コロンは 1 つしか使用できません。アドレスが IPv4 互換アドレス、IPv4 マップ IPv6 アドレス、または ISATAP アドレスである場合、最後の 32 ビットは IPv4 形式のドット区切りオクテット表記で表現されます。詳細については、IETF が発行する RFC 5942 のセクション 5 を参照してください。

スコープ ID が指定されている場合、スコープ ID の文字列表現はパーセント文字('%')によって IPv6 アドレスの文字列表現と区切られます。ポート番号が指定されている場合、IPv6 アドレスとスコープ ID の文字列表現は角括弧で囲まれます(先頭の '[' 文字に続いて IPv6 アドレス、'%' 文字、スコープ ID、末尾の ']' 文字)。ポート番号は、右角括弧の後にコロンを置き、それに続けて 10 進数によるポート番号の文字列表現として表現されます。

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

AddressString パラメーターが指すバッファーの長さが、IP アドレス、スコープ ID、ポートの文字列表現を受け取るのに十分でない場合、RtlIpv6AddressToStringEx は ERROR_INVALID_PARAMETER を返し、AddressStringLength パラメーターに必要なバッファー長を設定します。

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

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

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 RtlIpv6AddressToStringExA(
    const IN6_ADDR* Address,
    DWORD ScopeId,
    WORD Port,
    LPSTR AddressString,
    DWORD* AddressStringLength
);

[DllImport("ntdll.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int RtlIpv6AddressToStringExA(
    IntPtr Address,   // IN6_ADDR*
    uint ScopeId,   // DWORD
    ushort Port,   // WORD
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder AddressString,   // LPSTR out
    ref uint AddressStringLength   // DWORD* in/out
);

<DllImport("ntdll.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function RtlIpv6AddressToStringExA(
    Address As IntPtr,   ' IN6_ADDR*
    ScopeId As UInteger,   ' DWORD
    Port As UShort,   ' WORD
    <MarshalAs(UnmanagedType.LPStr)> AddressString As System.Text.StringBuilder,   ' LPSTR out
    ByRef AddressStringLength As UInteger   ' DWORD* in/out
) As Integer
End Function

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

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ntdll.dll')
RtlIpv6AddressToStringExA = Fiddle::Function.new(
  lib['RtlIpv6AddressToStringExA'],
  [
    Fiddle::TYPE_VOIDP,  # Address : IN6_ADDR*
    -Fiddle::TYPE_INT,  # ScopeId : DWORD
    -Fiddle::TYPE_SHORT,  # Port : WORD
    Fiddle::TYPE_VOIDP,  # AddressString : LPSTR out
    Fiddle::TYPE_VOIDP,  # AddressStringLength : DWORD* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ntdll")]
extern "system" {
    fn RtlIpv6AddressToStringExA(
        Address: *const IN6_ADDR,  // IN6_ADDR*
        ScopeId: u32,  // DWORD
        Port: u16,  // WORD
        AddressString: *mut u8,  // LPSTR out
        AddressStringLength: *mut u32  // DWORD* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ntdll.dll", CharSet = CharSet.Ansi)]
public static extern int RtlIpv6AddressToStringExA(IntPtr Address, uint ScopeId, ushort Port, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder AddressString, ref uint AddressStringLength);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ntdll_RtlIpv6AddressToStringExA' -Namespace Win32 -PassThru
# $api::RtlIpv6AddressToStringExA(Address, ScopeId, Port, AddressString, AddressStringLength)

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

出力引数:

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