Struktur WSAMSG (ws2def.h)

Artikel
08/28/2023

Struktur WSAMSG digunakan dengan fungsi LPFN_WSARECVMSG (WSARecvMsg) dan WSASendMsg untuk menyimpan alamat dan informasi kontrol opsional tentang soket yang terhubung dan tidak terhubung serta array buffer yang digunakan untuk menyimpan data pesan.

Sintaks

typedef struct _WSAMSG {
  LPSOCKADDR name;
  INT        namelen;
  LPWSABUF   lpBuffers;
#if ...
  ULONG      dwBufferCount;
#else
  DWORD      dwBufferCount;
#endif
  WSABUF     Control;
#if ...
  ULONG      dwFlags;
#else
  DWORD      dwFlags;
#endif
} WSAMSG, *PWSAMSG, *LPWSAMSG;

Anggota

name

Jenis: LPSOCKADDR

Penunjuk ke struktur SOCKET_ADDRESS yang menyimpan informasi tentang alamat jarak jauh. Digunakan hanya dengan soket yang tidak terhubung.

namelen

Jenis: INT

Panjang, dalam byte, dari struktur SOCKET_ADDRESS menunjuk ke anggota pAddr . Digunakan hanya dengan soket yang tidak terhubung.

lpBuffers

Jenis: LPWSABUF

Array struktur WSABUF yang digunakan untuk menerima data pesan. Kemampuan anggota lpBuffers untuk berisi beberapa buffer memungkinkan penggunaan I/O sebar/kumpulkan.

dwBufferCount

Jenis: DWORD

Jumlah buffer yang menunjuk ke anggota lpBuffers .

Control

Jenis: WSABUF

Struktur jenis WSABUF yang digunakan untuk menentukan data kontrol opsional. Lihat Keterangan.

dwFlags

Jenis: DWORD

Satu atau beberapa bendera kontrol, ditentukan sebagai LOGIS ATAU nilai. Nilai yang mungkin untuk anggota dwFlags pada input didefinisikan dalam file header Winsock2.h. Nilai yang mungkin untuk anggota dwFlags pada output ditentukan dalam file header Ws2def.h yang secara otomatis disertakan oleh file header Winsock2.h.

Bendera pada input	Makna
MSG_PEEK	Intip pada data masuk. Data disalin ke dalam buffer, tetapi tidak dihapus dari antrean input. Bendera ini hanya berlaku untuk soket yang tidak tumpang tindih.

Bendera dikembalikan	Makna
MSG_BCAST	Datagram diterima sebagai siaran lapisan tautan atau dengan alamat IP tujuan yang merupakan alamat siaran.
MSG_MCAST	Datagram diterima dengan alamat IP tujuan yang merupakan alamat multicast.
MSG_TRUNC	Datagram dipotong. Lebih banyak data yang ada daripada ruang yang dialokasikan proses.
MSG_CTRUNC	Data kontrol (tambahan) terpotong. Data kontrol lebih banyak ada daripada ruang yang dialokasikan proses.

Keterangan

Dalam Microsoft Windows Software Development Kit (SDK), versi struktur ini untuk digunakan pada Windows Vista didefinisikan dengan jenis data untuk anggota dwBufferCount dan dwFlags sebagai ULONG. Saat mengkompilasi aplikasi jika platform target adalah Windows Vista dan yang lebih baru (NTDDI_VERSION >= NTDDI_LONGHORN, _WIN32_WINNT >= 0x0600, atau WINVER >= 0x0600), jenis data untuk anggota dwBufferCount dan dwFlags adalah ULONG.

Windows Server 2003 dan Windows XP: Saat mengkompilasi aplikasi, jenis data untuk anggota dwBufferCount dan dwFlags adalah DWORD.

Pada Windows SDK yang dirilis untuk Windows Vista dan yang lebih baru, struktur WSAMSG 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 datagram atau data kontrol dipotong selama transmisi, fungsi yang digunakan terkait dengan struktur WSAMSG mengembalikan SOCKET_ERROR dan panggilan ke fungsi WSAGetLastError mengembalikan WSAEMSGSIZE. Terserah aplikasi untuk menentukan apa yang dipotong dengan memeriksa bendera MSG_TRUNC dan/atau MSG_CTRUNC.

Penggunaan anggota kontrol

Tabel berikut ini meringkas berbagai penggunaan data kontrol yang tersedia untuk digunakan dalam anggota Kontrol untuk IPv4 dan IPv6.

Protokol	cmsg_level	cmsg_type	Deskripsi
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	Menerima antarmuka kedatangan IPv4 asli tempat paket diterima untuk soket datagram. Data kontrol ini digunakan oleh firewall ketika terowongan Teredo, 6to4, atau ISATAP digunakan untuk traversal NAT IPv4. Anggota cmsg_data[] dalam struktur WSAMSG adalah ULONG yang berisi IF_INDEX yang ditentukan dalam file header Ifdef.h. Untuk informasi selengkapnya, lihat Opsi Soket IPPROTO_IP untuk opsi soket IP_ORIGINAL_ARRIVAL_IF. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: cmsg_type IP_ORIGINAL_ARRIVAL_IF tidak didukung.
IPv4	IPPROTO_IP	IP_PKTINFO	Menentukan/menerima informasi paket untuk soket IPv4. Untuk informasi selengkapnya, lihat opsi soket IP_PKTINFO .
IPv4	IPPROTO_IP	IP_ECN	Menentukan/menerima titik kode ECN di bidang header IPv4 Jenis Layanan (TOS). Untuk informasi selengkapnya, lihat WSASetRecvIPEcn.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	Menentukan/menerima opsi tujuan.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	Menentukan/menerima batas hop. Untuk informasi selengkapnya, lihat Opsi Soket IPPROTO_IPV6 untuk opsi soket IPV6_HOPLIMIT.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	Menentukan/menerima opsi hop-by-hop.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	Menentukan alamat lompatan berikutnya.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	Menentukan/menerima informasi paket untuk soket IPv6. Untuk informasi selengkapnya, lihat opsi soket IPV6_PKTINFO .
IPv6	IPPROTO_IPV6	IPV6_RTHDR	Menentukan/menerima header perutean.
IPv6	IPPROTO_IPV6	IPV6_ECN	Menentukan/menerima titik kode ECN di bidang header Traffic Class IPv6. Untuk informasi selengkapnya, lihat WSASetRecvIPEcn.

Data kontrol terdiri dari satu atau beberapa objek data kontrol, masing-masing dimulai dengan struktur WSACMSGHDR , didefinisikan sebagai berikut.

struct wsacmsghdr {
  UINT        cmsg_len;
  INT         cmsg_level;
  INT         cmsg_type;
  /* followed by UCHAR cmsg_data[] */
} WSACMSGHDR;

Catatan Transportasi, bukan aplikasi, mengisi informasi header dalam struktur WSACMSGHDR . Aplikasi ini hanya mengatur opsi soket yang diperlukan dan menyediakan ukuran buffer yang memadai.

Anggota struktur WSACMSGHDR adalah sebagai berikut:

Istilah	Deskripsi
cmsg_len	Jumlah byte data mulai dari awal WSACMSGHDR hingga akhir data (tidak termasuk byte padding yang mungkin mengikuti data).
cmsg_level	Protokol yang berasal dari informasi kontrol.
cmsg_type	Jenis informasi kontrol khusus protokol.

Makro berikut digunakan untuk menavigasi objek data:


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

Mengembalikan penunjuk ke objek data kontrol pertama. Mengembalikan penunjuk NULL jika tidak ada data kontrol dalam struktur WSAMSG , seperti ketika anggota Kontrol adalah penunjuk NULL .


#define LPCMSGHDR *WSA_CMSG_NXTHDR(LPWSAMSG msg, LPWSACMSGHDR cmsg);

Mengembalikan penunjuk ke objek data kontrol berikutnya, atau NULL jika tidak ada objek data lagi. Jika parameter pcmsgadalah NULL, penunjuk ke objek data kontrol pertama dikembalikan.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

Mengembalikan penunjuk ke byte pertama data (disebut sebagai anggota cmsg_data , meskipun tidak didefinisikan dalam struktur).


#define UINT WSA_CMSG_SPACE(UINT length);

Mengembalikan ukuran total objek data kontrol, mengingat jumlah data. Digunakan untuk mengalokasikan jumlah ruang buffer yang benar. Termasuk padding perataan.


#define UINT WSA_CMSG_LEN(UINT length);

Mengembalikan nilai dalam cmsg_len mengingat jumlah data. Termasuk padding perataan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Header	ws2def.h (termasuk Winsock2.h)