Fungsi GetAddrInfoW (ws2tcpip.h)
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 |
|---|---|
| Memori tidak cukup untuk melakukan operasi. | |
| 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. | |
| 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 . | |
| 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. | |
| 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. | |
| Nama yang diminta valid, tetapi tidak ada data dari jenis yang diminta yang ditemukan. | |
| Terjadi kesalahan yang tidak dapat dipulihkan saat pencarian database. Kesalahan ini dikembalikan jika terjadi kesalahan yang tidak dapat dipulihkan dalam resolusi nama. | |
| Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini. | |
| 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. | |
| 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;
}
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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk