RtlIpv6AddressToStringExW 関数 (ip2string.h)

[アーティクル]
02/05/2024

RtlIpv6AddressToStringEx 関数は、IPv6 アドレス、スコープ ID、およびポート番号を文字列に変換します。

構文

NTSYSAPI NTSTATUS RtlIpv6AddressToStringExW(
  [in]      const in6_addr *Address,
  [in]      ULONG          ScopeId,
  [in]      USHORT         Port,
  [out]     PWSTR          AddressString,
  [in, out] PULONG         AddressStringLength
);

パラメーター

[in] Address

ネットワークバイト順の IPv6 アドレス。

[in] ScopeId

ネットワークバイト順の IPv6 アドレスのスコープ ID。このパラメーターは省略可能です。

[in] Port

ネットワークバイトオーダー形式のポート番号。このパラメーターは省略可能です。

[out] AddressString

IP アドレス、スコープ ID、ポートの NULL で終わる文字列表現を受け取るバッファーへのポインター。このバッファーは、少なくともINET6_ADDRSTRLEN文字を保持するのに十分な大きさにする必要があります。 INET6_ADDRSTRLEN値は、 Ws2ipdef.h ヘッダーファイルで定義されます。

[in, out] AddressStringLength

入力時に、 AddressString パラメーターが指すバッファーに収まる文字数 (NULL ターミネータを含む)。出力時に、このパラメーターには AddressString パラメーターによって指されるバッファーに実際に書き込まれた文字数が含まれます。

戻り値

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

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

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

リターンコード

説明

STATUS_INVALID_PARAMETER

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

その他

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

注釈

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 ソケットで提供される関数にアクセスするために Windows ソケット 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 ヘッダーファイルで定義されています。

RtlIpv6AddressToStringEx 関数を含むインポートライブラリは、Windows Vista 用にリリースされた Microsoft Windows ソフトウェア開発キット (SDK) には含まれていません。 RtlIpv6AddressToStringEx 関数は、Windows Driver Kit (WDK) に含まれる Ntdll.lib インポートライブラリに含まれています。アプリケーションでは、GetModuleHandle 関数と GetProcAddress 関数を使用して 、Ntdll.dll から関数ポインターを取得し、この関数を呼び出すこともできます。

要件


サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	ip2string.h (Mstcpip.h を含む)
Library	ntdll.lib
[DLL]	ntdll.dll