Fungsi GetAddrInfoW (ws2tcpip.h)

Artikel
08/28/2023

Fungsi GetAddrInfoW menyediakan terjemahan independen protokol dari nama host Unicode ke alamat.

Sintaks

INT WSAAPI GetAddrInfoW(
  [in, optional] PCWSTR          pNodeName,
  [in, optional] PCWSTR          pServiceName,
  [in, optional] const ADDRINFOW *pHints,
  [out]          PADDRINFOW      *ppResult
);

Parameter

[in, optional] pNodeName

Penunjuk ke string Unicode yang dihentikan NULL yang berisi nama host (node) atau string alamat host numerik. Untuk protokol Internet, string alamat host numerik adalah alamat IPv4 desimal bertitik atau alamat hex IPv6.

[in, optional] pServiceName

Penunjuk ke string Unicode yang dihentikan NULL yang berisi nama layanan atau nomor port yang dinyatakan sebagai string.

Nama layanan adalah alias string untuk nomor port. Misalnya, "http" adalah alias untuk port 80 yang ditentukan oleh Internet Engineering Task Force (IETF) sebagai port default yang digunakan oleh server web untuk protokol HTTP. Nilai yang mungkin untuk parameter pServiceName ketika nomor port tidak ditentukan tercantum dalam file berikut:

%WINDIR%\system32\drivers\etc\services

[in, optional] pHints

Penunjuk ke struktur addrinfoW yang memberikan petunjuk tentang jenis soket yang didukung pemanggil.

Anggota ai_addrlen, ai_canonname, ai_addr, dan ai_next struktur addrinfoW yang diarahkan oleh parameter pHints harus nol atau NULL. Jika tidak, fungsi GetAddrInfoEx akan gagal dengan WSANO_RECOVERY.

Lihat Keterangan untuk detail selengkapnya.

[out] ppResult

Penunjuk ke daftar tertaut dari satu atau beberapa struktur addrinfoW yang berisi informasi respons tentang host.

Menampilkan nilai

Keberhasilan mengembalikan nol. Kegagalan mengembalikan kode kesalahan Windows Sockets nonzero, seperti yang ditemukan di Kode Kesalahan Soket Windows.

Sebagian besar kode kesalahan bukan nol yang dikembalikan oleh peta fungsi GetAddrInfoW ke serangkaian kesalahan yang diuraikan oleh rekomendasi Internet Engineering Task Force (IETF). Tabel berikut mencantumkan kode kesalahan ini dan setara WSA-nya. Disarankan agar kode kesalahan WSA digunakan, karena mereka menawarkan informasi kesalahan yang akrab dan komprehensif untuk programmer Winsock.

Nilai kesalahan	Setara WSA	Deskripsi
EAI_AGAIN	WSATRY_AGAIN	Terjadi kegagalan sementara dalam resolusi nama.
EAI_BADFLAGS	WSAEINVAL	Nilai yang tidak valid disediakan untuk anggota ai_flags parameter pHints .
EAI_FAIL	WSANO_RECOVERY	Terjadi kegagalan yang tidak dapat dipulihkan dalam resolusi nama.
EAI_FAMILY	WSAEAFNOSUPPORT	Anggota ai_family parameter pHints tidak didukung.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Terjadi kegagalan alokasi memori.
EAI_NONAME	WSAHOST_NOT_FOUND	Nama tidak diselesaikan untuk parameter yang disediakan atau parameter pNodeName dan pServiceName tidak disediakan.
EAI_SERVICE	WSATYPE_NOT_FOUND	Parameter pServiceName tidak didukung untuk anggota ai_socktype yang ditentukan dari parameter pHints .
EAI_SOCKTYPE	WSAESOCKTNOSUPPORT	Anggota ai_socktype parameter pHints tidak didukung.

Gunakan fungsi gai_strerror untuk mencetak pesan kesalahan berdasarkan kode EAI_* yang dikembalikan oleh fungsi GetAddrInfoW . Fungsi gai_strerror disediakan untuk kepatuhan terhadap rekomendasi IETF, tetapi tidak aman untuk utas. Oleh karena itu, penggunaan fungsi Windows Sockets tradisional, seperti WSAGetLastError, direkomendasikan.

Kode kesalahan	Makna
WSA_NOT_ENOUGH_MEMORY	Memori tidak cukup untuk melakukan operasi.
WSAEAFNOSUPPORT	Alamat yang tidak kompatibel dengan protokol yang diminta digunakan. Kesalahan ini dikembalikan jika anggota ai_family struktur addrinfoW yang diarahkan oleh parameter petunjuk tidak didukung.
WSAEINVAL	Argumen yang tidak valid disediakan. Kesalahan ini dikembalikan jika nilai yang tidak valid disediakan untuk anggota ai_flags struktur addrinfoW yang diarahkan oleh parameter petunjuk .
WSAESOCKTNOSUPPORT	Dukungan untuk jenis soket yang ditentukan tidak ada dalam keluarga alamat ini. Kesalahan ini dikembalikan jika anggota ai_socktype struktur addrinfoW yang diarahkan oleh parameter petunjuk tidak didukung.
WSAHOST_NOT_FOUND	Tidak ada host seperti itu yang diketahui. Kesalahan ini dikembalikan jika nama tidak diselesaikan untuk parameter yang disediakan atau parameter pNodename dan pServicename tidak disediakan.
WSANO_DATA	Nama yang diminta valid, tetapi tidak ada data dari jenis yang diminta yang ditemukan.
WSANO_RECOVERY	Terjadi kesalahan yang tidak dapat dipulihkan saat pencarian database. Kesalahan ini dikembalikan jika terjadi kesalahan yang tidak dapat dipulihkan dalam resolusi nama.
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSATRY_AGAIN	Ini biasanya kesalahan sementara selama resolusi nama host dan berarti bahwa server lokal tidak menerima respons dari server otoritatif. Kesalahan ini dikembalikan ketika kegagalan sementara dalam resolusi nama terjadi.
WSATYPE_NOT_FOUND	Kelas yang ditentukan tidak ditemukan. Parameter pServiceName tidak didukung untuk anggota ai_socktype yang ditentukan dari struktur addrinfoW yang diarahkan oleh parameter petunjuk .

Keterangan

Fungsi GetAddrInfoW adalah versi Unicode dari fungsi yang menyediakan terjemahan independen protokol dari nama host ke alamat. Versi ANSI dari fungsi ini adalah getaddrinfo.

Fungsi GetAddrInfoW mengembalikan hasil untuk namespace NS_DNS . Fungsi GetAddrInfoW menggabungkan semua respons jika lebih dari satu penyedia namespace mengembalikan informasi. Untuk digunakan dengan protokol IPv6 dan IPv4, resolusi nama dapat dilakukan oleh Sistem Nama Domain (DNS), file host lokal, atau dengan mekanisme penamaan lainnya untuk namespace NS_DNS .

Makro dalam file header Winsock menentukan nama fungsi kasus campuran GetAddrInfo dan struktur ADDRINFOT . Fungsi GetAddrInfo ini harus dipanggil dengan parameter pNodeName dan pServiceName dari pointer jenis TCHAR dan parameter pHints dan ppResult dari pointer jenis ADDRINFOT. Ketika UNICODE atau _UNICODE ditentukan, GetAddrInfo didefinisikan ke GetAddrInfoW, versi Unicode fungsi, dan ADDRINFOT didefinisikan ke struktur addrinfoW . Ketika UNICODE atau _UNICODE tidak ditentukan, GetAddrInfo didefinisikan untuk getaddrinfo, versi ANSI dari fungsi, dan ADDRINFOT didefinisikan ke struktur addrinfo .

Salah satu atau kedua parameter pNodeName atau pServiceName harus menunjuk ke string Unicode yang dihentikan NULL; umumnya keduanya disediakan.

Setelah berhasil, daftar tertaut struktur addrinfoW dikembalikan dalam parameter ppResult . Daftar dapat diproses dengan mengikuti penunjuk yang disediakan di anggota ai_next dari setiap struktur addrinfoW yang dikembalikan sampai penunjuk NULL ditemukan. Dalam setiap struktur addrinfoW yang dikembalikan, anggota ai_family, ai_socktype, dan ai_protocol sesuai dengan argumen masing-masing dalam panggilan fungsi soket atau WSASocket . Selain itu, anggota ai_addr di setiap struktur addrinfoW yang dikembalikan menunjuk ke struktur alamat soket yang diisi, yang panjangnya ditentukan dalam anggota ai_addrlen .

Jika parameter pNodeName menunjuk ke nama komputer, semua alamat permanen untuk komputer yang dapat digunakan sebagai alamat sumber dikembalikan. Pada Windows Vista dan yang lebih baru, alamat ini akan mencakup semua alamat IP unicast yang dikembalikan oleh fungsi GetUnicastIpAddressTable atau GetUnicastIpAddressEntry tempat anggota SkipAsSource diatur ke false dalam struktur MIB_UNICASTIPADDRESS_ROW .

Jika parameter pNodeName menunjuk ke string yang sama dengan "localhost", semua alamat loopback di komputer lokal dikembalikan.

Jika parameter pNodeName berisi string kosong, semua alamat terdaftar di komputer lokal dikembalikan.

Pada Windows Server 2003 dan yang lebih baru jika parameter pNodeName menunjuk ke string yang sama dengan ".. localmachine", semua alamat terdaftar di komputer lokal dikembalikan.

Jika parameter pNodeName mengacu pada nama server virtual kluster, hanya alamat server virtual yang dikembalikan. Pada Windows Vista dan yang lebih baru, alamat ini akan mencakup semua alamat IP unicast yang dikembalikan oleh fungsi GetUnicastIpAddressTable atau GetUnicastIpAddressEntry tempat anggota SkipAsSource diatur ke true dalam struktur MIB_UNICASTIPADDRESS_ROW . Lihat Pengklusteran Windows untuk informasi selengkapnya tentang pengklusteran.

Windows 7 dengan Paket Layanan 1 (SP1) dan Windows Server 2008 R2 dengan Paket Layanan 1 (SP1) menambahkan dukungan ke Netsh.exe untuk mengatur atribut SkipAsSource pada alamat IP. Ini juga mengubah perilaku sehingga jika anggota SkipAsSource dalam struktur MIB_UNICASTIPADDRESS_ROW diatur ke false, alamat IP akan didaftarkan di DNS. Jika anggota SkipAsSource diatur ke true, alamat IP tidak terdaftar di DNS.

Perbaikan tersedia untuk Windows 7 dan Windows Server 2008 R2 yang menambahkan dukungan ke Netsh.exe untuk mengatur atribut SkipAsSource pada alamat IP. Perbaikan ini juga mengubah perilaku sehingga jika anggota SkipAsSource dalam struktur MIB_UNICASTIPADDRESS_ROW diatur ke false, alamat IP akan didaftarkan di DNS. Jika anggota SkipAsSource diatur ke true, alamat IP tidak terdaftar di DNS. Untuk informasi selengkapnya, lihat 2386184 Pangkalan Pengetahuan (KB).

Perbaikan serupa juga tersedia untuk Windows Vista dengan Paket Layanan 2 (SP2) dan Windows Server 2008 dengan Paket Layanan 2 (SP2) yang menambahkan dukungan ke Netsh.exe untuk mengatur atribut SkipAsSource pada alamat IP. Perbaikan ini juga mengubah perilaku sehingga jika anggota SkipAsSource dalam struktur MIB_UNICASTIPADDRESS_ROW diatur ke false, alamat IP akan didaftarkan di DNS. Jika anggota SkipAsSource diatur ke true, alamat IP tidak terdaftar di DNS.

Penelepon fungsi GetAddrInfoW dapat memberikan petunjuk tentang jenis soket yang didukung melalui struktur addrinfoW yang diarahkan oleh parameter pHints . Ketika parameter pHints digunakan, aturan berikut berlaku untuk struktur addrinfoW terkait:

Nilai AF_UNSPEC untuk ai_family menunjukkan pemanggil hanya akan menerima keluarga alamat AF_INET dan AF_INET6 . Perhatikan bahwa AF_UNSPEC dan PF_UNSPEC sama.
Nilai nol untuk ai_socktype menunjukkan pemanggil akan menerima jenis soket apa pun.
Nilai nol untuk ai_protocol menunjukkan pemanggil akan menerima protokol apa pun.
Anggota ai_addrlen harus diatur ke nol.
Anggota ai_canonname harus diatur ke NULL.
Anggota ai_addr harus diatur ke NULL.
Anggota ai_next harus diatur ke NULL.

Nilai lain dalam struktur addrinfoW yang disediakan dalam parameter pHints menunjukkan persyaratan tertentu. Misalnya, jika pemanggil hanya menangani IPv4 dan tidak menangani IPv6, anggota ai_family harus diatur ke AF_INET. Misalnya, jika pemanggil hanya menangani TCP dan tidak menangani UDP, anggota ai_socktype harus diatur ke SOCK_STREAM.

Jika parameter pHints adalah penunjuk NULL , fungsi GetAddrInfoW menanganinya seolah-olah struktur addrinfoW dalam pHints diinisialisasi dengan anggota ai_family diatur ke AF_UNSPEC dan semua anggota lainnya diatur ke nol.

Pada Windows Vista dan yang lebih baru ketika GetAddrInfoW dipanggil dari layanan, jika operasi adalah hasil dari proses pengguna yang memanggil layanan, maka layanan harus meniru pengguna. Hal ini untuk memungkinkan keamanan diberlakukan dengan benar.

Fungsi GetAddrInfoW dapat digunakan untuk mengonversi representasi string teks alamat IP ke struktur addrinfoW yang berisi struktur sockaddr untuk alamat IP dan informasi lainnya. Untuk digunakan dengan cara ini, string yang ditunjukkan oleh parameter pNodeName harus berisi representasi teks alamat IP dan struktur addrinfoW yang ditunjukkan oleh parameter pHints harus memiliki bendera AI_NUMERICHOST yang diatur dalam anggota ai_flags . String yang ditunjukkan oleh parameter pNodeName mungkin berisi representasi teks dari alamat IPv4 atau IPv6. Alamat IP teks dikonversi ke struktur addrinfoW yang diarahkan oleh parameter ppResult . Struktur addrinfoW yang dikembalikan berisi struktur sockaddr untuk alamat IP bersama dengan informasi tambahan tentang alamat IP. Agar metode ini berfungsi dengan string alamat IPv6 pada Windows Server 2003 dan Windows XP, protokol IPv6 harus diinstal pada komputer lokal. Jika tidak, kesalahan WSAHOST_NOT_FOUND dikembalikan.

Membebaskan Informasi Alamat dari Alokasi Dinamis

Semua informasi yang dikembalikan oleh fungsi GetAddrInfoW yang diarahkan oleh parameter ppResult dialokasikan secara dinamis, termasuk semua struktur addrinfoW , struktur alamat soket, dan string nama host kanonis yang diarahkan oleh struktur addrinfoW . Memori yang dialokasikan oleh panggilan yang berhasil ke fungsi ini harus dirilis dengan panggilan berikutnya ke FreeAddrInfoW.

Contoh Kode

Contoh kode berikut menunjukkan cara menggunakan fungsi GetAddrInfoW .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

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

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

