Fungsi panggilan balik LPWSPSEND (ws2spi.h)
Fungsi LPWSPSend mengirim data pada soket yang terhubung.
Sintaks
LPWSPSEND Lpwspsend;
int Lpwspsend(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Parameter
[in] s
Deskriptor yang mengidentifikasi soket yang terhubung.
[in] lpBuffers
Penunjuk ke array struktur WSABUF . Setiap struktur WSABUF berisi penunjuk ke buffer dan panjang buffer, dalam byte. Untuk aplikasi Winsock, setelah fungsi LPWSPSend dipanggil, sistem memiliki buffer ini dan aplikasi mungkin tidak mengaksesnya. Buffer data yang direferensikan di setiap struktur WSABUF dimiliki oleh sistem dan aplikasi Anda mungkin tidak mengaksesnya selama masa panggilan.
[in] dwBufferCount
Jumlah struktur WSABUF dalam array lpBuffers .
[out] lpNumberOfBytesSent
Penunjuk ke jumlah byte yang dikirim oleh panggilan ini.
[in] dwFlags
Sekumpulan bendera yang menentukan cara panggilan dilakukan.
[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 telah selesai (diabaikan untuk soket yang tidak tumpang tindih).
[in] lpThreadId
Penunjuk ke struktur WSATHREADID yang akan digunakan oleh penyedia dalam panggilan berikutnya ke WPUQueueApc. Penyedia harus menyimpan struktur WSATHREADID yang direferensikan (bukan penunjuk ke yang sama) sampai setelah fungsi WPUQueueApc kembali.
[out] lpErrno
Penunjuk ke kode kesalahan.
Mengembalikan nilai
Jika tidak ada kesalahan yang terjadi dan operasi pengiriman telah segera selesai, LPWSPSend mengembalikan nol. Perhatikan bahwa dalam hal ini rutinitas penyelesaian, jika ditentukan, akan telah diantrekan. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu tersedia di lpErrno. Kode kesalahan WSA_IO_PENDING menunjukkan bahwa operasi yang tumpang tindih telah berhasil dimulai dan penyelesaian tersebut akan ditunjukkan di lain waktu. Kode kesalahan lainnya menunjukkan bahwa tidak ada operasi yang tumpang tindih yang dimulai dan tidak ada indikasi penyelesaian yang akan terjadi.
| Kode Kesalahan | Makna |
|---|---|
| Subsistem jaringan gagal. | |
| Alamat yang diminta adalah alamat siaran, tetapi bendera yang sesuai tidak ditetapkan. | |
| Pemblokiran panggilan Windows Sockets sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik. | |
| Parameter lpBuffers tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid. | |
| Koneksi telah terputus karena penyetelan ulang host jarak jauh. | |
| Koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung. | |
| Soket tidak terhubung. | |
| Deskriptor bukan soket. | |
| MSG_OOB ditentukan, tetapi soket tidak bergaya aliran seperti jenis SOCK_STREAM, data OOB tidak didukung di domain komunikasi yang terkait dengan soket ini, MSG_PARTIAL tidak didukung, atau soket tidak langsung dan hanya mendukung operasi penerimaan. | |
| Soket telah dimatikan; tidak dimungkinkan untuk LPWSPSend pada soket setelah LPWSPShutdown dipanggil dengan cara diatur ke SD_SEND atau SD_BOTH. | |
| **Windows NT:** Soket yang tumpang tindih: Ada terlalu banyak permintaan I/O yang tumpang tindih yang luar biasa. Soket yang tidak tumpang tindih: Soket ditandai sebagai nonblocking dan operasi pengiriman tidak dapat segera diselesaikan. | |
| Soket berorientasi pesan, dan pesan lebih besar dari maksimum yang didukung oleh transportasi yang mendasar. | |
| Soket belum terikat dengan LPWSPBind, atau soket tidak dibuat dengan bendera tumpang tindih. | |
| Sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya. | |
| Sirkuit virtual direset oleh sisi jarak jauh. | |
| Operasi yang tumpang tindih telah dibatalkan karena penutupan soket, atau eksekusi perintah SIO_FLUSH di LPWSPIoctl. |
Keterangan
Fungsi LPWSPSend digunakan untuk menulis data keluar dari satu atau beberapa buffer pada soket berorientasi koneksi yang ditentukan oleh s. Namun, ini juga dapat digunakan pada soket tanpa koneksi yang memiliki alamat serekan default yang ditetapkan yang ditetapkan melalui fungsi LPWSPConnect .
Untuk soket yang tumpang tindih (dibuat menggunakan LPWSPSocket dengan bendera WSA_FLAG_OVERLAPPED) ini akan terjadi menggunakan I/O yang tumpang tindih, kecuali jika lpOverlapped dan lpCompletionRoutine null dalam hal ini soket diperlakukan sebagai soket yang tidak tumpang tindih. Indikasi penyelesaian akan terjadi (pemanggilan rutinitas penyelesaian atau pengaturan objek peristiwa) ketika buffer yang disediakan telah dikonsumsi oleh transportasi. Jika operasi tidak segera selesai, status penyelesaian akhir diambil melalui rutinitas penyelesaian atau LPWSPGetOverlappedResult.
Untuk soket yang tidak tumpang tindih, parameter lpOverlapped, lpCompletionRoutine, dan lpThreadId diabaikan dan LPWSPSend mengadopsi semantik sinkron reguler. Data disalin dari buffer yang disediakan ke dalam buffer transportasi. Jika soket tidak memblokir dan berorientasi aliran, dan tidak ada ruang yang cukup dalam buffer transportasi, LPWSPSend akan kembali dengan hanya sebagian dari buffer yang disediakan yang telah dikonsumsi. Mengingat situasi buffer yang sama dan soket pemblokiran, LPWSPSend akan memblokir sampai semua konten buffer yang disediakan telah dikonsumsi.
Array struktur WSABUF yang diacu oleh parameter lpBuffers bersifat sementara. Jika operasi ini selesai dengan cara yang tumpang tindih, penyedia layanan bertanggung jawab untuk menangkap struktur WSABUF ini sebelum kembali dari panggilan ini. Ini memungkinkan aplikasi untuk membangun array WSABUF berbasis tumpukan.
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.
Perhatikan bahwa keberhasilan penyelesaian LPWSPSend tidak menunjukkan bahwa data berhasil dikirimkan.
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_OOB | Mengirim data OOB (soket gaya aliran seperti hanya SOCK_STREAM). |
| MSG_PARTIAL | Menentukan bahwa lpBuffers hanya berisi pesan parsial. Perhatikan bahwa kode kesalahan WSAEOPNOTSUPP akan dikembalikan untuk pesan yang tidak mendukung transmisi pesan parsial. |
Jika operasi yang tumpang tindih segera selesai, LPWSPSend mengembalikan nilai nol dan parameter lpNumberOfBytesSent diperbarui dengan jumlah byte yang dikirim. Jika operasi yang tumpang tindih berhasil dimulai dan akan selesai nanti, LPWSPSend mengembalikan SOCKET_ERROR dan menunjukkan kode kesalahan WSA_IO_PENDING. Dalam hal ini, lpNumberOfBytesSent tidak diperbarui. Ketika operasi yang tumpang tindih menyelesaikan jumlah data yang ditransfer ditunjukkan baik melalui parameter cbTransferred dalam rutinitas penyelesaian (jika ditentukan), atau melalui parameter lpcbTransfer di LPWSPGetOverlappedResult.
Penyedia harus mengizinkan fungsi ini dipanggil dari dalam rutinitas penyelesaian fungsi LPWSPRecv, LPWSPRecvFrom, LPWSPSend , atau LPWSPSendTo sebelumnya. Namun, untuk soket tertentu, rutinitas penyelesaian I/O tidak dapat ditumpuk. 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 tumpang tindih terpisah. Struktur WSAOverlapped didefinisikan di halaman referensinya sendiri.
Jika parameter lpCompletionRoutine null, penyedia layanan memberi sinyal kepada anggota hEventdari lpOverlapped ketika operasi yang tumpang tindih selesai jika berisi handel objek peristiwa yang valid. Klien Windows Sockets SPI dapat menggunakan LPWSPGetOverlappedResult untuk menunggu atau melakukan polling pada objek peristiwa.
Jika lpCompletionRoutine tidak null, anggota hEvent diabaikan dan dapat digunakan oleh klien Windows Sockets SPI untuk meneruskan informasi konteks ke rutinitas penyelesaian. Klien yang melewati lpCompletionRoutine non-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 anggota hEvent tidak terdefinisi, dan mencoba menunggu anggota hEvent akan menghasilkan hasil yang tidak dapat diprediksi.
Penyedia layanan mengatur agar fungsi dijalankan dalam rangkaian dan konteks proses yang tepat dengan memanggil WPUQueueApc. Fungsi ini dapat dipanggil dari konteks proses dan utas apa pun, bahkan konteks yang berbeda dari utas dan proses yang digunakan untuk memulai operasi yang tumpang tindih.
Penyedia layanan mengatur agar fungsi dijalankan dalam utas yang tepat dengan memanggil WPUQueueApc. Perhatikan bahwa fungsi ini harus dipanggil saat dalam konteks proses yang sama (tetapi belum tentu utas yang sama) yang digunakan untuk memulai operasi yang tumpang tindih. Penyedia layanan bertanggung jawab untuk mengatur konteks proses ini menjadi aktif sebelum memanggil WPUQueueApc.
Fungsi WPUQueueApc mengambil sebagai parameter input penunjuk ke struktur WSATHREADID (diberikan ke penyedia melalui parameter input lpThreadId ), penunjuk ke fungsi APC yang akan dipanggil, dan nilai konteks yang kemudian diteruskan ke fungsi APC. Karena hanya satu nilai konteks yang tersedia, fungsi APC itu sendiri tidak dapat menjadi rutinitas penyelesaian yang ditentukan klien. Penyedia layanan harus menyediakan pointer ke fungsi APC sendiri yang menggunakan nilai konteks yang disediakan untuk mengakses informasi hasil yang diperlukan untuk operasi yang tumpang tindih, dan kemudian memanggil rutinitas penyelesaian yang ditentukan klien.
Prototipe untuk rutinitas penyelesaian yang disediakan klien adalah sebagai berikut.
void CALLBACK
CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine adalah tempat penampung untuk nama fungsi yang disediakan klien. dwError menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh lpOverlapped. cbTransferred menentukan jumlah byte yang dikirim. Tidak ada nilai bendera yang saat ini ditentukan dan nilai dwFlags akan menjadi nol. Fungsi ini tidak mengembalikan nilai.
Rutinitas penyelesaian dapat dipanggil dalam urutan apa pun, meskipun tidak harus dalam urutan yang sama dengan operasi yang tumpang tindih selesai. Namun, penyedia layanan menjamin kepada klien bahwa buffer yang diposting dikirim dalam urutan yang sama seperti yang disediakan.
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.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Header | ws2spi.h |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk