Struktur ADDRINFOW (ws2def.h)
Struktur addrinfoW digunakan oleh fungsi GetAddrInfoW untuk menyimpan informasi alamat host.
Sintaks
typedef struct addrinfoW {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
PWSTR ai_canonname;
struct sockaddr *ai_addr;
struct addrinfoW *ai_next;
} ADDRINFOW, *PADDRINFOW;
Anggota
ai_flags
Jenis: int
Bendera yang menunjukkan opsi yang digunakan dalam fungsi GetAddrInfoW .
Nilai yang didukung untuk anggota ai_flags ditentukan dalam file header Winsock2.h dan dapat menjadi kombinasi dari opsi yang tercantum dalam tabel berikut.
| Nilai | Makna |
|---|---|
|
Alamat soket akan digunakan dalam panggilan ke fungsi ikatan . |
|
Nama kanonis dikembalikan dalam anggota ai_canonname pertama. |
|
Parameter nodename yang diteruskan ke fungsi GetAddrInfoW harus berupa string numerik. |
|
Jika bit ini diatur, permintaan dibuat untuk alamat IPv6 dan alamat IPv4 dengan AI_V4MAPPED.
Opsi ini didukung pada Windows Vista dan yang lebih baru. |
|
GetAddrInfoW hanya akan diselesaikan jika alamat global dikonfigurasi. Alamat loopback IPv6 dan IPv4 tidak dianggap sebagai alamat global yang valid. Opsi ini hanya didukung pada Windows Vista dan yang lebih baru. |
|
Jika permintaan GetAddrInfoW untuk alamat IPv6 gagal, permintaan layanan nama dibuat untuk alamat IPv4 dan alamat ini dikonversi ke format alamat IPv6 yang dipetakan IPv4.
Opsi ini didukung pada Windows Vista dan yang lebih baru. |
|
Informasi alamat dapat berasal dari penyedia namespace layanan non-otoritatif.
Opsi ini hanya didukung pada Windows Vista dan yang lebih baru untuk namespace NS_EMAIL . |
|
Informasi alamat berasal dari saluran aman.
Opsi ini hanya didukung pada Windows Vista dan yang lebih baru untuk namespace NS_EMAIL . |
|
Informasi alamat adalah untuk nama pilihan untuk pengguna.
Opsi ini hanya didukung pada Windows Vista dan yang lebih baru untuk namespace NS_EMAIL . |
|
Jika 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 .
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. Opsi ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru. |
|
Petunjuk ke penyedia namespace layanan bahwa nama host yang dikueri sedang digunakan dalam skenario berbagi file. Penyedia namespace mungkin mengabaikan petunjuk ini.
Opsi ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru. |
|
Nonaktifkan pengodean Nama Domain Internasional otomatis menggunakan Punycode dalam fungsi resolusi nama yang dipanggil oleh fungsi GetAddrInfoW .
Opsi ini didukung pada Windows 8, Windows Server 2012, dan yang lebih baru. |
ai_family
Jenis: int
Keluarga alamat. Nilai yang mungkin untuk keluarga alamat didefinisikan dalam file header Winsock2.h .
Pada Windows SDK yang dirilis untuk Windows Vista dan yang lebih baru, organisasi file header telah berubah dan nilai yang mungkin untuk keluarga alamat ditentukan dalam file header Ws2def.h . Perhatikan bahwa file header Ws2def.h secara otomatis disertakan dalam Winsock2.h, dan tidak boleh digunakan secara langsung.
Nilai yang saat ini didukung adalah AF_INET atau AF_INET6, yang merupakan format keluarga alamat Internet untuk IPv4 dan IPv6. Opsi lain untuk keluarga alamat (AF_NETBIOS untuk digunakan dengan NetBIOS, misalnya) didukung jika penyedia layanan Soket Windows untuk keluarga alamat diinstal. Perhatikan bahwa nilai untuk keluarga alamat AF_ dan konstanta keluarga protokol PF_ identik (misalnya, AF_UNSPEC dan PF_UNSPEC), sehingga konstanta dapat digunakan.
Tabel berikut mencantumkan nilai umum untuk keluarga alamat meskipun banyak nilai lain dimungkinkan.
ai_socktype
Jenis: int
Jenis soket. Nilai yang mungkin untuk jenis soket didefinisikan dalam file sertakan Winsock2.h .
Tabel berikut ini mencantumkan nilai yang mungkin untuk jenis soket yang didukung untuk Windows Sockets 2.
| Nilai | Makna |
|---|---|
|
Menyediakan aliran byte berbasis koneksi berurutan, andal, dua arah, dengan mekanisme transmisi data OOB. Menggunakan Protokol Kontrol Transmisi (TCP) untuk keluarga alamat Internet (AF_INET atau AF_INET6). Jika anggota ai_familyAF_IRDA, maka SOCK_STREAM adalah satu-satunya jenis soket yang didukung. |
|
Mendukung datagram, yang merupakan buffer tanpa koneksi dan tidak dapat diandalkan dengan panjang maksimum tetap (biasanya kecil). Menggunakan Protokol Datagram Pengguna (UDP) untuk keluarga alamat Internet (AF_INET atau AF_INET6). |
|
Menyediakan soket mentah yang memungkinkan aplikasi memanipulasi header protokol lapisan atas berikutnya. Untuk memanipulasi header IPv4, opsi soket IP_HDRINCL harus diatur pada soket. Untuk memanipulasi header IPv6, opsi soket IPV6_HDRINCL harus diatur pada soket. |
|
Menyediakan datagram pesan yang andal. Contoh dari jenis ini adalah implementasi protokol multicast Pragmatic General Multicast (PGM) di Windows, sering disebut sebagai pemrograman multicast yang andal. |
|
Menyediakan paket pseudo-stream berdasarkan datagram. |
Di Windows Sockets 2, jenis soket baru diperkenalkan. Aplikasi dapat secara dinamis menemukan atribut dari setiap protokol transportasi yang tersedia melalui fungsi WSAEnumProtocols . Jadi aplikasi dapat menentukan kemungkinan opsi jenis soket dan protokol untuk keluarga alamat dan menggunakan informasi ini saat menentukan parameter ini. Definisi jenis soket dalam file header Winsock2.h dan Ws2def.h akan diperbarui secara berkala karena jenis soket baru, keluarga alamat, dan protokol didefinisikan.
Di Windows Sockets 1.1, satu-satunya jenis soket yang mungkin adalah SOCK_DATAGRAM dan SOCK_STREAM.
ai_protocol
Jenis: int
Jenis protokol. Opsi yang mungkin khusus untuk keluarga alamat dan jenis soket yang ditentukan. Nilai yang mungkin untuk ai_protocol ditentukan dalam Winsock2.h dan file header Wsrm.h .
Pada Windows SDK yang dirilis untuk Windows Vista dan yang lebih baru, organisasi file header telah berubah dan anggota ini bisa menjadi salah satu nilai dari jenis enumerasi IPPROTO yang ditentukan dalam file header Ws2def.h . Perhatikan bahwa file header Ws2def.h secara otomatis disertakan dalam Winsock2.h, dan tidak boleh digunakan secara langsung.
Jika nilai 0 ditentukan untuk ai_protocol, pemanggil tidak ingin menentukan protokol dan penyedia layanan akan memilih ai_protocol untuk digunakan. Untuk protokol selain IPv4 dan IPv6, atur ai_protocol ke nol.
Tabel berikut ini mencantumkan nilai umum untuk anggota ai_protocol meskipun banyak nilai lain dimungkinkan.
Jika anggota ai_familyAF_IRDA, maka ai_protocol harus 0.
ai_addrlen
Jenis: size_t
Panjangnya, dalam byte, dari buffer yang ditujukkan oleh anggota ai_addr .
ai_canonname
Jenis: PWSTR
Nama kanonis untuk host.
ai_addr
Jenis: struct sockaddr*
Penunjuk ke struktur sockaddr . Anggota ai_addr di setiap struktur ADDRINFOW yang dikembalikan menunjuk ke struktur alamat soket yang diisi. Panjang, dalam byte, dari setiap struktur ADDRINFOW yang dikembalikan ditentukan dalam anggota ai_addrlen .
ai_next
Jenis: struct addrinfoW*
Penunjuk ke struktur berikutnya dalam daftar tertaut. Parameter ini diatur ke NULL dalam struktur addrinfoW terakhir dari daftar yang ditautkan.
Keterangan
Struktur addrinfoW digunakan oleh fungsi Unicode GetAddrInfoW untuk menyimpan informasi alamat host.
Struktur addrinfo adalah versi ANSI dari struktur ini yang digunakan oleh fungsi getaddrinfo ANSI.
Makro dalam file header Ws2tcpip.h menentukan struktur ADDRINFOT dan nama fungsi mixed-case GetAddrInfo. Fungsi GetAddrInfo harus dipanggil dengan parameter nodename dan servname dari pointer jenis TCHAR dan petunjuk dan parameter res dari pointer jenis ADDRINFOT. Ketika UNICODE atau _UNICODE ditentukan, ADDRINFOT didefinisikan ke struktur addrinfoW dan GetAddrInfo didefinisikan ke GetAddrInfoW, versi Unicode dari fungsi ini. Ketika UNICODE atau _UNICODE tidak ditentukan, ADDRINFOT didefinisikan ke struktur addrinfo dan GetAddrInfo didefinisikan untuk getaddrinfo, versi ANSI dari fungsi ini.
Setelah panggilan berhasil ke GetAddrInfoW, daftar tertaut struktur ADDRINFOW dikembalikan dalam parameter ppResult yang diteruskan ke fungsi GetAddrInfoW . Daftar dapat diproses dengan mengikuti penunjuk yang disediakan di anggota ai_next dari setiap struktur ADDRINFOW yang dikembalikan hingga 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 .
Contoh
Contoh kode berikut menunjukkan cara menggunakan struktur addrinfoW .
#ifndef UNICODE
#define UNICODE
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#pragma comment(lib, "Ws2_32.lib")
int __cdecl wmain(int argc, wchar_t ** argv)
{
//--------------------------------
// Declare and initialize variables.
WSADATA wsaData;
int iResult;
ADDRINFOW *result = NULL;
ADDRINFOW *ptr = NULL;
ADDRINFOW hints;
DWORD dwRetval = 0;
int i = 1;
struct sockaddr_in *sockaddr_ipv4;
struct sockaddr_in6 *sockaddr_ipv6;
// LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L" provides protocol-independent translation\n");
wprintf(L" from a 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 GetAddrInfoW() function
memset(&hints, 0, 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"\tName = %ws\n", argv[1]);
wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrInfoW(). If the call succeeds,
// the aiList variable will hold a linked list
// of addrinfo structures containing response
// information about the host
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");
// the InetNtop function is available on Windows Vista and later
sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
wprintf(L"\tIPv4 address %ws\n",
InetNtop(AF_INET, &sockaddr_ipv4->sin_addr, ipstringbuffer,
46));
// We could also use the WSAAddressToString function
// 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;
wprintf(L"\tIPv6 address %ws\n",
InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr,
ipstringbuffer, 46));
// We could also use WSAAddressToString which also returns the scope ID
// 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);
}
FreeAddrInfo(result);
WSACleanup();
return 0;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista, Windows XP dengan SP2 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Header | ws2def.h (termasuk Windows Server 2012, Windows 7 Windows Server 2008 R2) |
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