struktur ADDRINFOEX3 (ws2def.h)

Artikel
08/28/2023

Struktur addrinfoex3 digunakan oleh fungsi GetAddrInfoEx untuk menyimpan informasi alamat host ketika antarmuka jaringan tertentu telah diminta.

Sintaks

typedef struct addrinfoex3 {
  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 addrinfoex3 *ai_next;
  int                ai_version;
  PWSTR              ai_fqdn;
  int                ai_interfaceindex;
} ADDRINFOEX3, *PADDRINFOEX3, *LPADDRINFOEX3;

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
AI_PASSIVE 0x01	Alamat soket akan digunakan dalam panggilan ke fungsi ikatan .
AI_CANONNAME 0x02	Nama kanonis dikembalikan di anggota ai_canonname pertama.
AI_NUMERICHOST 0x04	Parameter nodename yang diteruskan ke fungsi GetAddrInfoEx harus berupa string numerik.
AI_ALL 0x0100	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.
AI_ADDRCONFIG 0x0400	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.
AI_V4MAPPED 0x0800	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.
AI_NON_AUTHORITATIVE 0x04000	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 .
AI_SECURE 0x08000	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 .
AI_RETURN_PREFERRED_NAMES 0x010000	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 .
AI_FQDN 0x00020000	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.
AI_FILESERVER 0x00040000	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_DISABLE_IDN_ENCODING 0x00080000	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_EXTENDED 0x80000000	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.

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.

Nilai	Makna
AF_UNSPEC 0	Keluarga alamat tidak ditentukan.
AF_INET 2	Keluarga alamat Protokol Internet versi 4 (IPv4).
AF_NETBIOS 17	Keluarga alamat NetBIOS. Keluarga alamat ini hanya didukung jika penyedia Windows Sockets untuk NetBIOS diinstal.
AF_INET6 23	Keluarga alamat Protokol Internet versi 6 (IPv6).
AF_IRDA 26	Keluarga alamat Asosiasi Data Inframerah (IrDA). Keluarga alamat ini hanya didukung jika komputer memiliki port inframerah dan pengandar yang terinstal.
AF_BTH 32	Keluarga alamat Bluetooth. Keluarga alamat ini hanya didukung jika adaptor Bluetooth diinstal.

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
SOCK_STREAM 1	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.
SOCK_DGRAM 2	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).
SOCK_RAW 3	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.
SOCK_RDM 4	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.
SOCK_SEQPACKET 5	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 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.

Nilai	Makna
IPPROTO_TCP 6	Protokol Kontrol Transmisi (TCP). Ini adalah nilai yang mungkin ketika anggota ai_familyAF_INET atau AF_INET6 dan anggota ai_socktypeSOCK_STREAM.
IPPROTO_UDP 17	Protokol Datagram Pengguna (UDP). Ini adalah nilai yang mungkin ketika anggota ai_familyAF_INET atau AF_INET6 dan parameter jenisSOCK_DGRAM.
IPPROTO_RM 113	Protokol PGM untuk multicast yang andal. Ini adalah nilai yang mungkin ketika anggota ai_familyAF_INET dan anggota ai_socktypeSOCK_RDM. Pada Windows SDK yang dirilis untuk Windows Vista dan yang lebih baru, nilai ini juga disebut IPPROTO_PGM.

Jika anggota ai_familyAF_IRDA, maka ai_protocol harus 0.

ai_addrlen

Panjangnya, 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 addrinfoex3 yang dikembalikan menunjuk ke struktur alamat soket yang diisi. Panjang, dalam byte, dari setiap struktur addrinfoex3 yang dikembalikan ditentukan dalam anggota ai_addrlen .

ai_blob

Penunjuk ke data yang digunakan untuk mengembalikan informasi namespace khusus penyedia yang terkait dengan nama di luar daftar alamat. Panjang, dalam byte, dari buffer yang ditujukkan oleh ai_blob harus ditentukan dalam anggota ai_bloblen .

ai_bloblen

Panjangnya, dalam byte, dari anggota ai_blob .

ai_provider

Penunjuk ke GUID penyedia namespace tertentu.

ai_next

Penunjuk ke struktur berikutnya dalam daftar tertaut. Parameter ini diatur ke NULL dalam struktur addrinfoex3 terakhir dari daftar yang ditautkan.

ai_version

Nomor versi struktur ini. Nilai yang saat ini digunakan untuk versi struktur ini adalah 3.

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.

Keterangan

Struktur addrinfoex3 didukung pada Windows 8.1 dan Windows Server 2012 R2

Struktur addrinfoex3 digunakan oleh fungsi GetAddrInfoEx untuk menyimpan informasi alamat host ketika AI_EXTENDED | AI_FQDN | bit AI_CANONNAME diatur dalam addrinfoex3.ai_flags anggota melewati GetAddrInfoEx. parameter petunjuk . Anda juga harus mengatur addrinfoex3. ai_interfaceindex anggota ke antarmuka yang ingin Anda ambil informasinya, dan ai_version ke 3.

Struktur addrinfoex3 adalah versi yang ditingkatkan dari struktur addrinfoex yang dapat mengembalikan nama kanonis dan nama domain yang sepenuhnya memenuhi syarat untuk host. Pada gilirannya, addrinfoex adalah versi yang disempurnakan dari struktur addrinfo dan addrinfoW yang digunakan dengan fungsi getaddrinfo dan GetAddrInfoW . Fungsi GetAddrInfoEx memungkinkan menentukan penyedia namespace 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 dengan mekanisme penamaan lainnya.

Data blob di anggota ai_blob digunakan untuk mengembalikan informasi namespace 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, addrinfoex3 didefinisikan untuk addrinfoex3W, versi Unicode dari struktur ini. Parameter string didefinisikan ke jenis data PWSTR dan struktur addrinfoex3W digunakan.

Ketika UNICODE atau _UNICODE tidak ditentukan, addrinfoex3 didefinisikan untuk addrinfoex3A, versi ANSI dari struktur ini. Parameter string adalah jenis data char * dan struktur addrinfoex3A digunakan.

Setelah panggilan berhasil ke GetAddrInfoEx, daftar tertaut struktur addrinfoex3 dikembalikan dalam parameter ppResult yang diteruskan ke fungsi GetAddrInfoEx . Daftar dapat diproses dengan mengikuti penunjuk yang disediakan di anggota ai_next dari setiap struktur addrinfoex3 yang dikembalikan hingga penunjuk NULL ditemukan. Dalam setiap struktur addrinfoex3 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 addrinfoex3 yang dikembalikan menunjuk ke struktur alamat soket yang diisi, yang panjangnya ditentukan dalam anggota ai_addrlen .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [khusus aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Header	ws2def.h

Lihat juga

Bagikan melalui