getaddrinfo
更新日2006年10月25日
参照 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winsock/winsock/getaddrinfo_2.asp

機能
そのgetaddrinfo関数はANSIホスト名からアドレスへのプトロコルより独立した変換を提供する

書式
int WSAAPI getaddrinfo(
  const char FAR* nodename,
  const char FAR* servname,
  const struct addrinfo FAR* hints,
  struct addrinfo FAR** res
);
引数
nodename [入]ホスト(ノード)名または数値のホストアドレス文字列を含む'\0'で終わるANSI文字列へのポインター。 そのインターネット・プロトコルのために、 数値のホストアドレス文字列は、ドット区切り数値IPv4アドレスまたはIPv6の16進法アドレスです。
servname [入]文字列として提示されるサービス名やポート番号を含む'\0'で終わるANSI文字列へのポインター。
hints [入]呼び出しルーチンがサポートするソケットのタイプに付いてのヒントを提供するaddrinfo構造体へのポインタ。 注釈を見て下さい。
res [出]ホストに付いてのレスポンス情報を含む一つ以上のaddrinfo構造体のリンクドリストへのポインタ。
戻り値
成功はゼロを戻します。 ウィンドウズ・ソケッツ・エラー・コードで見つかって、失敗はゼロ以外のウィンドウズ・ソケッツ・エラー・コードを戻します。
getaddrinfo関数により戻されるゼロ以外のエラーコードは、Internet Engineering Task Force (IETF)推薦によってアウトラインされているエラーコードのマップに位置づけられています。 以下のテーブルリストには、これらのエラーコードとそれらと等価のWSAコードがあります。 Winsockプログラマのためのよく知られる手続きと広範囲にわたるエラー情報として、 WSAエラーコードが使われる事を推薦されます。

エラーコード WSAによるコード 意味
EAI_AGAIN
WSATRY_AGAIN
名前レゾリューションのテンポラリ失敗が起こりました。
EAI_BADFLAGS
WSAEINVAL
hintsパラメタのai_flagsが不正です。
EAI_FAIL
WSANO_RECOVERY
名前レゾリューションのリカバリ不能な失敗が起こりました。
EAI_FAMILY
WSAEAFNOSUPPORT
そのhintsパラメタのそのai_familyメンバはサポートされていません。
EAI_MEMORY
WSA_NOT_ENOUGH_MEMORY
メモリアロケーション失敗が起こりました。
EAI_NONAME
WSAHOST_NOT_FOUND
その名前は提供されたパラメタまたはnodenameとservnameパラメタが提供されなかったために分解しません。
EAI_SERVICE
WSATYPE_NOT_FOUND
そのservnameパラメタはhintsパラメタの指定されたai_socktypeメンバのためにサポートされていません。
EAI_SOCKTYPE
WSAESOCKTNOSUPPORT
そのhintsパラメタのそのai_socktypeメンバはサポートされていません。

getaddrinfo関数によって戻されるEAIコードに基づくエラーメッセージを表示するために、gai_strerror関数を使用して下さい。 そのgai_strerror関数はIETF推薦に従う用に提供されています。 しかし、それはスレッドセーフではありません。 したがって、 WSAGetLastErrorのような従来のウィンドウズ・ソケッツ関数の仕様は推奨されます。

注釈

getaddrinfo関数はホスト名からアドレスへの変換を提供する、プロトコルより独立したANSIバージョンの関数です。 もし2つ以上の名前空間提供情報が戻されるならば、getaddrinfo関数は全てのレスポンスに集計します。

IPv6とIPv4プロトコルを共に使用する為に、 名前レゾリューションはDomain Name System(DNS)により出来ます、 ローカルhostsファイル、 または、他のネイミング・メカニズムによって。

getaddrinfo関数の為に使用可能なもう一つの名前はGetAddrInfoAです。 Ws2tcpip.hヘッダファイルのマクロにはGetAddrInfoAからgetaddrinfoへの定義がされています。

こちらの関数のそのUnicodeバージョンはGetAddrInfoWです。

Ws2tcpip.hヘッダファイルのマクロは、GetAddrInfoADDRINFOT構造体のミックスド・ケース関数名を定義しています。 このGetAddrInfo関数は、ADDRINFOT型のポインタのTCHAR型とそのhintsresパラメタのポインタのnodenameservnameパラメタと共に、呼ばれなければなりません。 UNICODEまたは_UNICODEが定義されていない時、 GetAddrInfogetaddrinfoとして定義されています、 関数のANSIバージョンです、 そして、ADDRINFOTはそのaddrinfo構造体として定義されています。 UNICODEまたは_UNICODEが定義されている時、 GetAddrInfoGetAddrInfoWとして定義されています、 関数のUnicodeバージョンです、 そして、ADDRINFOTaddrinfoW構造体として定義されています。

nodenameまたはservnameパラメタの一方または両方は、'\0'で終わるANSI文字列へのポイントでなければなりません; 通常、両方とも提供されます。

成功に、 addrinfo構造体のリンクドリストはresパラメタへと戻されます。 addrinfo構造体のリンクドリストに対する処理は、addrinfo構造体のai_nextメンバを使って、NULLポインタが現れるまでの間、繰り返し処理する事が出来ます。 ai_nextはポインタとして後続のデータを示す。 各々の戻されたaddrinfo構造体、ai_familyai_socktype、 そして、ai_protocolメンバにて、 ソケットまたはWSASocket関数より出しにおいて引数それぞれについて一致させて下さい。 また、 filled-inするソケット・アドレス構造体へのaddrinfo構造体ポイントを各々に戻された中のai_addrメンバ、 それの長さはそのai_addrlenメンバによって指定されます。

もしnodenameがコンピュータ名であるならば、コンピュータのための永続するアドレスは戻されます。 もしnodenameが文字列 "..localmachine" または "localhost"を含むならば、 全ての登録されているアドレスは戻されます。 もしnodenameがクラスタ・バーチャル・サーバ・ネームに当てはまるならば、仮想サーバ・アドレスだけが戻されます。 クラスタリングに付いての追加情報については、Windows Clusteringを調べて下さい。

getaddrinfo関数の呼び出し者は、hintsパラメタによって指されるaddrinfo構造体を通してサポートされるソケットのタイプについてのヒントを提供する事が出来ます。 hintsパラメタ使用時に、 その以下のルールはaddrinfo構造体関連に適用します:

  • 呼び出し者によって、ai_familyにAF_UNSPECが指定されると、プロトコルファミリィの(IPv4、IPv6)のいずれも受け入れる事を示します。 ノート AF_UNSPECとPF_UNSPECは同じです。
  • 呼び出し者によって、ai_socktypeにゼロが指定されると、いくつかのソケットタイプを受け入れる事を示します。
  • 呼び出し者によって、ai_protocolにゼロが指定されると、いくつかのプロトコルを受け入れる事を示します。
  • そのai_addrlenメンバにはゼロをセットしなければなりません。
  • そのai_canonnameメンバにはNULLをセットしなければなりません。
  • そのai_addrメンバにはNULLをセットしなければなりません。
  • そのai_nextメンバにはNULLをセットしなければなりません。

hintsパラメタにて提供されるaddrinfo構造体のその他の値は、要求仕様を示します。 たとえば、 呼び出し者がIPv4だけを取り扱ってIPv6を取り扱わないならば、 ai_familyメンバーにはAF_INETをセットしなければなりません。 For another example, たとえば、 呼び出し者がTCPだけを取り扱ってUDPを取り扱わないならば、 ai_socktypeメンバーにはSOCK_STREAMをセットしなければなりません。

もしhintsパラメタがNULLポインタであるならば、 hintsパラメタは初期値として、addrinfo構造体がゼロにセットされ、ai_familyメンバにAF_UNSPEC、その他のメンバはゼロとして、getaddrinfo関数に扱われます。

Windows Vista上にてgetaddrinfoがサービスから呼び出された後に、 もしそのオペレーションがユーザプロセスのサービス呼び出した結果であるならば、 サービスはユーザの役を演じなければなりません。 これは、セキュリティとルーティング区画を適切に実施する事を許します。


アドレス情報をダイナミックアロケーションより開放する事
getaddrinfo関数によって戻される全ての情報は、ダイナミックにアロケーションされます、 全てのaddrinfo構造体を含むこと、 ソケットアドレス構造体、 そして、正規のホスト名文字列は、addrinfo構造体で指されました。 関数呼び出しに成功し、割り当てられたメモリは、後にfreeaddrinfo呼び出しで開放する必要があります。

Example Code
以下のコード例は、getaddrinfo関数の使用方法を示します。
#include <ws2tcpip.h>

...

/*
 * 変数の宣言と初期化
 */
char *ip = "127.0.0.1";
char *port = "27015";
struct addrinfo aiHints;
struct addrinfo *aiList = NULL;
int retVal;

/*
 * hintsアドレス情報構造体をセットアップ
 * それはgetaddrinfo()関数を通過されます
 */
memset(&aiHints, 0, sizeof(aiHints));
aiHints.ai_family = AF_INET;
aiHints.ai_socktype = SOCK_STREAM;
aiHints.ai_protocol = IPPROTO_TCP;

/*
 * getaddrinfo()呼び出し。もし呼び出し成功ならば、
 * そのaiList変数はそのホストについての
 * レスポンス情報を含むaddrinfo構造体の
 * リンクドリストをホールドするでしょう
 */
if ((retVal = getaddrinfo(ip, port, &aiHints, &aiList)) != 0)
{
    printf("getaddrinfo() failed.\n");
}
ノート   開発環境がaddrinfogetaddrinfoの構造体と関数定義を含む最新バージョンのWs2tcpip.hをターゲットとしている事を確認して下さい、それぞれ。

hintsパラメタにおけるai_flagsの使用

hintsパラメタにて提供されるオプションであるaddrinfo構造体のai_flagsメンバーフラグは、以下の通りです:

  • AI_PASSIVE
  • AI_CANONNAME
  • AI_NUMERICHOST
  • AI_ADDRCONFIG
  • AI_NON_AUTHORITATIVE
  • AI_SECURE
  • AI_RETURN_PREFERRED_NAMES

AI_PASSIVEフラグをセットする事は、呼び出し者がbind関数呼び出しにおいて戻されたソケットアドレス構造体を使用する予定である事を意味します。 そのAI_PASSIVEフラグがセットされnodenameがNULLポインタである時、 ソケットアドレス構造体のIPアドレス部分には、IPv4アドレスのためにIN_ADDR_ANY、IPv6アドレスのためにIN6ADDR_ANY_INITがそれぞれセットされます。

そのAI_PASSIVEフラグがセットされていない時、 その戻されたソケットアドレス構造体は接続志向プロトコルのためのconnect関数呼び出しのための準備です、 または、connectsendto、または、コネクションレス・プロトコルのためのsend 関数、どちらにでも呼び出し準備が出来ている。 もしそのnodenameパラメタがNULLポインタである場合、 ソケットアドレス構造体のIPアドレス部分には、ループバックアドレスがセットされます。

もしAI_CANONNAMEもAI_NUMERICHOSTも使われないならば、 getaddrinfo関数は、分解を試みます。 もしリテラル文字列が渡されるならば、getaddrinfoは文字列の変換を試みます、 そして、ホスト名が渡されるならば、getaddrinfo関数はアドレスまたは複数のアドレスに名前の分解を試みます。

AI_CANONNAMEビットがセットされ、getaddrinfo関数が成功を戻す時、 そのresパラメタのそのai_canonnameメンバーは、その指定されたノードの正式名称を含む処のNULL終端される文字列を指します。

ノート   AI_CANONNAMEフラグがセットされる時、getaddrinfo関数は成功を戻す事が出来ます、 それでも、addrinfo構造体の関連するai_canonnameメンバーは、NULLです。 したがって、 AI_CANONNAMEフラグの推薦された使用は、addrinfo構造体の関連するai_canonnameメンバーがNULLであるかどうかについて調べる事を含みます。

AI_NUMERICHOSTビットがセットされる時、 nodenameパラメタは、NULLでない数値のホストアドレス文字列を含まなければなりません、 さもなければ、EAI_NONAMEエラーが戻されます。 このフラグは、名前解決サービスが呼ばれるのを防止します。

AI_ADDRCONFIG、AI_NON_AUTHORITATIVE、AI_SECURE、そして、AI_RETURN_PREFERRED_NAMESフラグはWindows Vista以降にてサポートされています。 AI_NON_AUTHORITATIVE、AI_SECURE、そして、AI_RETURN_PREFERRED_NAMESフラグはNS_EMAIL名前空間だけに適用されます。

もしAI_ADDRCONFIGビットがセットされているならば、 グローバルアドレスが構成される場合には、getaddrinfoは分解するでしょう。 もしAI_ADDRCONFIGフラグが指定されているならば、 IPv4アドレスがローカルシステム上に構成される場合だけ、IPv4アドレスは戻されます、 そして、IPv6アドレスがローカルシステム上に構成される場合だけ、IPv6アドレスは戻されます。 IPv4またはIPv6ループバックアドレスは、有効なグローバルアドレスと考えられません。

もしAI_NON_AUTHORITATIVEビットがセットされているならば、 NS_EMAIL名前空間プロバイダーは、信頼出来る結果と信頼出来ない結果を戻します。 もしAI_NON_AUTHORITATIVEビットがセットされていないならば、 そのNS_EMAIL名前空間プロバイダーは、信頼出来る結果だけを戻します。

もしAI_SECUREビットがセットされているならば、 NS_EMAIL名前空間プロバイダーは、ありうるなりすましを最小にするために強化されたセキュリティで得られた結果を戻します。

もしAI_RETURN_PREFERRED_NAMESがセットされているならば、 ノーネイムはpNameパラメタで提供されなければなりません。 NS_EMAIL名前空間プロバイダーは、パブリケイションのために好ましい名前を戻します。


Windowsの以前のバージョンでのgetaddrinfoのためのサポート

getaddrinfo関数は、Windows XP以降のWs2_32.dllに後から追加されました。 もしWindowsの以前のバージョン(Windows 2000, Windows NT, and Windows Me/98/95)の上にてこちらの関数を使用するアプリケーションの実行をあなたが望むならば、 あなたは、そのWs2tcpip.hファイルをインクルードし、またそのWspiapi.hファイルをインクルードする必要があります。 そのWspiapi.hインクルード・ファイルが加えられる時、 そのgetaddrinfo関数はWspiapi.hファイルの中にてWspiapiGetAddrInfo インライン関数として定義されています。 実行時に、 もしそのWs2_32.dllまたはWship6.dll(Windows 2000のためにIPv6 テクノロジィ・プレビュでgetaddrinfoを含んでいるファイル)がgetaddrinfoを含まないならば、そのような方向で、そのWspiapiGetAddrInfo関数は実装されます、 それから、getaddrinfoのバージョンは、そのWspiapi.hヘッダファイルコード上にてインラインベースとして実装されています。 そのgetaddrinfo関数をネイティビリィサポートされていない以前のWindowsプラットフォームの上では、こちらのインラインコードが使用されます。

Windows2000用IPv6テクノロジィ・プレビュがインストールされている時には、IPv6プロトコルがWindows2000上にてサポートされます。 さもなければ、Windows XPより以前のWindowsのバージョン上にて、getaddrinfoサポートはIPv4ネームレゾリューションのハンドリングに限定されます。

そのGetAddrInfoW関数はgetaddrinfoのそのUnicodeバージョンです。 そのGetAddrInfoW関数はWindows XP SP2のそのWs2_32.dllにと追加されました。 そのGetAddrInfoW関数はWindows XP SP2以前のWindowsバージョン上にて使用できません。


要求環境
Client Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95.
Server Requires Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header Declared in Ws2tcpip.h on Windows Server "Longhorn", Windows Vista, Windows Server 2003, and Windows XP.

Declared in Ws2tcpip.h on Windows 2000, Windows NT, and Windows Me/98/95; include Wspiapi.h.
Library Use libws2_32.a
DLL Requires Ws2_32.dll.

参照
addrinfo
addrinfoW
bind
connect
freeaddrinfo
gai_strerror
GetAddrInfoW
send
sendto
socket
Winsock Functions
Winsock Reference
WSAGetLastError
WSASocket