Fungsi WSASendMsg (winsock2.h)

Artikel
03/08/2023

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

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

Sintaks

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 yang 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 bukan NULL untuk menghindari hasil yang berpotensi salah. Parameter ini dapat berupa NULL hanya jika parameter lpOverlapped bukan NULL.

[in] lpOverlapped

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

[in] lpCompletionRoutine

Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_

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

Mengembalikan nilai

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

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

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

Kode kesalahan	Makna
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 ICMP "Port Unreachable".
WSAEFAULT	Parameter lpMsg, lpNumberOfBytesSent, lpOverlapped, atau lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid. Kesalahan ini juga dikembalikan jika anggota nama struktur WSAMSG yang diacu oleh parameter lpMsg adalah pointer NULL dan anggota namelen struktur WSAMSG tidak diatur ke nol. Kesalahan ini juga dikembalikan jika anggota Control.buf dari struktur WSAMSG yang diarahkan oleh parameter lpMsg adalah pointer NULL dan anggota Control.len dari struktur WSAMSG tidak diatur ke nol.
WSAEINPROGRESS	Panggilan Windows Sockets 1.1 yang diblokir sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINTR	Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall.
WSAEINVAL	Soket belum terikat dengan ikatan, atau soket tidak dibuat dengan bendera tumpang tindih.
WSAEMSGSIZE	Soket berorientasi pada 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 anggota dwFlags dari struktur WSAMSG yang diarahkan 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 dipanggil dengan cara 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 yang 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.

Keterangan

Fungsi WSASendMsg dapat digunakan sebagai pengganti fungsi WSASend dan WSASendTo . Fungsi WSASendMsg hanya dapat digunakan dengan datagram dan soket mentah. Deskriptor soket dalam parameter s 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. Anggota dwFlags dari struktur WSAMSG yang diarahkan oleh parameter lpMsg diabaikan pada input dan tidak digunakan pada output.

Catatan Penunjuk fungsi untuk fungsi WSASendMsg harus diperoleh pada durasi 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 pointer 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 lpCompletionRoutine adalah NULL; ketika lpOverlapped dan lpCompletionRoutine adalah NULL, 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 kirim : data disalin dari buffer atau buffer ke dalam buffer transportasi. Jika soket tidak diblokir dan dialirkan berorientasi, dan ruang di buffer transportasi tidak memadai, WSASendMsg hanya mengembalikan bagian dari buffer aplikasi yang telah dikonsumsi. Sebaliknya, situasi buffer ini pada soket pemblokiran menghasilkan pemblokiran WSASendMsg sampai semua konten buffer aplikasi telah dikonsumsi.

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 ditujukkan oleh anggota lpBuffers dari struktur WSAMSG yang ditujukkan oleh parameter lpMsg .

Untuk soket berorientasi pesan, perawatan harus dilakukan agar 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 akan digunakan untuk pengiriman.

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 akan digunakan untuk pengiriman.

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 IPv6 yang dipetakan IPv4, salah satu objek data kontrol yang diteruskan dalam struktur WSAMSG yang diarahkan oleh parameter lpMsg harus berisi struktur in_pktinfo yang berisi alamat sumber IPv4 lokal untuk 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 diarahkan oleh parameter lpMsg harus berisi struktur in6_pktinfo yang berisi alamat sumber IPv6 lokal untuk digunakan untuk pengiriman.

Catatan Opsi soket SO_SNDTIMEO hanya berlaku untuk soket pemblokiran.

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 terdefinisi, 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	Makna
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 sebagian pesan. Perhatikan bahwa kode kesalahan WSAEOPNOTSUPP akan dikembalikan oleh transportasi yang tidak mendukung transmisi pesan parsial.

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

Pada output, anggota dwFlags dari struktur WSAMSG yang diarahkan 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 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 ketika 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 menggunakan I/O yang tumpang tindih dapat dipanggil dari dalam rutinitas penyelesaian fungsi sebelumnya, WSARecv, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg), WSASend, WSASendMsg, atau 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 secara bersamaan luar biasa, masing-masing harus mereferensikan struktur WSAOVERLAPPED terpisah.

Jika parameter lpCompletionRoutine adalah NULL, parameter hEventdari 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 bukan NULL, parameter hEvent diabaikan dan dapat digunakan oleh aplikasi untuk meneruskan informasi konteks ke rutinitas penyelesaian. Penelepon yang melewati lpCompletionRoutinenon-NULL dan kemudian memanggil WSAGetOverlappedResult untuk permintaan I/O yang tumpang tindih yang sama 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 berada 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 menunggu dipanggil sebelum penantian utas yang dapat diperingatkan terpenuhi 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 dengan yang ditentukan.

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

Persyaratan

Persyaratan	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]
Target Platform	Windows
Header	winsock2.h (termasuk Mswsock.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll