struktur ADDRINFOEX4 (ws2def.h)
Struktur addrinfoex4 digunakan oleh fungsi GetAddrInfoEx untuk menyimpan informasi alamat host ketika antarmuka jaringan tertentu telah diminta.
Sintaks
typedef struct addrinfoex4 {
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;
GUID *ai_provider;
struct addrinfoex4 *ai_next;
int ai_version;
PWSTR ai_fqdn;
int ai_interfaceindex;
HANDLE ai_resolutionhandle;
} ADDRINFOEX4, *PADDRINFOEX4, *LPADDRINFOEX4;
Anggota
ai_flags
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 di anggota ai_canonname pertama. |
|
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 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. 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. 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. 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_fqdn 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. Opsi ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru. |
|
Petunjuk untuk 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. |
|
Menunjukkan bahwa objek saat ini diperluas: yaitu, addrinfoex2 atau lebih besar.
Opsi ini didukung pada Windows 8.1, Windows Server 2012 R2, dan yang lebih baru. |
|
Handel resolusi dikembalikan di anggota ai_resolutionhandle .
Opsi ini didukung pada Windows 10, Windows Server 2016, dan yang lebih baru. |
ai_family
Keluarga alamat.
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_INET dan PF_INET), sehingga konstanta mana pun dapat digunakan.
Tabel di bawah ini mencantumkan nilai umum untuk keluarga alamat meskipun banyak nilai lain dimungkinkan.
ai_socktype
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 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
Panjang, dalam byte, dari buffer yang ditujukkan oleh anggota ai_addr .
ai_canonname
Nama kanonis untuk host.
ai_addr
Penunjuk ke struktur sockaddr . Anggota ai_addr di setiap struktur addrinfoex4 yang dikembalikan menunjuk ke struktur alamat soket yang diisi. Panjang, dalam byte, dari setiap struktur addrinfoex4 yang dikembalikan ditentukan dalam anggota ai_addrlen .
ai_blob
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
Panjang, dalam byte, dari anggota ai_blob .
ai_provider
Penunjuk ke GUID penyedia namespace layanan tertentu.
ai_next
Penunjuk ke struktur berikutnya dalam daftar tertaut. Parameter ini diatur ke NULL dalam struktur addrinfoex4 terakhir dari daftar tertaut.
ai_version
Nomor versi struktur ini. Nilai yang saat ini digunakan untuk versi struktur ini adalah 4.
ai_fqdn
Nama domain yang sepenuhnya memenuhi syarat untuk host.
ai_interfaceindex
Indeks antarmuka, seperti yang didefinisikan oleh IP_ADAPTER_ADDRESSES. Properti IfIndex dikembalikan di GetAdaptersAddresses.
ai_resolutionhandle
Tangani menunjuk ke nama domain yang sepenuhnya memenuhi syarat untuk host.
Keterangan
Struktur addrinfoex4 didukung pada Windows 10 dan Windows Server 2016
Struktur addrinfoex4 digunakan oleh fungsi GetAddrInfoEx untuk menyimpan informasi alamat host ketika AI_EXTENDED AI_FQDN | | AI_CANONNAME | bitAI_RESOLUTION_HANDLE diatur dalam anggota addrinfoex4.ai_flags yang diteruskan melalui GetAddrInfoEx.mengisyaratkan parameter.
Struktur addrinfoex4 adalah versi yang ditingkatkan dari struktur addrinfoex yang dapat mengembalikan nama kanonis, nama domain yang sepenuhnya memenuhi syarat untuk host, dan handel ke nama domain yang sepenuhnya memenuhi syarat. Pada gilirannya, GetAddrInfoEx adalah versi yang disempurnakan dari struktur addrinfo dan addrinfoW yang digunakan dengan fungsi getaddrinfo dan GetAddrInfoW . 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.
Data blob di anggota ai_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.
Ketika UNICODE atau _UNICODE didefinisikan, addrinfoex4 didefinisikan untuk addrinfoex4W, versi Unicode dari struktur ini. Parameter string didefinisikan ke jenis data PWSTR dan struktur addrinfoex4W digunakan.
Ketika UNICODE atau _UNICODE tidak ditentukan, addrinfoex4 didefinisikan ke addrinfoex4A, versi ANSI dari struktur ini. Parameter string adalah dari jenis data char * dan struktur addrinfoex4A digunakan.
Setelah panggilan berhasil ke GetAddrInfoEx, daftar tertaut struktur addrinfoex4 dikembalikan dalam parameter ppResult yang diteruskan ke fungsi GetAddrInfoEx . Daftar dapat diproses dengan mengikuti penunjuk yang disediakan di anggota ai_next dari setiap struktur addrinfoex4 yang dikembalikan hingga penunjuk NULL ditemui. Dalam setiap struktur addrinfoex4 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 addrinfoex4 yang dikembalikan menunjuk ke struktur alamat soket yang diisi, yang panjangnya ditentukan dalam anggota ai_addrlen .
Contoh
Kode berikut menjelaskan melakukan panggilan ke GetAddrInfoEx dengan struktur addrinfoex4 untuk mengambil handel ke FQDN. sampel kemudian memanggil WSAIoctl dengan struktur ASSOCIATE_NAMERES_CONTEXT_INPUT .
//
// Connect to a server using its IPv4 addresses
//
VOID
ConnectServer(
PCWSTR server)
{
int iResult;
PADDRINFOEX4 pResult = NULL;
ADDRINFOEX3 hints = { 0 };
PADDRINFOEX4 pCur = NULL;
WSADATA wsaData;
SOCKET connectSocket = INVALID_SOCKET;
ULONG bytesReturned = 0;
ASSOCIATE_NAMERES_CONTEXT_INPUT input = { 0 };
SOCKADDR_IN clientService;
wchar_t ipstringbuffer[46];
String string;
DWORD dwRetval;
//
// Initialize Winsock
//
iResult = WSAStartup(
MAKEWORD(2, 2),
&wsaData);
if (iResult != 0) {
printf("WSAStartup failed: %d\n", iResult);
goto Exit;
}
//
// Create a SOCKET for connection
//
connectSocket = socket(
AF_UNSPEC,
SOCK_STREAM,
IPPROTO_TCP);
if (connectSocket == INVALID_SOCKET)
{
printf("socket failed: %d\n", WSAGetLastError());
goto Exit;
}
//
// Do name resolution
//
hints.ai_family = AF_INET;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags = AI_EXTENDED | AI_FQDN | AI_CANONNAME | AI_RESOLUTION_HANDLE;
hints.ai_version = ADDRINFOEX_VERSION_4;
dwRetval = GetAddrInfoExW(
server,
NULL,
NS_DNS,
NULL,
(const ADDRINFOEXW*)&hints,
(PADDRINFOEXW*)&pResult,
NULL,
NULL,
NULL, NULL);
if (dwRetval != 0) {
printf("GetAddrInfoEx failed with error: %d\n", dwRetval);
goto Exit;
}
input.TransportSettingId.Guid = ASSOCIATE_NAMERES_CONTEXT;
input.Handle = pResult->ai_resolutionhandle;
//
// Associate socket with the handle
//
if (WSAIoctl(
connectSocket,
SIO_APPLY_TRANSPORT_SETTING,
(VOID *)&input,
sizeof(input),
NULL,
0,
&bytesReturned,
NULL,
NULL) == SOCKET_ERROR)
if (iResult != 0){
printf("WSAIoctl failed: %d\n", WSAGetLastError());
goto Exit;
}
//
// Connect to server
//
pCur = pResult;
while (pCur != NULL)
{
if (pCur->ai_addr->sa_family == AF_INET)
{
clientService = *(const sockaddr_in*)pCur->ai_addr;
clientService.sin_port = htons(80);
if (connect(
connectSocket,
(const SOCKADDR *)&clientService,
sizeof(clientService)) == SOCKET_ERROR)
{
printf("connect failed: %d\n", WSAGetLastError());
goto Exit;
}
}
pCur = pCur->ai_next;
}
Exit:
if (connectSocket != INVALID_SOCKET)
{
closesocket(connectSocket);
}
if (pResult)
{
FreeAddrInfoExW((ADDRINFOEXW*)pResult);
}
WSACleanup();
return;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 10 [khusus aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2016 [hanya aplikasi desktop] |
| Header | ws2def.h |