Fungsi WSASendMsg (winsock2.h)

Artikel
07/16/2024

Fungsi WSASendMsg mengirim data dan informasi kontrol opsional dari soket yang terhubung dan tidak terhubung.

Note Fungsi ini adalah ekstensi khusus Microsoft untuk spesifikasi Windows Sockets.

Sintaksis

int WSAAPI WSASendMsg(
  [in]  SOCKET                             Handle,
  [in]  LPWSAMSG                           lpMsg,
  [in]  DWORD                              dwFlags,
  [out] LPDWORD                            lpNumberOfBytesSent,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameter

[in] Handle

Deskriptor yang mengidentifikasi soket.

[in] lpMsg

Struktur WSAMSG menyimpan struktur msghdr Posix.1g.

[in] dwFlags

Bendera yang digunakan untuk memodifikasi perilaku panggilan fungsi WSASendMsg . Untuk informasi selengkapnya, lihat Menggunakan dwFlags di bagian Keterangan.

[out] lpNumberOfBytesSent

Penunjuk ke nomor, dalam byte, yang dikirim oleh panggilan ini jika operasi I/O segera selesai.

Gunakan NULL untuk parameter ini jika parameter lpOverlapped tidak NULL untuk menghindari hasil yang berpotensi salah. Parameter ini dapat NULL hanya jika parameter lpOverlapped tidak NULL.

[in] lpOverlapped

Penunjuk ke struktur WSAOVERLAPPED . Diabaikan untuk soket yang tidak tumpang tindih.

[in] lpCompletionRoutine

Jenis: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Penunjuk ke rutinitas penyelesaian yang dipanggil saat operasi pengiriman selesai. Diabaikan untuk soket yang tidak tumpang tindih.

Mengembalikan nilai

Mengembalikan nol ketika berhasil dan penyelesaian segera terjadi. Ketika nol dikembalikan, rutinitas penyelesaian yang ditentukan dipanggil saat utas panggilan dalam status dapat diingat.

Nilai pengembalian SOCKET_ERROR, dan panggilan berikutnya ke WSAGetLastError yang mengembalikan WSA_IO_PENDING, menunjukkan operasi tumpang tindih telah berhasil dimulai; penyelesaian kemudian ditunjukkan melalui cara lain, seperti melalui peristiwa atau port penyelesaian.

Setelah gagal, mengembalikan SOCKET_ERROR dan panggilan berikutnya ke WSAGetLastError mengembalikan nilai selain WSA_IO_PENDING. Tabel berikut mencantumkan kode kesalahan.

Kode kesalahan	Arti
WSAEACCES	Alamat yang diminta adalah alamat siaran, tetapi bendera yang sesuai tidak ditetapkan.
WSAECONNRESET	Untuk soket datagram UDP, kesalahan ini akan menunjukkan bahwa operasi pengiriman sebelumnya menghasilkan pesan "Port Unreachable" ICMP.
WSAEFAULT	lpMsg, lpNumberOfBytesSent, lpOverlapped, atau parameter lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian yang valid dari ruang alamat pengguna. Kesalahan ini juga dikembalikan jika nama anggota struktur WSAMSG yang ditujukkan oleh parameter lpMsg adalah penunjuk NULL dan namelen anggota struktur WSAMSG tidak diatur ke nol. Kesalahan ini juga dikembalikan jika Control.buf anggota struktur WSAMSG yang ditunjukkan oleh parameter lpMsg adalah penunjuk NULL dan Control.len anggota WSAMSG struktur tidak diatur ke nol.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINTR	Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall.
WSAEINVAL	Soket belum terikat denganikatan , atau soket tidak dibuat dengan bendera tumpang tindih.
WSAEMSGSIZE	Soket berorientasi pesan, dan pesan lebih besar dari maksimum yang didukung oleh transportasi yang mendasar.
WSAENETDOWN	Subsistem jaringan gagal.
WSAENETRESET	Untuk soket datagram, kesalahan ini menunjukkan bahwa waktu hidup telah kedaluwarsa.
WSAENETUNREACH	Jaringan tidak dapat dijangkau.
WSAENOBUFS	Penyedia Soket Windows melaporkan kebuntuan buffer.
WSAENOTCONN	Soket tidak tersambung.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Operasi soket tidak didukung. Kesalahan ini dikembalikan jika dwFlags anggota struktur WSAMSG yang ditujukkan oleh parameter lpMsg menyertakan bendera kontrol apa pun yang tidak valid untuk WSASendMsg.
WSAESHUTDOWN	Soket telah dimatikan; tidak dimungkinkan untuk memanggil fungsi WSASendMsg pada soket setelah pematian dipanggil dengan bagaimana diatur ke SD_SEND atau SD_BOTH.
WSAETIMEDOUT	Waktu soket habis. Kesalahan ini dikembalikan jika soket memiliki batas waktu tunggu yang ditentukan menggunakan opsi soket SO_SNDTIMEO dan batas waktu terlampaui.
WSAEWOULDBLOCK	Soket yang tumpang tindih: Ada terlalu banyak permintaan I/O yang tumpang tindih. Soket yang tidak tumpang tindih: Soket ditandai sebagai nonblocking dan operasi pengiriman tidak dapat segera diselesaikan.
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSA_IO_PENDING	Operasi tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED	Operasi yang tumpang tindih telah dibatalkan karena penutupan soket atau karena eksekusi perintah SIO_FLUSH di WSAIoctl.

Komentar

Fungsi WSASendMsg dapat digunakan sebagai pengganti fungsi WSASend dan WSASendTo. Fungsi WSASendMsg hanya dapat digunakan dengan datagram dan soket mentah. Deskriptor soket dalam parameter harus dibuka dengan jenis soket yang diatur ke SOCK_DGRAM atau SOCK_RAW.

Parameter dwFlags hanya dapat berisi kombinasi bendera kontrol berikut: MSG_DONTROUTE, MSG_PARTIAL, dan MSG_OOB. dwFlags anggota struktur WSAMSG yang ditunjukkan oleh parameter lpMsg diabaikan pada input dan tidak digunakan pada output.

Catatan Penunjuk fungsi untuk fungsi WSASendMsg harus diperoleh pada waktu proses dengan melakukan panggilan ke fungsi WSAIoctl dengan opcode SIO_GET_EXTENSION_FUNCTION_POINTER yang ditentukan. Buffer input yang diteruskan ke fungsi WSAIoctl harus berisi WSAID_WSASENDMSG, pengidentifikasi unik global (GUID) yang nilainya mengidentifikasi fungsi ekstensi WSASendMsg . Setelah berhasil, output yang dikembalikan oleh fungsi WSAIoctl berisi penunjuk ke fungsi WSASendMsg . GUID WSAID_WSASENDMSG didefinisikan dalam file header Mswsock.h.

Soket yang tumpang tindih dibuat dengan panggilan fungsi WSASocket yang memiliki set bendera WSA_FLAG_OVERLAPPED. Untuk soket yang tumpang tindih, mengirim informasi menggunakan I/O yang tumpang tindih kecuali lpOverlapped dan lpCompletionRoutineNULL; ketika lpOverlapped dan lpCompletionRoutineNULL, soket diperlakukan sebagai soket yang tidak tumpang tindih. Indikasi penyelesaian terjadi dengan soket yang tumpang tindih; setelah buffer atau buffer dikonsumsi oleh transportasi, rutinitas penyelesaian dipicu atau objek peristiwa diatur. Jika operasi tidak segera selesai, status penyelesaian akhir diambil melalui rutinitas penyelesaian atau dengan memanggil fungsi WSAGetOverlappedResult.

Untuk soket yang tidak tumpang tindih, parameter lpOverlapped dan lpCompletionRoutine diabaikan dan WSASendMsg mengadopsi semantik pemblokiran yang sama dengan fungsi pengiriman : data disalin dari buffer atau buffer ke dalam buffer transportasi. Jika soket tidak diblokir dan berorientasi aliran, dan ruang yang tidak mencukup dalam buffer transportasi, WSASendMsg kembali hanya dengan bagian dari buffer aplikasi yang telah dikonsumsi. Sebaliknya, situasi buffer ini pada soket pemblokiran menghasilkan WSASendMsg pemblokiran sampai semua konten buffer aplikasi telah digunakan.

Jika fungsi ini selesai dengan cara yang tumpang tindih, penyedia layanan Winsock bertanggung jawab untuk menangkap struktur WSABUF ini sebelum kembali dari panggilan ini. Ini memungkinkan aplikasi untuk membangun array WSABUF berbasis tumpukan yang ditunjukkan oleh lpBuffers anggota struktur WSAMSG yang ditunjukkan oleh parameter lpMsg .

Untuk soket berorientasi pesan, perhatian harus dilakukan untuk tidak melebihi ukuran pesan maksimum penyedia yang mendasar, yang dapat diperoleh dengan mendapatkan nilai opsi soket SO_MAX_MSG_SIZE. Jika data terlalu panjang untuk diteruskan secara atomik melalui protokol yang mendasar, kesalahan WSAEMSGSIZE dikembalikan dan tidak ada data yang dikirimkan.

Pada soket IPv4 jenis SOCK_DGRAM atau SOCK_RAW, aplikasi dapat menentukan alamat sumber IP lokal untuk digunakan untuk mengirim dengan fungsi WSASendMsg . Salah satu objek data kontrol yang diteruskan dalam struktur WSAMSG ke fungsi WSASendMsg mungkin berisi struktur in_pktinfo yang digunakan untuk menentukan alamat sumber IPv4 lokal yang digunakan untuk mengirim.

Pada soket IPv6 jenis SOCK_DGRAM atau SOCK_RAW, aplikasi dapat menentukan alamat sumber IP lokal untuk digunakan untuk mengirim dengan fungsi WSASendMsg . Salah satu objek data kontrol yang diteruskan dalam struktur WSAMSG ke fungsi WSASendMsg mungkin berisi struktur in6_pktinfo yang digunakan untuk menentukan alamat sumber IPv6 lokal yang digunakan untuk mengirim.

Untuk soket tumpukan ganda saat mengirim datagram dengan fungsi WSASendMsg dan aplikasi ingin menentukan alamat sumber IP lokal tertentu yang akan digunakan, metode untuk menangani ini tergantung pada alamat IP tujuan. Saat mengirim ke alamat tujuan IPv4 atau alamat tujuan IPv4 yang dipetakan IPv4, salah satu objek data kontrol yang diteruskan dalam struktur WSAMSG yang ditunjukkan oleh parameter lpMsg harus berisi struktur in_pktinfo yang berisi alamat sumber IPv4 lokal yang akan digunakan untuk pengiriman. Saat mengirim ke alamat tujuan IPv6 yang bukan alamat IPv6 yang dipetakan IPv4, salah satu objek data kontrol yang diteruskan dalam struktur WSAMSG yang ditunjukkan oleh parameter lpMsg harus berisi struktur in6_pktinfo yang berisi alamat sumber IPv6 lokal untuk digunakan untuk mengirim.

Catatan Opsi soket SO_SNDTIMEO hanya berlaku untuk memblokir soket.

Catatan Keberhasilan penyelesaian WSASendMsg tidak menunjukkan bahwa data berhasil dikirimkan.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti WSASendMsg dengan parameter lpOverlapped diatur ke NULL, Winsock mungkin perlu menunggu peristiwa jaringan sebelum panggilan dapat selesai. Winsock melakukan penantian yang dapat diperingatkan dalam situasi ini, yang dapat terganggu oleh panggilan prosedur asinkron (APC) yang dijadwalkan pada utas yang sama. Mengeluarkan panggilan Winsock pemblokiran lain di dalam APC yang mengganggu panggilan Winsock pemblokiran yang sedang berlangsung pada utas yang sama akan menyebabkan perilaku yang tidak ditentukan, dan tidak boleh dicoba oleh klien Winsock.

dwFlags

Parameter input dwFlags dapat digunakan untuk memengaruhi perilaku pemanggilan fungsi di luar opsi yang ditentukan untuk soket terkait. Artinya, semantik fungsi ini ditentukan oleh opsi soket dan parameter dwFlags. Yang terakhir dibangun dengan menggunakan operator BITWISE OR dengan salah satu nilai berikut.

Nilai	Arti
MSG_DONTROUTE	Menentukan bahwa data tidak boleh tunduk pada perutean. Penyedia layanan Windows Sockets dapat memilih untuk mengabaikan bendera ini.
MSG_PARTIAL	Menentukan bahwa lpMsg->lpBuffers hanya berisi pesan parsial. Perhatikan bahwa kode kesalahan WSAEOPNOTSUPP akan dikembalikan oleh transportasi yang tidak mendukung transmisi pesan parsial.

Nilai yang mungkin untuk parameter dwFlags ditentukan dalam file header Winsock2.h.

Pada output, dwFlags anggota struktur WSAMSG yang ditujukkan oleh parameter lpMsg tidak digunakan.

I/O Soket Tumpang Tindih

Jika operasi yang tumpang tindih segera selesai, WSASendMsg mengembalikan nilai nol dan parameter lpNumberOfBytesSent diperbarui dengan jumlah byte yang dikirim. Jika operasi yang tumpang tindih berhasil dimulai dan akan selesai nanti, WSASendMsg mengembalikan SOCKET_ERROR dan menunjukkan kode kesalahan WSA_IO_PENDING. Dalam hal ini, lpNumberOfBytesSent tidak diperbarui. Ketika operasi yang tumpang tindih selesai, jumlah data yang ditransfer ditunjukkan baik melalui parameter cbTransferred dalam rutinitas penyelesaian (jika ditentukan) atau melalui parameter lpcbTransfer di WSAGetOverlappedResult.

Catatan Semua I/O yang dimulai oleh utas tertentu dibatalkan saat utas tersebut keluar. Untuk soket yang tumpang tindih, operasi asinkron yang tertunda dapat gagal jika utas ditutup sebelum operasi selesai. Lihat ExitThread untuk informasi selengkapnya.

Fungsi WSASendMsg yang menggunakan I/O yang tumpang tindih dapat dipanggil dari dalam rutinitas penyelesaian WSARecv, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg), WSASend, WSASendMsg, atau fungsi WSASendTo. Ini memungkinkan transmisi data sensitif waktu terjadi sepenuhnya dalam konteks preemptive.

