fungsi getaddrinfo (ws2tcpip.h)
Fungsi getaddrinfo menyediakan terjemahan independen protokol dari nama host ANSI ke alamat.
Sintaks
INT WSAAPI getaddrinfo(
[in, optional] PCSTR pNodeName,
[in, optional] PCSTR pServiceName,
[in, optional] const ADDRINFOA *pHints,
[out] PADDRINFOA *ppResult
);
Parameter
[in, optional] pNodeName
Penunjuk ke string ANSI yang dihentikan NULL yang berisi nama host (node) atau string alamat host numerik. Untuk protokol Internet, string alamat host numerik adalah alamat IPv4 dotted-decimal atau alamat hex IPv6.
[in, optional] pServiceName
Penunjuk ke string ANSI yang dihentikan NULL yang berisi nama layanan atau nomor port yang direpresentasikan 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 saat nomor port tidak ditentukan tercantum dalam file berikut:
%WINDIR%\system32\drivers\etc\services
[in, optional] pHints
Penunjuk ke struktur addrinfo yang memberikan petunjuk tentang jenis soket yang didukung pemanggil.
Anggota ai_addrlen, ai_canonname, ai_addr, dan ai_next dari struktur addrinfo yang ditujukkan 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 addrinfo yang berisi informasi respons tentang host.
Menampilkan nilai
Keberhasilan mengembalikan nol. Kegagalan mengembalikan kode kesalahan Windows Sockets bukan nol, seperti yang ditemukan di Kode Kesalahan Soket Windows.
Sebagian besar kode kesalahan bukan nol yang dikembalikan oleh peta fungsi getaddrinfo 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 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 getaddrinfo . 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 ai_family anggota struktur addrinfo yang ditujukkan oleh parameter pHints tidak didukung. | |
| Argumen yang tidak valid disediakan. Kesalahan ini dikembalikan jika nilai yang tidak valid disediakan untuk anggota ai_flags struktur addrinfo yang diacu oleh parameter pHints . | |
| Dukungan untuk jenis soket yang ditentukan tidak ada dalam keluarga alamat ini. Kesalahan ini dikembalikan jika anggota ai_socktype struktur addrinfo yang diacu oleh parameter pHints 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 addrinfo yang ditujukkan oleh parameter pHints . |
Keterangan
Fungsi getaddrinfo adalah versi ANSI dari fungsi yang menyediakan terjemahan independen protokol dari nama host ke alamat. Versi Unicode dari fungsi ini adalah GetAddrInfoW. Pengembang didorong untuk menggunakan fungsi GetAddrInfoW Unicode daripada fungsi ansi getaddrinfo .
Fungsi getaddrinfo mengembalikan hasil untuk namespace NS_DNS . Fungsi getaddrinfo 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 lain untuk namespace layanan NS_DNS .
Nama lain yang dapat digunakan untuk fungsi getaddrinfo adalah GetAddrInfoA. Makro dalam file header Ws2tcpip.h menentukan GetAddrInfoA ke getaddrinfo.
Makro dalam file header Ws2tcpip.h menentukan nama fungsi mixed-case 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 tidak ditentukan, GetAddrInfo didefinisikan untuk getaddrinfo, versi ANSI dari fungsi, dan ADDRINFOT didefinisikan ke struktur addrinfo . Ketika UNICODE atau _UNICODE ditentukan, GetAddrInfo didefinisikan ke GetAddrInfoW, versi Unicode fungsi, dan ADDRINFOT didefinisikan ke struktur addrinfoW .
Nama parameter dan jenis parameter untuk fungsi getaddrinfo yang ditentukan dalam file header Ws2tcpip.h pada Platform Software Development Kit (SDK) untuk Windows Server 2003, dan Windows XP berbeda.
Satu atau kedua parameter pNodeName atau pServiceName harus menunjuk ke string ANSI yang dihentikan NULL; umumnya keduanya disediakan.
Setelah berhasil, daftar struktur addrinfo yang ditautkan dikembalikan dalam parameter ppResult . Daftar dapat diproses dengan mengikuti penunjuk yang disediakan di anggota ai_next dari setiap struktur addrinfo yang dikembalikan sampai penunjuk NULL ditemukan. Dalam setiap struktur addrinfo 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 addrinfo 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 getaddrinfo dapat memberikan petunjuk tentang jenis soket yang didukung melalui struktur addrinfo yang diacu oleh parameter pHints . Ketika parameter pHints digunakan, aturan berikut berlaku untuk struktur addrinfo 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 AF_UNSPEC untuk ai_family menunjukkan pemanggil akan menerima keluarga protokol apa pun. Nilai ini dapat digunakan untuk mengembalikan alamat IPv4 dan IPv6 untuk nama host yang ditujukkan oleh parameter pNodeName . Pada Windows Server 2003 dan Windows XP, alamat IPv6 dikembalikan hanya jika IPv6 diinstal pada komputer lokal.
Nilai lain dalam struktur addrinfo yang disediakan dalam parameter pHints menunjukkan persyaratan khusus. 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 getaddrinfo memperlakukannya seolah-olah struktur addrinfo dalam pHints diinisialisasi dengan anggota ai_family diatur ke AF_UNSPEC dan semua anggota lainnya diatur ke nol.
Pada Windows Vista dan kemudian ketika getaddrinfo 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 getaddrinfo dapat digunakan untuk mengonversi representasi string teks alamat IP ke struktur addrinfo 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 addrinfo 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 addrinfo yang ditujukkan oleh parameter ppResult . Struktur addrinfo 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 getaddrinfo yang ditujukkan oleh parameter ppResult dialokasikan secara dinamis, termasuk semua struktur addrinfo , struktur alamat soket, dan string nama host kanonis yang diacu oleh struktur addrinfo . Memori yang dialokasikan oleh panggilan yang berhasil ke fungsi ini harus dirilis dengan panggilan berikutnya ke freeaddrinfo.Contoh Kode
Contoh kode berikut menunjukkan cara menggunakan fungsi 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;
}
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 getaddrinfo 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 getaddrinfo saat ini tidak menyediakan penguraian IDN dukungan yang diterapkan pada nama yang diteruskan dalam parameter pNodeName . Winsock tidak melakukan konversi Punycode/IDN apa pun. Versi karakter lebar fungsi GetAddrInfo tidak menggunakan Punycode untuk mengonversi IDN sesuai RFC 3490. Versi karakter luas fungsi GetAddrInfo 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 yang kemudian dapat diteruskan dalam parameter pNodeName ke fungsi getaddrinfo . Untuk meneruskan nama IDN ini ke fungsi GetAddrInfo saat versi karakter lebar fungsi ini digunakan (ketika UNICODE atau _UNICODE ditentukan), Anda dapat menggunakan fungsi MultiByteToWideChar untuk mengonversi string CHAR menjadi string WCHAR .
Penggunaan ai_flags dalam parameter pHints
Bendera di ai_flags anggota struktur addrinfo 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 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 getaddrinfo mencoba resolusi. Jika string harfiah diteruskan getaddrinfo mencoba mengonversi string, dan jika nama host diteruskan, fungsi getaddrinfo mencoba untuk menyelesaikan nama ke alamat atau beberapa alamat.
Ketika bit AI_CANONNAME diatur, parameter pNodeName tidak boleh NULL. Jika tidak, fungsi getaddrinfo akan gagal dengan WSANO_RECOVERY. Ketika bit AI_CANONNAME diatur dan fungsi getaddrinfo mengembalikan keberhasilan, anggota ai_canonname dalam parameter ppResult menunjuk ke string yang dihentikan NULL yang berisi nama kanonis dari simpul yang ditentukan. Catatan Fungsi getaddrinfo dapat mengembalikan keberhasilan ketika bendera AI_CANONNAME diatur, namun anggota ai_canonname dalam struktur addrinfo terkait adalah NULL. Oleh karena itu, penggunaan bendera AI_CANONNAME yang direkomendasikan mencakup pengujian apakah anggota ai_canonname dalam struktur addrinfo 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, getaddrinfo akan menyelesaikan hanya 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, getaddrinfo akan mengembalikan nama domain yang sepenuhnya memenuhi syarat yang akhirnya diselesaikan oleh nama tersebut. Nama domain yang sepenuhnya memenuhi syarat dikembalikan dalam anggota ai_canonname dalam struktur addrinfo 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 getaddrinfo 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 ke 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. |
Contoh kode menggunakan AI_NUMERICHOST
Contoh kode berikut menunjukkan cara menggunakan fungsi getaddrinfo untuk mengonversi representasi string teks alamat IP ke struktur addrinfo yang berisi struktur sockaddr untuk alamat IP dan informasi lainnya.#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;
}
Dukungan untuk getaddrinfo pada Windows 2000 dan versi yang lebih lama
Fungsi getaddrinfo ditambahkan ke Ws2_32.dll pada Windows XP dan yang lebih baru. Untuk menjalankan aplikasi yang menggunakan fungsi ini pada versi Windows sebelumnya, maka Anda perlu menyertakan file Ws2tcpip.h dan Wspiapi.h . Ketika file yang disertakan Wspiapi.h ditambahkan, fungsi getaddrinfo didefinisikan ke fungsi sebaris WspiapiGetAddrInfo dalam file Wspiapi.h . Pada runtime, fungsi WspiapiGetAddrInfo diimplementasikan sedemikian sehingga jika Ws2_32.dll atau Wship6.dll (file yang berisi getaddrinfo dalam Pratinjau Teknologi IPv6 untuk Windows 2000) tidak menyertakan getaddrinfo, maka versi getaddrinfo diimplementasikan sebaris berdasarkan kode dalam file header Wspiapi.h. Kode sebaris ini akan digunakan pada platform Windows yang lebih lama yang tidak secara asli mendukung fungsi getaddrinfo .Protokol IPv6 didukung pada Windows 2000 ketika Pratinjau Teknologi IPv6 untuk Windows 2000 diinstal. Jika tidak , dukungan getaddrinfo pada versi Windows yang lebih lama dari Windows XP terbatas pada penanganan resolusi nama IPv4.
Fungsi GetAddrInfoW adalah versi Unicode dari getaddrinfo. Fungsi GetAddrInfoW ditambahkan ke Ws2_32.dll di Windows XP dengan Paket Layanan 2 (SP2). Fungsi GetAddrInfoW tidak dapat digunakan pada versi Windows yang lebih lama dari Windows XP dengan SP2.
Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 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.
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