Struktur WSAMSG (ws2def.h)
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 |
---|---|
|
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. |
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;
Anggota struktur WSACMSGHDR adalah sebagai berikut:
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) |