Struktur ADDRINFOA (ws2def.h)
Struktur addrinfo digunakan oleh fungsi getaddrinfo untuk menyimpan informasi alamat host.
Sintaks
typedef struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
struct addrinfo *ai_next;
} ADDRINFOA, *PADDRINFOA;
Anggota
ai_flags
Jenis: int
Bendera yang menunjukkan opsi yang digunakan dalam fungsi getaddrinfo .
Nilai yang didukung untuk anggota ai_flags ditentukan dalam file header Ws2def.h pada Windows SDK untuk Windows 7 dan yang lebih baru. Nilai-nilai ini didefinisikan dalam file header Ws2tcpip.h pada Windows SDK untuk Windows Server 2008 dan Windows Vista. Nilai-nilai ini didefinisikan dalam file header Ws2tcpip.h pada Platform SDK untuk Windows Server 2003, dan Windows XP. Nilai yang didukung untuk anggota ai_flags bisa 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 getaddrinfo 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. |
|
Getaddrinfo 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 getaddrinfo 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, getaddrinfo 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 getaddrinfo akan gagal jika kedua bendera ada dengan EAI_BADFLAGS. 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. |
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 ini mencantumkan nilai umum untuk keluarga alamat meskipun banyak nilai lain dimungkinkan.
ai_socktype
Jenis: int
Jenis soket. Nilai yang mungkin untuk jenis soket ditentukan dalam file header 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 file header Winsock2.h dan 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: karakter*
Nama kanonis untuk host.
ai_addr
Jenis: struct sockaddr*
Penunjuk ke struktur sockaddr . Anggota ai_addr di setiap titik struktur addrinfo yang dikembalikan ke struktur alamat soket yang diisi. Panjang, dalam byte, dari setiap struktur addrinfo yang dikembalikan ditentukan dalam anggota ai_addrlen .
ai_next
Jenis: struct addrinfo*
Penunjuk ke struktur berikutnya dalam daftar tertaut. Parameter ini diatur ke NULL dalam struktur addrinfo terakhir dari daftar yang ditautkan.
Keterangan
Struktur addrinfo digunakan oleh fungsi getaddrinfo ANSI untuk menyimpan informasi alamat host.
Struktur addrinfoW adalah versi struktur ini yang digunakan oleh fungsi Unicode GetAddrInfoW .
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 tidak ditentukan, ADDRINFOT didefinisikan ke struktur addrinfo dan GetAddrInfo didefinisikan untuk getaddrinfo, versi ANSI dari fungsi ini. Ketika UNICODE atau _UNICODE ditentukan, ADDRINFOT didefinisikan ke struktur addrinfoW dan GetAddrInfo didefinisikan ke GetAddrInfoW, versi Unicode dari fungsi ini.
Setelah panggilan berhasil ke getaddrinfo, daftar tertaut struktur addrinfo dikembalikan dalam parameter res yang diteruskan ke fungsi getaddrinfo . 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 .
Dukungan untuk getaddrinfo dan struct addrinfo pada versi Windows yang lebih lama
Fungsi getaddrinfo yang menggunakan struktur addrinfo ditambahkan ke Ws2_32.dll pada Windows XP dan yang lebih baru. Struktur addrinfo didefinisikan dalam file header Ws2tcpip.h yang disertakan dengan Platform SDK yang dirilis untuk Windows XP dan yang lebih baru dan Windows SDK dirilis untuk Windows Vista dan yang lebih baru.Untuk menjalankan aplikasi yang menggunakan fungsi getaddrinfo dan struktur addrinfo pada versi Windows yang lebih lama (Windows 2000), 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 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 untuk menangani resolusi nama IPv4.
Fungsi GetAddrInfoW yang menggunakan struktur addrinfoW adalah versi Unicode dari fungsi getaddrinfo dan struktur addrinfo terkait. Fungsi GetAddrInfoW ditambahkan ke Ws2_32.dll di Windows XP dengan Paket Layanan 2 (SP2). Fungsi GetAddrInfoW dan struktur addrinfoW tidak dapat digunakan pada versi Windows yang lebih lama dari Windows XP dengan SP2.
Contoh
Contoh kode berikut menunjukkan penggunaan struktur addrinfo .
#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(" 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;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Header | ws2def.h |