Parameter lpOverlapped harus valid selama durasi operasi yang tumpang tindih. Jika beberapa operasi I/O beredar secara bersamaan, masing-masing harus mereferensikan struktur WSAOVERLAPPED yang terpisah.

Jika parameter lpCompletionRoutine NULL, parameter hEvent lpOverlapped diberi sinyal ketika operasi yang tumpang tindih selesai jika berisi handel objek peristiwa yang valid. Aplikasi dapat menggunakan WSAWaitForMultipleEvents atau WSAGetOverlappedResult untuk menunggu atau melakukan polling pada objek peristiwa.

Jika lpCompletionRoutine tidak NULL, parameter hEvent diabaikan dan dapat digunakan oleh aplikasi untuk meneruskan informasi konteks ke rutinitas penyelesaian. Pemanggil yang melewati non-NULLlpCompletionRoutine dan kemudian memanggil WSAGetOverlappedResult untuk tumpang tindih yang sama Permintaan I/O mungkin tidak mengatur parameter fWait untuk pemanggilan WSAGetOverlappedResult ke TRUE. Dalam hal ini, penggunaan parameter hEvent tidak terdefinisi, dan mencoba menunggu parameter hEvent akan menghasilkan hasil yang tidak dapat diprediksi.

Rutinitas penyelesaian mengikuti aturan yang sama seperti yang ditetapkan untuk rutinitas penyelesaian I/O file Windows. Rutinitas penyelesaian tidak akan dipanggil sampai utas dalam status tunggu yang dapat diperingatkan, misalnya, dengan WSAWaitForMultipleEvents dipanggil dengan parameter fAlertable diatur ke TRUE.

