getaddrinfo 関数 (ws2tcpip.h)

[アーティクル]
03/15/2023

getaddrinfo 関数は、ANSI ホスト名からアドレスへのプロトコルに依存しない変換を提供します。

構文

INT WSAAPI getaddrinfo(
  [in, optional] PCSTR           pNodeName,
  [in, optional] PCSTR           pServiceName,
  [in, optional] const ADDRINFOA *pHints,
  [out]          PADDRINFOA      *ppResult
);

パラメーター

[in, optional] pNodeName

ホスト (ノード) 名または数値ホストアドレス文字列を含む NULL で終わる ANSI 文字列へのポインター。インターネットプロトコルの場合、数値ホストアドレス文字列はドット 10 進数の IPv4 アドレスまたは IPv6 16 進アドレスです。

[in, optional] pServiceName

文字列として表されるサービス名またはポート番号を含む NULL で終わる ANSI 文字列へのポインター。

サービス名は、ポート番号の文字列エイリアスです。たとえば、"http" は、インターネットエンジニアリングタスクフォース (IETF) によって HTTP プロトコルの Web サーバーで使用される既定のポートとして定義されているポート 80 のエイリアスです。ポート番号が指定されていない場合の pServiceName パラメーターに指定できる値を次のファイルに示します。

%WINDIR%\system32\drivers\etc\services

[in, optional] pHints

呼び出し元がサポートするソケットの種類に関するヒントを提供する addrinfo 構造体へのポインター。

pHints パラメーターが指すaddrinfo 構造体のai_addrlen、ai_canonname、ai_addr、およびai_nextメンバーは、0 または NULL である必要があります。それ以外の場合、 GetAddrInfoEx 関数は WSANO_RECOVERYで失敗します。

詳細については、「解説」を参照してください。

[out] ppResult

ホストに関する応答情報を含む 1 つ以上の addrinfo 構造体のリンクされたリストへのポインター。

戻り値

成功すると 0 が返されます。 Failure は、Windows ソケットエラーコードに示されているように、0 以外の Windows ソケットエラーコードを返します。

getaddrinfo 関数によって返される 0 以外のエラーコードのほとんどは、インターネットエンジニアリングタスクフォース (IETF) の推奨事項で説明されているエラーのセットにマップされます。次の表に、これらのエラーコードとその WSA と同等のエラーコードを示します。 WSA エラーコードは、Winsock プログラマにとって使い慣れた包括的なエラー情報を提供するため、使用することをお勧めします。

エラー値	WSA と同等	説明
EAI_AGAIN	WSATRY_AGAIN	名前解決で一時的なエラーが発生しました。
EAI_BADFLAGS	WSAEINVAL	pHints パラメーターのai_flags メンバーに無効な値が指定されました。
EAI_FAIL	WSANO_RECOVERY	名前解決で回復できないエラーが発生しました。
EAI_FAMILY	WSAEAFNOSUPPORT	pHints パラメーターのai_family メンバーはサポートされていません。
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	メモリ割り当てエラーが発生しました。
EAI_NONAME	WSAHOST_NOT_FOUND	指定されたパラメーターの名前が解決されないか、 pNodeName パラメーターと pServiceName パラメーターが指定されませんでした。
EAI_SERVICE	WSATYPE_NOT_FOUND	pServiceName パラメーターは、pHints パラメーターの指定したai_socktype メンバーではサポートされていません。
EAI_SOCKTYPE	WSAESOCKTNOSUPPORT	pHints パラメーターのai_socktype メンバーはサポートされていません。

getaddrinfo 関数によって返される EAI コードに基づいてエラーメッセージを出力するには、gai_strerror関数を使用します。 gai_strerror関数は IETF の推奨事項に準拠するために提供されますが、スレッドセーフではありません。そのため、 WSAGetLastError などの従来の Windows ソケット関数を使用することをお勧めします。

エラーコード	意味
WSA_NOT_ENOUGH_MEMORY	操作を実行するためのメモリが不足していました。
WSAEAFNOSUPPORT	要求されたプロトコルと互換性のないアドレスが使用されました。このエラーは、pHints パラメーターが指す addrinfo 構造体のai_family メンバーがサポートされていない場合に返されます。
WSAEINVAL	無効な引数が指定されました。このエラーは、pHints パラメーターが指す addrinfo 構造体のai_flags メンバーに無効な値が指定された場合に返されます。
WSAESOCKTNOSUPPORT	このアドレスファミリでは、指定したソケットタイプはサポートされていません。このエラーは、pHints パラメーターが指す addrinfo 構造体のai_socktype メンバーがサポートされていない場合に返されます。
WSAHOST_NOT_FOUND	そのようなホストは不明です。このエラーは、指定されたパラメーターの名前が解決されない場合、または pNodeName パラメーターと pServiceName パラメーターが指定されていない場合に返されます。
WSANO_DATA	要求された名前は有効ですが、要求された種類のデータが見つかりませんでした。
WSANO_RECOVERY	データベースの参照中に、修復できないエラーが発生しました。このエラーは、名前解決で回復不可能なエラーが発生した場合に返されます。
WSANOTINITIALIZED	この関数を使用する前に、WSAStartup 呼び出しが正常に行われる必要があります。
WSATRY_AGAIN	これは、通常、ホスト名の解決中に発生する一時エラーであり、ローカルサーバーが、権限のあるサーバーから応答を受信しなかったことを示します。このエラーは、名前解決で一時的なエラーが発生したときに返されます。
WSATYPE_NOT_FOUND	指定したクラスが見つかりませんでした。 pServiceName パラメーターは、pHints パラメーターが指す addrinfo 構造体の指定されたai_socktype メンバーではサポートされていません。

注釈

getaddrinfo 関数は、ホスト名からアドレスへのプロトコルに依存しない変換を提供する関数の ANSI バージョンです。この関数の Unicode バージョンは GetAddrInfoW です。開発者は、getaddrinfo ANSI 関数ではなく GetAddrInfoW Unicode 関数を使用することをお勧めします。

getaddrinfo 関数は、NS_DNS名前空間の結果を返します。 getaddrinfo 関数は、複数の名前空間プロバイダーが情報を返す場合に、すべての応答を集計します。 IPv6 および IPv4 プロトコルで使用する場合、名前解決はドメインネームシステム (DNS)、ローカル ホスト ファイル、または NS_DNS 名前空間のその他の名前付けメカニズムによって行うことができます。

getaddrinfo 関数に使用できるもう 1 つの名前は、GetAddrInfoA です。 Ws2tcpip.h ヘッダーファイル内のマクロでは、GetAddrInfoA を getaddrinfo に定義します。

Ws2tcpip.h ヘッダーファイル内のマクロでは、GetAddrInfo の大文字と小文字が混在する関数名と ADDRINFOT 構造体を定義します。この GetAddrInfo 関数は、TCHAR 型のポインターの pNodeName パラメーターと pServiceName パラメーター、および ADDRINFOT 型のポインターの pHints パラメーターと ppResult パラメーターを使用して呼び出す必要があります。 UNICODE または_UNICODEが定義されていない場合、 GetAddrInfo は getaddrinfo に定義され、関数の ANSI バージョン、 ADDRINFOT は addrinfo 構造体に定義されます。 UNICODE または_UNICODEが定義されている場合、GetAddrInfo は GetAddrInfoW に定義され、関数の Unicode バージョンは、ADDRINFOT は addrinfoW 構造体に定義されます。

Windows Server 2003 および Windows XP 用プラットフォームソフトウェア開発キット (SDK) の Ws2tcpip.h ヘッダーファイルで定義されている getaddrinfo 関数のパラメーター名とパラメーター型は異なっていました。

pNodeName パラメーターまたは pServiceName パラメーターの一方または両方が、NULL で終わる ANSI 文字列を指している必要があります。一般に、両方が提供されます。

成功すると、リンクされた addrinfo 構造体のリストが ppResult パラメーターで返されます。リストは、NULL ポインターが検出されるまで、返された各 addrinfo 構造体のai_next メンバーに指定されたポインターに従って処理できます。返される各 addrinfo 構造体では、 ai_family、 ai_socktype、 および ai_protocol メンバーは 、ソケットまたは WSASocket 関数呼び出しのそれぞれの引数に対応します。また、返される各 addrinfo 構造体のai_addr メンバーは、入力されたソケットアドレス構造体を指し、その長さは ai_addrlen メンバーで指定されます。

pNodeName パラメーターがコンピューター名を指している場合は、ソースアドレスとして使用できるコンピューターのすべての永続的なアドレスが返されます。 Windows Vista 以降では、これらのアドレスには、MIB_UNICASTIPADDRESS_ROW構造体でSkipAsSource メンバーが false に設定されている GetUnicastIpAddressTable 関数または GetUnicastIpAddressEntry 関数によって返されるすべてのユニキャスト IP アドレスが含まれます。

pNodeName パラメーターが "localhost" と等しい文字列を指している場合は、ローカルコンピューター上のすべてのループバックアドレスが返されます。

pNodeName パラメーターに空の文字列が含まれている場合は、ローカルコンピューター上のすべての登録済みアドレスが返されます。

Windows Server 2003 以降では、 pNodeName パラメーターがに等しい文字列を指している場合。localmachine", all registered addresses on the local computer are returned.

pNodeName パラメーターがクラスター仮想サーバー名を参照している場合は、仮想サーバーアドレスのみが返されます。 Windows Vista 以降では、これらのアドレスには、MIB_UNICASTIPADDRESS_ROW構造体でSkipAsSource メンバーが true に設定されている GetUnicastIpAddressTable 関数または GetUnicastIpAddressEntry 関数によって返されるすべてのユニキャスト IP アドレスが含まれます。クラスタリングの詳細については、「 Windows クラスタリング」を参照してください。

Windows 7 Service Pack 1 (SP1) と Windows Server 2008 R2 Service Pack 1 (SP1) では、IP アドレスに SkipAsSource 属性を設定するためのサポートが Netsh.exe に追加されます。これにより、MIB_UNICASTIPADDRESS_ROW構造体の SkipAsSource メンバーが false に設定されている場合、IP アドレスが DNS に登録されるように動作も変更されます。 SkipAsSource メンバーが true に設定されている場合、IP アドレスは DNS に登録されません。

Windows 7 および Windows Server 2008 R2 では、IP アドレスに SkipAsSource 属性を設定するためのサポートを Netsh.exe に追加する修正プログラムを使用できます。この修正プログラムは、MIB_UNICASTIPADDRESS_ROW構造体の SkipAsSource メンバーが false に設定されている場合、IP アドレスが DNS に登録されるように動作も変更します。 SkipAsSource メンバーが true に設定されている場合、IP アドレスは DNS に登録されません。詳細については、「ナレッジベース (KB) 2386184」を参照してください。

同様の修正プログラムは、Service Pack 2 (SP2) と Windows Server 2008 Service Pack 2 (SP2) を使用する Windows Vista でも使用できます。この修正プログラムは、IP アドレスに SkipAsSource 属性を設定するためのサポートを Netsh.exe に追加します。この修正プログラムは、MIB_UNICASTIPADDRESS_ROW構造体の SkipAsSource メンバーが false に設定されている場合、IP アドレスが DNS に登録されるように動作も変更します。 SkipAsSource メンバーが true に設定されている場合、IP アドレスは DNS に登録されません。

getaddrinfo 関数の呼び出し元は、pHints パラメーターが指す addrinfo 構造体を介してサポートされるソケットの種類に関するヒントを提供できます。 pHints パラメーターを使用すると、関連付けられている addrinfo 構造体に次の規則が適用されます。

ai_family の値AF_UNSPECは、呼び出し元がAF_INETとAF_INET6アドレスファミリのみを受け入れることを示します。 AF_UNSPECとPF_UNSPECは同じであることに注意してください。
ai_socktype の値 0 は、呼び出し元が任意のソケット型を受け入れることを示します。
ai_protocolの値 0 は、呼び出し元が任意のプロトコルを受け入れることを示します。
ai_addrlen メンバーは 0 に設定する必要があります。
ai_canonname メンバーは NULL に設定する必要があります。
ai_addr メンバーは NULL に設定する必要があります。
ai_next メンバーは NULL に設定する必要があります。

ai_familyの AF_UNSPEC の値は、呼び出し元がプロトコルファミリを受け入れることを示します。この値を使用して、 pNodeName パラメーターが指すホスト名の IPv4 アドレスと IPv6 アドレスの両方を返すことができます。 Windows Server 2003 および Windows XP では、IPv6 アドレスは、IPv6 がローカルコンピューターにインストールされている場合にのみ返されます。

pHints パラメーターで提供される addrinfo 構造体のその他の値は、特定の要件を示します。たとえば、呼び出し元が IPv4 のみを処理し、IPv6 を処理しない場合は、 ai_family メンバーを AF_INET に設定する必要があります。別の例として、呼び出し元が TCP のみを処理し、UDP を処理しない場合は、 ai_socktype メンバーを SOCK_STREAM に設定する必要があります。

pHints パラメーターが NULL ポインターの場合、getaddrinfo 関数は、pHints の addrinfo 構造体が、ai_family メンバーが AF_UNSPEC に設定され、他のすべてのメンバーが 0 に設定された状態で初期化されたかのように扱います。

Windows Vista 以降では、 getaddrinfo がサービスから呼び出されたときに、操作がサービスを呼び出すユーザープロセスの結果である場合、サービスはユーザーを偽装する必要があります。これは、セキュリティを適切に適用できるようにするためです。

getaddrinfo 関数を使用すると、IP アドレスのテキスト文字列表現を、IP アドレスとその他の情報の sockaddr 構造体を含む addrinfo 構造体に変換できます。この方法で使用するには、pNodeName パラメーターが指す文字列に IP アドレスのテキスト表現が含まれている必要があります。また、pHints パラメーターが指す addrinfo 構造体には、ai_flags メンバーに AI_NUMERICHOST フラグが設定されている必要があります。 pNodeName パラメーターが指す文字列には、IPv4 アドレスまたは IPv6 アドレスのテキスト表現を含める場合があります。テキスト IP アドレスは、ppResult パラメーターによって指される addrinfo 構造体に変換されます。返される addrinfo 構造体には、IP アドレスの sockaddr 構造体と、IP アドレスに関する追加情報が含まれています。このメソッドが Windows Server 2003 および Windows XP で IPv6 アドレス文字列を操作するには、IPv6 プロトコルをローカルコンピューターにインストールする必要があります。それ以外の場合は、 WSAHOST_NOT_FOUND エラーが返されます。

動的割り当てからのアドレス情報の解放

ppResult パラメーターが指す getaddrinfo 関数によって返されるすべての情報は、addrinfo 構造体、ソケットアドレス構造体、addrinfo構造体が指す正規ホスト名文字列など、動的に割り当てられます。この関数の正常な呼び出しによって割り当てられたメモリは、 freeaddrinfo の後続の呼び出しで解放する必要があります。

コード例

次のコード例は 、getaddrinfo 関数の使用方法を示しています。

#undef UNICODE

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// link with Ws2_32.lib
#pragma comment (lib, "Ws2_32.lib")

int __cdecl main(int argc, char **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;
    INT iRetval;

    DWORD dwRetval;

    int i = 1;
    
    struct addrinfo *result = NULL;
    struct addrinfo *ptr = NULL;
    struct addrinfo hints;

    struct sockaddr_in  *sockaddr_ipv4;
//    struct sockaddr_in6 *sockaddr_ipv6;
    LPSOCKADDR sockaddr_ip;

    char ipstringbuffer[46];
    DWORD ipbufferlength = 46;

    // Validate the parameters
    if (argc != 3) {
        printf("usage: %s <hostname> <servicename>\n", argv[0]);
        printf("getaddrinfo provides protocol-independent translation\n");
        printf("   from an ANSI host name to an IP address\n");
        printf("%s example usage\n", argv[0]);
        printf("   %s www.contoso.com 0\n", argv[0]);
        return 1;
    }

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("WSAStartup failed: %d\n", iResult);
        return 1;
    }

    //--------------------------------
    // Setup the hints address info structure
    // which is passed to the getaddrinfo() function
    ZeroMemory( &hints, sizeof(hints) );
    hints.ai_family = AF_UNSPEC;
    hints.ai_socktype = SOCK_STREAM;
    hints.ai_protocol = IPPROTO_TCP;

    printf("Calling getaddrinfo with following parameters:\n");
    printf("\tnodename = %s\n", argv[1]);
    printf("\tservname (or port) = %s\n\n", argv[2]);
    
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval = getaddrinfo(argv[1], argv[2], &hints, &result);
    if ( dwRetval != 0 ) {
        printf("getaddrinfo failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    printf("getaddrinfo returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        printf("getaddrinfo response %d\n", i++);
        printf("\tFlags: 0x%x\n", ptr->ai_flags);
        printf("\tFamily: ");
        switch (ptr->ai_family) {
            case AF_UNSPEC:
                printf("Unspecified\n");
                break;
            case AF_INET:
                printf("AF_INET (IPv4)\n");
                sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
                printf("\tIPv4 address %s\n",
                    inet_ntoa(sockaddr_ipv4->sin_addr) );
                break;
            case AF_INET6:
                printf("AF_INET6 (IPv6)\n");
                // the InetNtop function is available on Windows Vista and later
                // sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
                // printf("\tIPv6 address %s\n",
                //    InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
                
                // We use WSAAddressToString since it is supported on Windows XP and later
                sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
                // The buffer length is changed by each call to WSAAddresstoString
                // So we need to set it for each iteration through the loop for safety
                ipbufferlength = 46;
                iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL, 
                    ipstringbuffer, &ipbufferlength );
                if (iRetval)
                    printf("WSAAddressToString failed with %u\n", WSAGetLastError() );
                else    
                    printf("\tIPv6 address %s\n", ipstringbuffer);
                break;
            case AF_NETBIOS:
                printf("AF_NETBIOS (NetBIOS)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_family);
                break;
        }
        printf("\tSocket type: ");
        switch (ptr->ai_socktype) {
            case 0:
                printf("Unspecified\n");
                break;
            case SOCK_STREAM:
                printf("SOCK_STREAM (stream)\n");
                break;
            case SOCK_DGRAM:
                printf("SOCK_DGRAM (datagram) \n");
                break;
            case SOCK_RAW:
                printf("SOCK_RAW (raw) \n");
                break;
            case SOCK_RDM:
                printf("SOCK_RDM (reliable message datagram)\n");
                break;
            case SOCK_SEQPACKET:
                printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_socktype);
                break;
        }
        printf("\tProtocol: ");
        switch (ptr->ai_protocol) {
            case 0:
                printf("Unspecified\n");
                break;
            case IPPROTO_TCP:
                printf("IPPROTO_TCP (TCP)\n");
                break;
            case IPPROTO_UDP:
                printf("IPPROTO_UDP (UDP) \n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_protocol);
                break;
        }
        printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        printf("\tCanonical name: %s\n", ptr->ai_canonname);
    }

    freeaddrinfo(result);
    WSACleanup();

    return 0;
}

メモ開発環境が、addrinfo と getaddrinfo の構造体と関数の定義をそれぞれ含む Ws2tcpip.h の最新バージョンをターゲットにしていることを確認します。

国際化ドメイン名

インターネットホスト名は、通常、非常に制限された文字のセットで構成されます。

英文字の大文字と小文字の ASCII 文字。
0 から 9 の数字。
ASCII ハイフン文字。

インターネットの成長に伴い、ASCII 文字セットで表されない他の言語のインターネットホスト名を識別する必要性が高まっています。このニーズを容易にし、ASCII 以外の文字 (Unicode) を特殊な ASCII 文字列として表現できるようにする識別子は、国際化ドメイン名 (IDN) と呼ばれます。アプリケーションのドメイン名の国際化 (IDNA) と呼ばれるメカニズムは、IDN を標準的な方法で処理するために使用されます。 IDN と IDNA の仕様は、インターネットエンジニアリングタスクフォース (IETF) によって公開されている RFC 3490、 RTF 5890、 RFC 6365 に記載されています。

Windows 8およびWindows Server 2012では、getaddrinfo 関数は、pNodeName パラメーターで渡された名前に適用される国際化ドメイン名 (IDN) の解析をサポートします。 Winsock は Punycode/IDN エンコードと変換を実行します。この動作は、以下で説明する AI_DISABLE_IDN_ENCODING フラグを使用して無効にすることができます。

Windows 7 および Windows Server 2008 R2 以前では、 getaddrinfo 関数は現在、 pNodeName パラメーターで渡された名前に適用されるサポート IDN 解析を提供していません。 Winsock では、Punycode/IDN 変換は実行されません。 GetAddrInfo 関数のワイド文字バージョンでは、RFC 3490 に従って IDN を変換するために Punycode を使用しません。 DNS のクエリ時の GetAddrInfo 関数のワイド文字バージョンでは、エンタープライズ環境の Microsoft DNS サーバーで使用される形式である UTF-8 形式の Unicode 名がエンコードされます。

Windows Vista 以降のいくつかの関数では、IDN 内の Unicode ラベル間の ASCII 対応への変換がサポートされています。結果として得られる各 Unicode ラベルの表現には ASCII 文字のみが含まれ、Unicode ラベルに ASCII 以外の文字が含まれている場合は xn-- プレフィックスで始まります。これは、一部の DNS ツールとサーバーが ASCII 文字のみをサポートしているため、インターネット上の既存の DNS サーバーをサポートするためです ( RFC 3490 を参照)。

IdnToAscii 関数は、RFC 3490 で定義されている標準アルゴリズムを使用して、Punycode を使用して IDN を元の Unicode 文字列の ASCII 表現に変換します。 IdnToUnicode 関数は、IDN の ASCII 形式を通常の Unicode UTF-16 エンコード構文に変換します。関連するドラフト標準の詳細とリンクについては、「国際化ドメイン名 (IDN) の処理」を参照してください。

IdnToAscii 関数を使用して、IDN 名を ASCII 形式に変換し、pNodeName パラメーターで getaddrinfo 関数に渡すことができます。この関数のワイド文字バージョンが使用されている場合 (UNICODE または_UNICODEが定義されている場合)、この IDN 名を GetAddrInfo 関数に渡すには、 MultiByteToWideChar 関数を使用して CHAR 文字列を WCHAR 文字列に変換できます。

pHints パラメーターでのai_flagsの使用

pHints パラメーターで提供される省略可能な addrinfo 構造体のai_flags メンバー内のフラグは、関数の動作を変更します。

これらのフラグビットは、Windows 7 用 Microsoft Windows ソフトウェア開発キット (Windows SDK) (SDK) の Ws2def.h ヘッダーファイルで定義されています。これらのフラグビットは、Windows Server 2008 および Windows Vista のWindows SDKの Ws2tcpip.h ヘッダーファイルで定義されます。これらのフラグビットは、Windows Server 2003 および Windows XP 用プラットフォーム SDK の Ws2tcpip.h ヘッダーファイルで定義されています。

フラグビットには、次の組み合わせを指定できます。

フラグビット	説明
AI_PASSIVE	AI_PASSIVE フラグを設定すると、呼び出し元は、バインド関数の呼び出しで返されたソケットアドレス構造を使用することを意図しています。 AI_PASSIVE フラグが設定され、pNodeName が NULL ポインターである場合、ソケット・アドレス構造の IP アドレス部分は、IPv4 アドレスの場合はINADDR_ANY、IPv6 アドレスの場合はIN6ADDR_ANY_INITに設定されます。 AI_PASSIVE フラグが設定されていない場合、返されたソケットアドレス構造体は、接続指向プロトコルの connect 関数を呼び出す準備が整っているか、接続なしのプロトコルの connect、sendto、または send 関数を呼び出す準備が整います。この場合、 pNodeName パラメーターが NULL ポインターの場合、ソケットアドレス構造体の IP アドレス部分はループバックアドレスに設定されます。
AI_CANONNAME	AI_CANONNAMEもAI_NUMERICHOSTも使用しない場合、getaddrinfo 関数は解決を試みます。リテラル文字列が渡された場合、getaddrinfo は文字列の変換を試み、ホスト名が渡された場合、 getaddrinfo 関数は名前をアドレスまたは複数のアドレスに解決しようとします。 AI_CANONNAME ビットが設定されている場合、pNodeName パラメーターを NULL にすることはできません。それ以外の場合、 getaddrinfo 関数は WSANO_RECOVERYで失敗します。 AI_CANONNAME ビットが設定され、getaddrinfo 関数が成功を返すと、ppResult パラメーターのai_canonname メンバーは、指定されたノードの正規名を含む NULL で終わる文字列を指します。メモgetaddrinfo 関数は、AI_CANONNAME フラグが設定されている場合に成功を返すことができますが、関連付けられた addrinfo 構造体のai_canonname メンバーは NULL です。したがって、AI_CANONNAME フラグの推奨される使用には、関連付けられた addrinfo 構造体のai_canonname メンバーが NULL であるかどうかをテストすることが含まれます。
AI_NUMERICHOST	AI_NUMERICHOST ビットが設定されている場合、pNodeName パラメーターには NULL 以外の数値ホストアドレス文字列が含まれている必要があります。それ以外の場合は、EAI_NONAME エラーが返されます。このフラグにより、名前解決サービスが呼び出されなくなります。
AI_NUMERICSERV	AI_NUMERICSERV ビットが設定されている場合、pServiceName パラメーターには NULL 以外の数値ポート番号が含まれている必要があります。それ以外の場合は、EAI_NONAME エラーが返されます。このフラグにより、名前解決サービスが呼び出されなくなります。 AI_NUMERICSERV フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_NUMERICSERV フラグは、Microsoft プロバイダーではサポートされていません。
AI_ALL	AI_ALL ビットが設定されている場合は、AI_V4MAPPEDを持つ IPv6 アドレスと IPv4 アドレスに対して要求が行われます。 AI_ALL フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_ALL フラグは、Windows Vista 以降でサポートされています。
AI_ADDRCONFIG	AI_ADDRCONFIG ビットが設定されている場合、グローバルアドレスが構成されている場合にのみ getaddrinfo が解決されます。 AI_ADDRCONFIG フラグが指定されている場合、IPv4 アドレスはローカルシステムで IPv4 アドレスが構成されている場合にのみ返され、IPv6 アドレスはローカルシステムで IPv6 アドレスが構成されている場合にのみ返されます。 IPv4 または IPv6 ループバックアドレスは、有効なグローバルアドレスとは見なされません。 AI_ADDRCONFIG フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_ADDRCONFIG フラグは、Windows Vista 以降でサポートされています。
AI_V4MAPPED	AI_V4MAPPED ビットが設定され、IPv6 アドレスの要求が失敗した場合、IPv4 アドレスに対して名前サービス要求が行われ、これらのアドレスは IPv4 マップ IPv6 アドレス形式に変換されます。 AI_V4MAPPED フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_V4MAPPED フラグは、Windows Vista 以降でサポートされています。
AI_NON_AUTHORITATIVE	AI_NON_AUTHORITATIVE ビットが設定されている場合、NS_EMAIL名前空間プロバイダーは権限のある結果と権限のない結果の両方を返します。 AI_NON_AUTHORITATIVE ビットが設定されていない場合、NS_EMAIL名前空間プロバイダーは権限のある結果のみを返します。 AI_NON_AUTHORITATIVE フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_NON_AUTHORITATIVE フラグは Windows Vista 以降でサポートされており、NS_EMAIL名前空間にのみ適用されます。
AI_SECURE	AI_SECURE ビットが設定されている場合、NS_EMAIL名前空間プロバイダーは、なりすましの可能性を最小限に抑えるために、セキュリティが強化された結果を返します。 AI_SECURE フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_SECURE フラグは Windows Vista 以降でサポートされており、NS_EMAIL名前空間にのみ適用されます。
AI_RETURN_PREFERRED_NAMES	AI_RETURN_PREFERRED_NAMESが設定されている場合は、pNodeName パラメーターに名前を指定しないでください。 NS_EMAIL名前空間プロバイダーは、パブリケーションの優先名を返します。 AI_RETURN_PREFERRED_NAMES フラグは、Windows Vista 以降のWindows SDKで定義されます。 AI_RETURN_PREFERRED_NAMES フラグは Windows Vista 以降でサポートされており、NS_EMAIL名前空間にのみ適用されます。
AI_FQDN	AI_FQDNが設定され、フラット名 (単一ラベル) が指定されている場合、getaddrinfo は名前が最終的に解決された完全修飾ドメイン名を返します。完全修飾ドメイン名は、関連付けられた addrinfo 構造体のai_canonname メンバーで返されます。これは、DNS に登録されている正規名を返す AI_CANONNAME ビットフラグとは異なります。これは、フラット名が解決された完全修飾ドメイン名とは異なる場合があります。設定できるのは、 AI_FQDN ビットと AI_CANONNAME ビットの 1 つだけです。両方のフラグがEAI_BADFLAGSと共に存在する場合、getaddrinfo 関数は失敗します。 AI_FQDN ビットが設定されている場合、pNodeName パラメーターを NULL にすることはできません。それ以外の場合、 GetAddrInfoEx 関数は WSANO_RECOVERYで失敗します。 Windows 7: AI_FQDN フラグは、Windows 7 以降のWindows SDKで定義されています。 AI_FQDN フラグは、Windows 7 以降でサポートされています。
AI_FILESERVER	AI_FILESERVERが設定されている場合、これは、クエリ対象のホスト名がファイル共有シナリオで使用されていることを名前空間プロバイダーに示すヒントです。名前空間プロバイダーは、このヒントを無視できます。 Windows 7: AI_FILESERVER フラグは、Windows 7 以降のWindows SDKで定義されています。 AI_FILESERVER フラグは、Windows 7 以降でサポートされています。

AI_NUMERICHOSTを使用したコード例

次のコード例は、getaddrinfo 関数を使用して、IP アドレスのテキスト文字列表現を、IP アドレスとその他の情報の sockaddr 構造体を含む addrinfo 構造体に変換する方法を示しています。

#undef UNICODE

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// link with Ws2_32.lib
#pragma comment (lib, "Ws2_32.lib")