// set APPVER=5.02 for WinXP SP2 and later

int __cdecl wmain(int argc, wchar_t **argv)
{

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

    DWORD dwRetval;

    int i = 1;
    
    ADDRINFOW *result = NULL;
    ADDRINFOW *ptr = NULL;
    ADDRINFOW hints;

//    struct sockaddr_in6 *sockaddr_ipv6;
    LPSOCKADDR sockaddr_ip;

    wchar_t ipstringbuffer[46];
    DWORD ipbufferlength = 46;

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


    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"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;

    wprintf(L"Calling getaddrinfow with following parameters:\n");
    wprintf(L"\tnodename = %ws\n", argv[1]);
    wprintf(L"\tservname (or port) = %ws\n\n", argv[2]);
    

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

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

        wprintf(L"GetAddrInfoW response %d\n", i++);
        wprintf(L"\tFlags: 0x%x\n", ptr->ai_flags);
        wprintf(L"\tFamily: ");
        switch (ptr->ai_family) {
            case AF_UNSPEC:
                wprintf(L"Unspecified\n");
                break;
            case AF_INET:
                wprintf(L"AF_INET (IPv4)\n");
                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)
                    wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
                else    
                    wprintf(L"\tIPv4 address %ws\n", ipstringbuffer);
                break;
            case AF_INET6:
                wprintf(L"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)
                    wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
                else    
                    wprintf(L"\tIPv6 address %ws\n", ipstringbuffer);
                break;
            default:
                wprintf(L"Other %ld\n", ptr->ai_family);
                break;
        }
        wprintf(L"\tSocket type: ");
        switch (ptr->ai_socktype) {
            case 0:
                wprintf(L"Unspecified\n");
                break;
            case SOCK_STREAM:
                wprintf(L"SOCK_STREAM (stream)\n");
                break;
            case SOCK_DGRAM:
                wprintf(L"SOCK_DGRAM (datagram) \n");
                break;
            case SOCK_RAW:
                wprintf(L"SOCK_RAW (raw) \n");
                break;
            case SOCK_RDM:
                wprintf(L"SOCK_RDM (reliable message datagram)\n");
                break;
            case SOCK_SEQPACKET:
                wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)\n");
                break;
            default:
                wprintf(L"Other %ld\n", ptr->ai_socktype);
                break;
        }
        wprintf(L"\tProtocol: ");
        switch (ptr->ai_protocol) {
            case 0:
                wprintf(L"Unspecified\n");
                break;
            case IPPROTO_TCP:
                wprintf(L"IPPROTO_TCP (TCP)\n");
                break;
            case IPPROTO_UDP:
                wprintf(L"IPPROTO_UDP (UDP) \n");
                break;
            default:
                wprintf(L"Other %ld\n", ptr->ai_protocol);
                break;
        }
        wprintf(L"\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
        wprintf(L"\tCanonical name: %s\n", ptr->ai_canonname);
    }

    FreeAddrInfoW(result);
    WSACleanup();

    return 0;
}

Catatan Pastikan bahwa lingkungan pengembangan menargetkan versi terbaru Ws2tcpip.h yang mencakup definisi struktur dan fungsi untuk addrinfoW dan GetAddrInfoW.

Nama Domain Internasional

Nama host internet biasanya terdiri dari sekumpulan karakter yang sangat terbatas:

Huruf besar dan kecil ASCII dari alfabet bahasa Inggris.
Digit dari 0 hingga 9.
Karakter tanda hubung ASCII.

Dengan pertumbuhan Internet, ada kebutuhan yang berkembang untuk mengidentifikasi nama host Internet untuk bahasa lain yang tidak diwakili oleh set karakter ASCII. Pengidentifikasi yang memfasilitasi kebutuhan ini dan memungkinkan karakter non-ASCII (Unicode) direpresentasikan sebagai string karakter ASCII khusus dikenal sebagai Nama Domain Internasional (IDN). Mekanisme yang disebut Internationalisasi Nama Domain dalam Aplikasi (IDNA) digunakan untuk menangani IDN dengan cara standar. Spesifikasi untuk IDN dan IDNA di dokumentasikan dalam RFC 3490, RTF 5890, dan RFC 6365 yang diterbitkan oleh Internet Engineering Task Force (IETF).

Pada Windows 8 dan Windows Server 2012, fungsi GetAddrInfoW menyediakan dukungan untuk penguraian Nama Domain Internasional (IDN) yang diterapkan pada nama yang diteruskan dalam parameter pNodeName . Winsock melakukan pengodean dan konversi Punycode/IDN. Perilaku ini dapat dinonaktifkan menggunakan bendera AI_DISABLE_IDN_ENCODING yang dibahas di bawah ini.

Pada Windows 7 dan Windows Server 2008 R2 atau yang lebih lama, fungsi GetAddrInfoW saat ini tidak menyediakan dukungan untuk penguraian IDN yang diterapkan pada nama yang diteruskan dalam parameter pNodeName . Winsock tidak melakukan konversi Punycode/IDN apa pun. Fungsi GetAddrInfoW tidak menggunakan Punycode untuk mengonversi IDN sesuai RFC 3490. Fungsi GetAddrInfoW saat mengkueri DNS mengodekan nama Unicode dalam format UTF-8, format yang digunakan oleh server DNS Microsoft di lingkungan perusahaan.

Beberapa fungsi pada Windows Vista dan kemudian mendukung konversi antara label Unicode dalam IDN ke setara ASCII mereka. Representasi yang dihasilkan dari setiap label Unicode hanya berisi karakter ASCII dan dimulai dengan awalan xn-- jika label Unicode berisi karakter non-ASCII. Alasan untuk ini adalah untuk mendukung server DNS yang ada di Internet, karena beberapa alat dan server DNS hanya mendukung karakter ASCII (lihat RFC 3490).

Fungsi IdnToAscii menggunakan Punycode untuk mengonversi IDN ke representasi ASCII dari string Unicode asli menggunakan algoritma standar yang ditentukan dalam RFC 3490. Fungsi IdnToUnicode mengonversi bentuk ASCII dari IDN ke sintaks pengodean Unicode UTF-16 normal. Untuk informasi selengkapnya dan tautan ke standar draf terkait, lihat Menangani Nama Domain Internasional (IDN).

Fungsi IdnToAscii dapat digunakan untuk mengonversi nama IDN ke formulir ASCII. Untuk meneruskan formulir ASCII ini ke fungsi GetAddrInfoW , Anda dapat menggunakan fungsi MultiByteToWideChar untuk mengonversi string CHAR menjadi string WCHAR yang kemudian dapat diteruskan dalam parameter pNodeName ke fungsi GetAddrInfoW .

Penggunaan ai_flags dalam parameter petunjuk

Bendera di ai_flags anggota struktur addrinfoW opsional yang disediakan dalam parameter pHints mengubah perilaku fungsi.

Bit bendera ini didefinisikan dalam file header Ws2def.h pada Microsoft Windows Software Development Kit (SDK) untuk Windows 7. Bit bendera ini ditentukan dalam file header Ws2tcpip.h pada Windows SDK untuk Windows Server 2008 dan Windows Vista. Bit bendera ini didefinisikan dalam file header Ws2tcpip.h pada Platform Software Development Kit (SDK) untuk Windows Server 2003, dan Windows XP.

Bit bendera dapat berupa kombinasi dari yang berikut ini:

Bit Bendera	Deskripsi
AI_PASSIVE	Mengatur bendera AI_PASSIVE menunjukkan pemanggil berniat menggunakan struktur alamat soket yang dikembalikan dalam panggilan ke fungsi ikatan . Ketika bendera AI_PASSIVE diatur dan pNodeName adalah penunjuk NULL , bagian alamat IP dari struktur alamat soket diatur ke INADDR_ANY untuk alamat IPv4 dan IN6ADDR_ANY_INIT untuk alamat IPv6. Ketika bendera AI_PASSIVE tidak diatur, struktur alamat soket yang dikembalikan siap untuk panggilan ke fungsi sambungkan untuk protokol berorientasi koneksi, atau siap untuk panggilan ke fungsi sambungkan, kirim, atau kirim untuk protokol tanpa koneksi. Jika parameter pNodeName adalah penunjuk NULL dalam hal ini, bagian alamat IP dari struktur alamat soket diatur ke alamat loopback.
AI_CANONNAME	Jika tidak AI_CANONNAME atau AI_NUMERICHOST digunakan, fungsi GetAddrInfoW mencoba resolusi. Jika string harfiah diteruskan GetAddrInfoW mencoba mengonversi string, dan jika nama host diteruskan fungsi GetAddrInfoW mencoba menyelesaikan nama ke alamat atau beberapa alamat. Ketika bit AI_CANONNAME diatur, parameter pNodeName tidak boleh NULL. Jika tidak, fungsi GetAddrInfoEx akan gagal dengan WSANO_RECOVERY. Ketika bit AI_CANONNAME diatur dan fungsi GetAddrInfoW mengembalikan keberhasilan, anggota ai_canonname dalam parameter ppResult menunjuk ke string yang dihentikan NULL yang berisi nama kanonis dari simpul yang ditentukan. Catatan Fungsi GetAddrInfoW dapat mengembalikan keberhasilan ketika bendera AI_CANONNAME diatur, namun anggota ai_canonname dalam struktur addrinfoW terkait adalah NULL. Oleh karena itu, penggunaan bendera AI_CANONNAME yang direkomendasikan mencakup pengujian apakah anggota ai_canonname dalam struktur addrinfoW terkait adalah NULL.
AI_NUMERICHOST	Ketika bit AI_NUMERICHOST diatur, parameter pNodeName harus berisi string alamat host numerik non-NULL, jika tidak, kesalahan EAI_NONAME dikembalikan. Bendera ini mencegah layanan resolusi nama dipanggil.
AI_NUMERICSERV	Ketika bit AI_NUMERICSERV diatur, parameter pServiceName harus berisi nomor port numerik non-NULL, jika tidak, kesalahan EAI_NONAME dikembalikan. Bendera ini mencegah layanan resolusi nama dipanggil. Bendera AI_NUMERICSERV ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_NUMERICSERV tidak didukung oleh penyedia Microsoft.
AI_ALL	Jika bit AI_ALL diatur, permintaan dibuat untuk alamat IPv6 dan alamat IPv4 dengan AI_V4MAPPED. Bendera AI_ALL ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_ALL didukung pada Windows Vista dan yang lebih baru.
AI_ADDRCONFIG	Jika bit AI_ADDRCONFIG diatur, GetAddrInfoW hanya akan diselesaikan jika alamat global dikonfigurasi. Jika bendera AI_ADDRCONFIG ditentukan, alamat IPv4 akan dikembalikan hanya jika alamat IPv4 dikonfigurasi pada sistem lokal, dan alamat IPv6 akan dikembalikan hanya jika alamat IPv6 dikonfigurasi pada sistem lokal. Alamat loopback IPv4 atau IPv6 tidak dianggap sebagai alamat global yang valid. Bendera AI_ADDRCONFIG ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_ADDRCONFIG didukung pada Windows Vista dan yang lebih baru.
AI_V4MAPPED	Jika bit AI_V4MAPPED diatur dan permintaan untuk alamat IPv6 gagal, permintaan layanan nama dibuat untuk alamat IPv4 dan alamat ini dikonversi ke format alamat IPv6 yang dipetakan IPv4. Bendera AI_V4MAPPED ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_V4MAPPED didukung pada Windows Vista dan yang lebih baru.
AI_NON_AUTHORITATIVE	Jika bit AI_NON_AUTHORITATIVE diatur, penyedia namespace NS_EMAIL mengembalikan hasil otoritatif dan non-otoritatif. Jika bit AI_NON_AUTHORITATIVE tidak diatur, penyedia namespace NS_EMAIL hanya mengembalikan hasil otoritatif. Bendera AI_NON_AUTHORITATIVE ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_NON_AUTHORITATIVE didukung pada Windows Vista dan yang lebih baru dan hanya berlaku untuk namespace NS_EMAIL .
AI_SECURE	Jika bit AI_SECURE diatur, penyedia namespace NS_EMAIL akan mengembalikan hasil yang diperoleh dengan keamanan yang ditingkatkan untuk meminimalkan kemungkinan spoofing. Bendera AI_SECURE ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_SECURE didukung pada Windows Vista dan yang lebih baru dan hanya berlaku untuk namespace NS_EMAIL .
AI_RETURN_PREFERRED_NAMES	Jika AI_RETURN_PREFERRED_NAMES diatur, maka tidak ada nama yang harus disediakan dalam parameter pNodeName . Penyedia namespace NS_EMAIL akan mengembalikan nama pilihan untuk publikasi. Bendera AI_RETURN_PREFERRED_NAMES ditentukan pada Windows SDK untuk Windows Vista dan yang lebih baru. Bendera AI_RETURN_PREFERRED_NAMES didukung pada Windows Vista dan yang lebih baru dan hanya berlaku untuk namespace NS_EMAIL .
AI_FQDN	Jika AI_FQDN diatur dan nama datar (label tunggal) ditentukan, GetAddrInfoW akan mengembalikan nama domain yang sepenuhnya memenuhi syarat yang akhirnya diselesaikan oleh nama tersebut. Nama domain yang sepenuhnya memenuhi syarat dikembalikan di anggota ai_canonname dalam struktur addrinfoW terkait. Ini berbeda dari bendera bit AI_CANONNAME yang mengembalikan nama kanonis yang terdaftar di DNS yang mungkin berbeda dari nama domain yang sepenuhnya memenuhi syarat yang diselesaikan oleh nama datar. Hanya salah satu bit AI_FQDN dan AI_CANONNAME yang dapat diatur. Fungsi GetAddrInfoW akan gagal jika kedua bendera ada dengan EAI_BADFLAGS. Ketika bit AI_FQDN diatur, parameter pNodeName tidak boleh NULL. Jika tidak, fungsi GetAddrInfoEx akan gagal dengan WSANO_RECOVERY. Windows 7: Bendera AI_FQDN ditentukan pada Windows SDK untuk Windows 7 dan yang lebih baru. Bendera AI_FQDN didukung pada Windows 7 dan yang lebih baru.
AI_FILESERVER	Jika AI_FILESERVER diatur, ini adalah petunjuk untuk penyedia namespace layanan bahwa nama host yang dikueri sedang digunakan dalam skenario berbagi file. Penyedia namespace mungkin mengabaikan petunjuk ini. Windows 7: Bendera AI_FILESERVER ditentukan pada Windows SDK untuk Windows 7 dan yang lebih baru. Bendera AI_FILESERVER didukung pada Windows 7 dan yang lebih baru.
AI_DISABLE_IDN_ENCODING	Jika AI_DISABLE_IDN_ENCODING diatur, ini menonaktifkan pengodean Nama Domain Internasional otomatis menggunakan Punycode dalam fungsi resolusi nama yang disebut oleh fungsi GetAddrInfoW . Windows 8: Bendera AI_DISABLE_IDN_ENCODING ditentukan pada Windows SDK untuk Windows 8 dan yang lebih baru. Bendera AI_DISABLE_IDN_ENCODING didukung pada Windows 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Catatan

Header ws2tcpip.h mendefinisikan GetAddrInfo sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP, Windows 8.1 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	ws2tcpip.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll