GetAddrInfoExW

リクエストを処理すべきネームスペースプロバイダを特定するための追加パラメータを持つ、プロトコル非依存な名前解決を提供する。(Unicode)

GetAddrInfoExW pName, pServiceName, dwNameSpace, lpNspId, hints, ppResult, timeout, lpOverlapped, lpCompletionRoutine, lpHandle

pName : [wstr] ホスト (ノード) 名または数値形式のホストアドレス文字列を格納した NULL 終端文字列へのポインタ。インターネットプロトコルの場合、数値形式のホストアドレス文字列はドット区切り十進表記の IPv4 アドレスまたは 16 進表記の IPv6 アドレスである。
pServiceName : [wstr] サービス名、または文字列として表現されたポート番号のいずれかを格納した NULL 終端文字列へのオプションのポインタ。サービス名はポート番号の文字列エイリアスである。たとえば "http" は、HTTP プロトコルで Web サーバが既定で使用するポートとして IETF が定めたポート 80 のエイリアスである。ポート番号を指定しない場合の pServiceName パラメータとして使用可能な値は、次のファイルに列挙されている: %WINDIR%\system32\drivers\etc\services
dwNameSpace : [int] 問い合わせ対象のネームスペースプロバイダを決定するオプションの名前空間識別子。特定の名前空間識別子を渡すと、指定した名前空間をサポートするネームスペースプロバイダのみが問い合わせ対象となる。NS_ALL を指定するとインストール済みかつアクティブなすべてのネームスペースプロバイダが問い合わせ対象となる。
lpNspId : [var] NS_DNS のような単一の名前空間の下に複数のネームスペースプロバイダが登録されている場合に、問い合わせ対象の特定ネームスペースプロバイダを示すオプションの GUID へのポインタ。特定のネームスペースプロバイダの GUID を渡すと、指定したネームスペースプロバイダのみが問い合わせ対象となる。ネームスペースプロバイダの GUID を取得するには WSAEnumNameSpaceProviders 関数を呼び出せばよい。
hints : [var] 呼び出し元がサポートするソケットの種類についてのヒントを与える addrinfoex 構造体へのポインタ。pHints パラメータが指す addrinfoex 構造体の ai_addrlen、ai_canonname、ai_addr、ai_next メンバはゼロまたは NULL でなければならない。そうでない場合、GetAddrInfoEx 関数は WSANO_RECOVERY で失敗する。詳細は備考を参照。
ppResult : [var] ホストに関する応答情報を含む 1 つ以上の addrinfoex 構造体のリンクリストへのポインタ。
timeout : [var] ネームスペースプロバイダからの応答を待ってから呼び出しを中止するまでの時間 (ミリ秒) を示すオプションのパラメータ。このパラメータは、GetAddrInfoEx 関数を呼び出す前にソース内で UNICODE または _UNICODE マクロが定義されている場合のみサポートされる。そうでない場合、タイムアウトオプションがサポートされないため、このパラメータは予約されており NULL を設定しなければならない。
lpOverlapped : [var] 非同期操作に使われる overlapped 構造体へのオプションのポインタ。このパラメータは、GetAddrInfoEx 関数を呼び出す前にソース内で UNICODE または _UNICODE マクロが定義されている場合のみサポートされる。Windows 8 および Windows Server 2012 においては、lpCompletionRoutine パラメータが指定されていない場合、OVERLAPPED 構造体の hEvent メンバには非同期呼び出しの完了時に通知を受け取る手動リセットイベントを設定する必要がある。完了ルーチンを指定している場合は hEvent メンバを NULL にしなければならない。hEvent で指定したイベントがセットされたら、GetAddrInfoExOverlappedResult 関数を呼び出して操作結果を取得できる。Windows 8 および Windows Server 2012 において、UNICODE または _UNICODE マクロが定義されていない場合、このパラメータは現在予約されており NULL を設定しなければならない。Windows 7 および Windows Server 2008 R2 以前では非同期操作をサポートしないため、このパラメータは予約されており NULL を設定しなければならない。
lpCompletionRoutine : [int] 型: \_In_opt\_ [**LPWSAOVERLAPPED_COMPLETION_ROUTINE**](../winsock2/nc-winsock2-lpwsaoverlapped_completion_routine.md) 非同期操作の正常完了時に呼び出される関数へのオプションのポインタ。このパラメータは、GetAddrInfoEx 関数を呼び出す前にソース内で UNICODE または _UNICODE マクロが定義されている場合のみサポートされる。Windows 8 および Windows Server 2012 においては、このパラメータを指定する場合、以下のシグネチャを持つ関数へのポインタでなければならない。
lpHandle : [intptr] 未定。

(プラグイン / モジュール : ws2_32.dll)

解説

リクエストを処理すべきネームスペースプロバイダを特定するための追加パラメータを持つ、プロトコル非依存な名前解決を提供する。(Unicode)

[戻り値]
成功時、GetAddrInfoEx は NO_ERROR (0) を返す。失敗時は Windows Sockets エラーコード一覧にある
0 以外の Windows Sockets エラーコードを返す。GetAddrInfoEx 関数が返す 0
以外のエラーコードのほとんどは、IETF の勧告で概説されているエラーの集合にマップされる。次の表は、これらのエラーコードとそれに対応する
WSA エラーを示す。Winsock プログラマにとって馴染みがあり包括的なエラー情報を提供するため、WSA
エラーコードの使用を推奨する。
（以下省略）

[備考]
GetAddrInfoEx
関数は、ホスト名からアドレスへ、サービス名からポート番号へのプロトコル非依存な変換を提供する。GetAddrInfoEx 関数は
getaddrinfo 関数および GetAddrInfoW 関数の拡張版である。GetAddrInfoEx
関数では問い合わせを解決するネームスペースプロバイダを指定できる。GetAddrInfoEx
関数は、特定のネームスペースプロバイダが指定されていない限り、複数のネームスペースプロバイダからの結果を集約して返す。IPv6 および
IPv4 プロトコルでは、名前解決は DNS (Domain Name System)、ローカルの hosts ファイル、メールプロバイダ
(NS_EMAIL 名前空間)、その他の命名メカニズムによって行える。UNICODE または _UNICODE
が定義されている場合、GetAddrInfoEx は Unicode 版の GetAddrInfoExW
として定義される。文字列パラメータは PWSTR データ型として定義され、ADDRINFOEXW 構造体が使われる。Windows 8
および Windows Server 2012
では、timeout、lpOverlapped、lpCompletionRoutine、lpNameHandle パラメータを使って
GetAddrInfoEx 関数を非同期で完了させる呼び出しを行える。UNICODE または _UNICODE
が定義されていない場合、GetAddrInfoEx は ANSI 版の GetAddrInfoExA として定義される。文字列パラメータは
PCSTR データ型となり、ADDRINFOEXA
構造体が使われる。timeout、lpOverlapped、lpCompletionRoutine、lpNameHandle パラメータは
NULL に設定しなければならない。pName または pServiceName パラメータの少なくとも一方は NULL
終端文字列を指していなければならない。通常は両方を指定する。成功時には addrinfoex 構造体のリンクリストが ppResult
パラメータに返される。リストは返された各 addrinfoex 構造体の ai_next メンバが指すポインタをたどり、NULL
ポインタに出会うまで処理できる。返された各 addrinfoex 構造体の
ai_family、ai_socktype、ai_protocol メンバは、socket または WSASocket
関数呼び出しのそれぞれの引数に対応する。また、返された各 addrinfoex 構造体の ai_addr
メンバは、内容が埋められたソケットアドレス構造体を指し、その長さは ai_addrlen メンバで指定される。pName
パラメータがコンピュータ名を指している場合、送信元アドレスとして使用可能な当該コンピュータの永続アドレスがすべて返される。Windows
Vista 以降では、これらのアドレスには GetUnicastIpAddressTable または
GetUnicastIpAddressEntry 関数が返す、MIB_UNICASTIPADDRESS_ROW 構造体の
SkipAsSource メンバが false に設定されているユニキャスト IP アドレスすべてが含まれる。pName パラメータが
"localhost" と等しい文字列を指している場合、ローカルコンピュータ上のすべてのループバックアドレスが返される。pName
パラメータが空文字列を含む場合、ローカルコンピュータに登録済みのすべてのアドレスが返される。Windows Server 2003 以降で
pName パラメータが "..localmachine"
と等しい文字列を指している場合、ローカルコンピュータに登録済みのすべてのアドレスが返される。pName
パラメータがクラスタ仮想サーバ名を参照している場合、仮想サーバアドレスのみが返される。Windows Vista
以降では、これらのアドレスには GetUnicastIpAddressTable または GetUnicastIpAddressEntry
関数が返す、MIB_UNICASTIPADDRESS_ROW 構造体の SkipAsSource メンバが true
に設定されているユニキャスト IP アドレスすべてが含まれる。クラスタリングの詳細は Windows Clustering
を参照。Windows 7 SP1 および Windows Server 2008 R2 SP1 では、Netsh.exe での IP
アドレスの SkipAsSource 属性設定がサポートされ、MIB_UNICASTIPADDRESS_ROW 構造体の
SkipAsSource メンバが false の場合は当該 IP アドレスが DNS に登録され、true
の場合は登録されないように動作が変更されている。Windows 7 および Windows Server 2008 R2
にも同様の動作変更を行うホットフィックスが用意されている。詳しくは Knowledge Base (KB) 2386184
を参照。Windows Vista SP2 および Windows Server 2008 SP2
にも同様のホットフィックスが用意されている。
呼び出し元は、pHints パラメータが指す addrinfoex 構造体を通じて、サポートするソケットの種類に関するヒントを
GetAddrInfoEx 関数に渡せる。pHints パラメータを使う場合、それに関連付けられた addrinfoex
構造体には次の規則が適用される。
（以下省略）

情報