int __cdecl main(int argc, char **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    DWORD dwRetval;

    int i = 1;
    
    struct addrinfo *result = NULL;
    struct addrinfo *ptr = NULL;
    struct addrinfo hints;


    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s <IP Address String>\n", argv[0]);
        printf("  getaddrinfo determines the IP binary network address\n");
        printf("       %s 207.46.197.32\n", argv[0]);  /* www.contoso.com */
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("WSAStartup failed: %d\n", iResult);
        return 1;
    }

    //--------------------------------
    // Setup the hints address info structure
    // which is passed to the getaddrinfo() function
    ZeroMemory( &hints, sizeof(hints) );
    hints.ai_flags = AI_NUMERICHOST;
    hints.ai_family = AF_UNSPEC;
//    hints.ai_socktype = SOCK_STREAM;
//    hints.ai_protocol = IPPROTO_TCP;


//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval = getaddrinfo(argv[1], NULL, &hints, &result);
    if ( dwRetval != 0 ) {
        printf("getaddrinfo failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    printf("getaddrinfo returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        printf("getaddrinfo response %d\n", i++);
        printf("\tFlags: 0x%x\n", ptr->ai_flags);
        printf("\tFamily: ");
        switch (ptr->ai_family) {
            case AF_UNSPEC:
                printf("Unspecified\n");
                break;
            case AF_INET:
                printf("AF_INET (IPv4)\n");
                break;
            case AF_INET6:
                printf("AF_INET6 (IPv6)\n");
                break;
            case AF_NETBIOS:
                printf("AF_NETBIOS (NetBIOS)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_family);
                break;
        }
        printf("\tSocket type: ");
        switch (ptr->ai_socktype) {
            case 0:
                printf("Unspecified\n");
                break;
            case SOCK_STREAM:
                printf("SOCK_STREAM (stream)\n");
                break;
            case SOCK_DGRAM:
                printf("SOCK_DGRAM (datagram) \n");
                break;
            case SOCK_RAW:
                printf("SOCK_RAW (raw) \n");
                break;
            case SOCK_RDM:
                printf("SOCK_RDM (reliable message datagram)\n");
                break;
            case SOCK_SEQPACKET:
                printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_socktype);
                break;
        }
        printf("\tProtocol: ");
        switch (ptr->ai_protocol) {
            case 0:
                printf("Unspecified\n");
                break;
            case IPPROTO_TCP:
                printf("IPPROTO_TCP (TCP)\n");
                break;
            case IPPROTO_UDP:
                printf("IPPROTO_UDP (UDP) \n");
                break;
            default:
                printf("Other %ld\n", ptr->ai_protocol);
                break;
        }
        printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        printf("\tCanonical name: %s\n", ptr->ai_canonname);
    }

    freeaddrinfo(result);
    WSACleanup();

    return 0;
}

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

getaddrinfo 関数は、Windows XP 以降の Ws2_32.dll に追加されました。以前のバージョンの Windows でこの関数を使用するアプリケーションを実行するには、 Ws2tcpip.h ファイルと Wspiapi.h ファイルを含める必要があります。 Wspiapi.h インクルードファイルを追加すると、getaddrinfo 関数が Wspiapi.h ファイルの WspiapiGetAddrInfo インライン関数に定義されます。実行時に 、WspiapiGetAddrInfo 関数は、Ws2_32.dll または Wship6.dll (Windows 2000 の IPv6 テクノロジプレビューの getaddrinfo を含むファイル) に getaddrinfo が含まれていない場合、 getaddrinfo のバージョンが Wspiapi.h ヘッダーファイル内のコードに基づいてインラインで実装されるように実装されます。このインラインコードは、 getaddrinfo 関数をネイティブにサポートしていない古い Windows プラットフォームで使用されます。

Windows 2000 用 IPv6 テクノロジプレビューがインストールされている場合、Windows 2000 では IPv6 プロトコルがサポートされます。それ以外の場合、Windows XP より前のバージョンの Windows での getaddrinfo のサポートは、IPv4 名前解決の処理に限定されます。

GetAddrInfoW 関数は、getaddrinfo の Unicode バージョンです。 GetAddrInfoW 関数が Windows XP Service Pack 2 (SP2) の Ws2_32.dll に追加されました。 GetAddrInfoW 関数は、SP2 を使用する Windows XP より前のバージョンの Windows では使用できません。

Windows Phone 8: この関数は、Windows Phone 8 以降のWindows Phone ストアアプリでサポートされています。

Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1、 Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	ws2tcpip.h
Library	Ws2_32.lib
[DLL]	Ws2_32.dll