Penyedia transportasi memungkinkan aplikasi untuk memanggil operasi kirim dan terima dari dalam konteks rutinitas penyelesaian I/O soket, dan menjamin bahwa, untuk soket tertentu, rutinitas penyelesaian I/O tidak akan ditumpuk. Ini memungkinkan transmisi data sensitif waktu terjadi sepenuhnya dalam konteks preemptive.

Prototipe rutinitas penyelesaian adalah sebagai berikut.


void CALLBACK CompletionRoutine(
  IN DWORD dwError,
  IN DWORD cbTransferred,
  IN LPWSAOVERLAPPED lpOverlapped,
  IN DWORD dwFlags
);

Fungsi CompletionRoutine adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi atau yang ditentukan pustaka. Parameter dwError menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh parameter lpOverlapped. Parameter cbTransferred menunjukkan jumlah byte yang dikirim. Saat ini tidak ada nilai bendera yang ditentukan dan parameter dwFlags akan menjadi nol. Fungsi CompletionRoutine tidak mengembalikan nilai.

Mengembalikan dari fungsi ini memungkinkan pemanggilan rutinitas penyelesaian lain yang tertunda untuk soket. Semua rutinitas penyelesaian tunggu dipanggil sebelum penantian utas yang dapat diperingatkan dipenuhi dengan kode pengembalian WSA_IO_COMPLETION. Rutinitas penyelesaian dapat dipanggil dalam urutan apa pun, tidak harus dalam urutan yang sama operasi yang tumpang tindih selesai. Namun, buffer yang diposting dijamin akan dikirim dalam urutan yang sama yang ditentukan.

windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store pada Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 8.1, Windows Vista [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	winsock2.h (termasuk Mswsock.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll