Struktur ADDRINFOEXW (ws2def.h)
Struktur addrinfoex digunakan oleh fungsi GetAddrInfoEx untuk menyimpan informasi alamat host.
Sintaks
typedef struct addrinfoexW {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
PWSTR ai_canonname;
struct sockaddr *ai_addr;
void *ai_blob;
size_t ai_bloblen;
LPGUID ai_provider;
struct addrinfoexW *ai_next;
} ADDRINFOEXW, *PADDRINFOEXW, *LPADDRINFOEXW;
Anggota
ai_flags
Jenis: int
Bendera yang menunjukkan opsi yang digunakan dalam fungsi GetAddrInfoEx .
Nilai yang didukung untuk anggota ai_flags didefinisikan dalam file sertakan Winsock2.h dan dapat menjadi kombinasi dari opsi berikut.
| Nilai | Makna |
|---|---|
|
Alamat soket akan digunakan dalam panggilan ke fungsi ikatan . |
|
Nama kanonis dikembalikan dalam anggota ai_canonname pertama.
Ketika bit AI_CANONNAME dan AI_FQDN diatur, struktur addrinfoex2 dikembalikan bukan struktur addrinfoex . |
|
Parameter nodename yang diteruskan ke fungsi GetAddrInfoEx 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. |
|
GetAddrInfoEx 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 GetAddrInfoEx 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 berasal dari hasil non-otoritatif.
Ketika opsi ini diatur dalam parameter pHintsGetAddrInfoEx, penyedia namespace NS_EMAIL mengembalikan hasil otoritatif dan non-otoritatif. Jika opsi ini tidak diatur, maka hanya hasil otoritatif yang dikembalikan. Dalam parameter ppResults yang dikembalikan oleh GetAddrInfoEx, bendera ini diatur dalam ai_flags anggota struktur addrinfoex untuk hasil non-otoritatif. Opsi ini hanya didukung pada Windows Vista dan yang lebih baru untuk namespace NS_EMAIL . |
|
Informasi alamat berasal dari saluran aman. Jika bit AI_SECURE diatur, penyedia namespace NS_EMAIL akan mengembalikan hasil yang diperoleh dengan keamanan yang ditingkatkan untuk meminimalkan kemungkinan spoofing.
Ketika opsi ini diatur dalam parameter pHintsGetAddrInfoEx, penyedia namespace NS_EMAIL hanya mengembalikan hasil yang diperoleh dengan keamanan yang ditingkatkan untuk meminimalkan kemungkinan spoofing. Dalam parameter ppResults yang dikembalikan oleh GetAddrInfoEx, bendera ini diatur dalam ai_flags anggota struktur addrinfoex untuk hasil yang dikembalikan dengan keamanan yang ditingkatkan untuk meminimalkan kemungkinan spoofing. Opsi ini hanya didukung pada Windows Vista dan yang lebih baru untuk namespace NS_EMAIL . |
|
Informasi alamat adalah untuk nama pilihan untuk publikasi dengan namespace tertentu.
Ketika opsi ini diatur dalam parameter pHintsGetAddrInfoEx, tidak ada nama yang harus disediakan dalam parameter pName dan penyedia namespace NS_EMAIL akan mengembalikan nama pilihan untuk publikasi. Dalam parameter ppResults yang dikembalikan oleh GetAddrInfoEx, bendera ini diatur dalam ai_flags anggota struktur addrinfoex untuk hasil yang dikembalikan untuk nama pilihan untuk publikasi. Opsi ini hanya didukung pada Windows Vista dan yang lebih baru untuk namespace NS_EMAIL . |
|
Nama domain yang sepenuhnya memenuhi syarat dikembalikan di anggota ai_canonicalname pertama.
Ketika opsi ini diatur dalam parameter pHintsgetAddrInfoEx dan nama datar (label tunggal) ditentukan dalam parameter pName , nama domain yang sepenuhnya memenuhi syarat yang akhirnya diselesaikan oleh nama tersebut akan dikembalikan. Ketika bit AI_CANONNAME dan AI_FQDN diatur, struktur addrinfoex2 dikembalikan bukan struktur addrinfoex . 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 disebut oleh fungsi GetAddrInfoEx .
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 sertakan 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 di bawah ini 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 Kendali 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 ditentukan.
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 didefinisikan 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
Panjang, dalam byte, dari buffer yang ditujukkan oleh anggota ai_addr .
ai_canonname
Jenis: PCTSTR
Nama kanonis untuk host.
ai_addr
Jenis: struct sockaddr*
Penunjuk ke struktur sockaddr . Anggota ai_addr di setiap struktur addrinfoex yang dikembalikan menunjuk ke struktur alamat soket yang diisi. Panjang, dalam byte, dari setiap struktur addrinfoex yang dikembalikan ditentukan dalam anggota ai_addrlen .
ai_blob
Jenis: void*
Penunjuk ke data yang digunakan untuk mengembalikan informasi namespace layanan khusus penyedia yang terkait dengan nama di luar daftar alamat. Panjang, dalam byte, dari buffer yang diacu oleh ai_blob harus ditentukan dalam anggota ai_bloblen .
ai_bloblen
Jenis: size_t
Panjang, dalam byte, dari anggota ai_blob .
ai_provider
Jenis: LPGUID
Penunjuk ke GUID penyedia namespace layanan tertentu.
ai_next
Jenis: struct addrinfoex*
Penunjuk ke struktur berikutnya dalam daftar tertaut. Parameter ini diatur ke NULL dalam struktur addrinfoex terakhir dari daftar tertaut.
Keterangan
Struktur addrinfoex digunakan oleh fungsi GetAddrInfoEx untuk menyimpan informasi alamat host. Struktur addrinfoex adalah versi yang disempurnakan dari struktur addrinfo dan addrinfoW . Anggota struktur tambahan adalah untuk data blob dan GUID untuk penyedia namespace. Data blob digunakan untuk mengembalikan informasi namespace layanan khusus penyedia tambahan yang terkait dengan nama. Format data dalam anggota ai_blob khusus untuk penyedia namespace tertentu. Saat ini, data blob digunakan oleh penyedia namespace NS_EMAIL untuk menyediakan informasi tambahan.
Struktur addrinfoex adalah versi yang disempurnakan dari struktur addrinfo dan addrinfoW yang digunakan dengan fungsi GetAddrInfoEx . Fungsi GetAddrInfoEx memungkinkan menentukan penyedia namespace layanan untuk menyelesaikan kueri. Untuk digunakan dengan protokol IPv6 dan IPv4, resolusi nama dapat dilakukan oleh Sistem Nama Domain (DNS), file host lokal, penyedia email ( namespace NS_EMAIL ), atau oleh mekanisme penamaan lainnya.
Ketika UNICODE atau _UNICODE didefinisikan, addrinfoex didefinisikan untuk addrinfoexW, versi Unicode dari struktur ini. Parameter string didefinisikan ke jenis data PWSTR dan struktur addrinfoexW digunakan.
Ketika UNICODE atau _UNICODE tidak ditentukan, addrinfoex didefinisikan ke addrinfoexA, versi ANSI dari struktur ini. Parameter string adalah dari jenis data PCSTR dan struktur addrinfoexA digunakan.
Setelah panggilan berhasil ke GetAddrInfoEx, daftar tertaut struktur addrinfoex dikembalikan dalam parameter ppResult yang diteruskan ke fungsi GetAddrInfoEx . Daftar dapat diproses dengan mengikuti penunjuk yang disediakan di anggota ai_next dari setiap struktur addrinfoex yang dikembalikan sampai pointer NULL ditemui. Dalam setiap struktur addrinfoex 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 addrinfoex yang dikembalikan menunjuk ke struktur alamat soket yang diisi, yang panjangnya ditentukan dalam anggota ai_addrlen .
Contoh
Contoh berikut menunjukkan penggunaan struktur addrinfoex .
#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;
ADDRINFOEX *result = NULL;
ADDRINFOEX *ptr = NULL;
ADDRINFOEX hints;
DWORD dwRetval = 0;
int i = 1;
DWORD dwNamespace = NS_DNS;
LPGUID lpNspid = NULL;
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 GetAddrInfoEx with following parameters:\n");
wprintf(L"\tName = %ws\n", argv[1]);
wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrInfoEx(). If the call succeeds,
// the aiList variable will hold a linked list
// of ADDRINFOEX structures containing response
// information about the host
dwRetval = GetAddrInfoEx(argv[1], argv[2],
dwNamespace, lpNspid, &hints, &result,
NULL, NULL, NULL, NULL);
if (dwRetval != 0) {
wprintf(L"GetAddrInfoEx failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
wprintf(L"GetAddrInfoEx returned success\n");
// Retrieve each address and print out the hex bytes
for (ptr = result; ptr != NULL; ptr = ptr->ai_next) {
wprintf(L"GetAddrInfoEx 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);
}
FreeAddrInfoEx(result);
WSACleanup();
return 0;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Header | ws2def.h (termasuk Windows Server 2012, Windows 7 Windows Server 2008 R2) |