RtlIpv6StringToAddressA 関数 (ip2string.h)

[アーティクル]
08/24/2023

RtlIpv6StringToAddress 関数は、IPv6 アドレスの文字列表現をバイナリ IPv6 アドレスに変換します。

構文

NTSYSAPI NTSTATUS RtlIpv6StringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] in6_addr *Addr
);

パラメーター

[in] S

IPv6 アドレスの NULL で終わる文字列表現を含むバッファーへのポインター。

[out] Terminator

変換された文字列を終了した文字へのポインターを受け取るパラメーター。これは、呼び出し元が文字列から詳細情報を抽出するために使用できます。

[out] Addr

IPv6 アドレスのバイナリ表現を格納するポインター。

戻り値

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

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

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

注釈

RtlIpv6StringToAddress 関数は、IPv6 アドレスの文字列形式を、ネットワーク順に返される IPv6 アドレス (左から右に並べ替えられたバイト) に変換するために使用されます。

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

S パラメーターが指す文字列は、IPv6 アドレス文字列の形式で表す必要があります。 IPv6 アドレスの基本的な文字列表現は、コロンで区切られた 8 つの 16 進数で構成されます。連続する 0 個の数値の文字列は、二重コロンに置き換えることができます。 IPv6 アドレスの文字列形式では、1 つの double-colon しか使用できません。アドレスが IPv4 互換アドレス、IPv4 マップ IPv6 アドレス、または ISATAP アドレスである場合、最後の 32 ビットは IPv4 スタイルのドットオクテット表記で表すことができます。詳細については、IETF によって公開された RFC 5942 のセクション 5 を参照してください。

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

メモ一部の形式が正しくない IPv6 アドレス (:::: など) は、有効な IPv6 アドレスで始まります。 RtlIpv6StringToAddress 関数は成功を返し、IPv6 アドレスの有効な部分を二重コロン (::)として解析します。その後、ターミネータは 3 番目のコロンを指します。渡された文字列全体が有効な IPv6 アドレスであることを検証するには、ターミネータが正しい文字を指していることを確認する必要があります。 S パラメーターに IPv6 アドレスのみが含まれている場合、終端記号は文字列の末尾にある NULL 文字を指す必要があります。

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

UNICODE と_UNICODEの両方が定義されていない場合、 RtlIpv6StringToAddress は、この関数の ANSI バージョンである RtlIpv6StringToAddressA に定義されます。 S パラメーターと Terminator パラメーターは、PCSTR データ型に対して定義されます。

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

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

注意

ip2string.h ヘッダーは、RtlIpv6StringToAddress をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件


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