LPFN_TRANSMITPACKETS fungsi panggilan balik (mswsock.h)

Artikel
03/15/2023

Fungsi TransmitPackets mengirimkan data dalam memori atau data file melalui soket yang terhubung. Fungsi TransmitPackets menggunakan manajer cache sistem operasi untuk mengambil data file, mengunci memori untuk waktu minimum yang diperlukan untuk mengirimkan dan menghasilkan transmisi performa tinggi yang efisien.

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

Sintaks

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

BOOL LpfnTransmitpackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
)
{...}

Parameter

hSocket

Handel ke soket yang terhubung untuk digunakan dalam transmisi. Meskipun soket tidak perlu menjadi sirkuit berorientasi koneksi, tujuan/peer default seharusnya dibuat menggunakan fungsi connect, WSAConnect, accept, WSAAccept, AcceptEx, atau WSAJoinLeaf .

lpPacketArray

Array jenis TRANSMIT_PACKETS_ELEMENT, yang menjelaskan data yang akan dikirimkan.

nElementCount

Jumlah elemen dalam lpPacketArray.

nSendSize

Ukuran, dalam byte, dari blok data yang digunakan dalam operasi kirim . Atur nSendSize ke nol untuk membiarkan lapisan soket memilih ukuran pengiriman default.

Mengatur nSendSize ke 0xFFFFFFF memungkinkan pemanggil mengontrol ukuran dan konten setiap permintaan pengiriman , yang dicapai dengan menggunakan bendera TP_ELEMENT_EOP dalam array TRANSMIT_PACKETS_ELEMENT yang diarahkan ke parameter lpPacketArray . Kemampuan ini berguna untuk protokol pesan yang menempatkan batasan pada ukuran permintaan pengiriman individu.

lpOverlapped

Penunjuk ke struktur YANG TUMPANG TINDIH . Jika handel soket yang ditentukan dalam parameter hSocket telah dibuka sebagai tumpang tindih, gunakan parameter ini untuk mencapai operasi I/O asinkron (tumpang tindih). Handel soket dibuka sebagai tumpang tindih secara default.

dwFlags

Sekumpulan bendera yang digunakan untuk menyesuaikan pemrosesan fungsi TransmitPackets . Tabel berikut menguraikan penggunaan parameter dwFlags .

Nilai	Makna
TF_DISCONNECT	Memulai pemutusan tingkat transportasi setelah semua data file diantrekan untuk transmisi. Hanya berlaku untuk soket berorientasi koneksi. Menentukan bendera ini untuk soket yang tidak mendukung pemutusan semantik (seperti soket datagram) menghasilkan kesalahan.
TF_REUSE_SOCKET	Menyiapkan handel soket untuk digunakan kembali. Ketika fungsi TransmitPackets selesai, handel soket dapat diteruskan ke fungsi AcceptEx . Hanya berlaku saat soket dan TF_DISCONNECT berorientasi koneksi ditentukan. Catatan Pengiriman paket tingkat soket tunduk pada perilaku transportasi yang mendasar. Misalnya, soket TCP dapat tunduk pada status TIME_WAIT TCP, menyebabkan panggilan TransmitPackets tertunda.
TF_USE_DEFAULT_WORKER	Mengarahkan Winsock untuk menggunakan utas default sistem untuk memproses permintaan TransmitPackets yang panjang. Permintaan TransmitPackets panjang didefinisikan sebagai permintaan yang memerlukan lebih dari satu bacaan dari file atau cache; oleh karena itu definisi permintaan panjang tergantung pada ukuran file dan panjang paket kirim yang ditentukan. Utas default sistem dapat disesuaikan menggunakan parameterregistri\ berikut sebagai REG_DWORD:HKEY_LOCAL_MACHINE\ ParameterAFD\CurrentControlSet\Services\TransmitWorker
TF_USE_SYSTEM_THREAD	Mengarahkan Winsock untuk menggunakan utas sistem untuk memproses permintaan TransmitPackets yang panjang. Permintaan TransmitPackets panjang didefinisikan sebagai permintaan yang memerlukan lebih dari satu bacaan dari file atau cache; oleh karena itu definisi permintaan panjang tergantung pada ukuran file dan panjang paket kirim yang ditentukan.
TF_USE_KERNEL_APC	Mengarahkan Winsock untuk menggunakan kernel Asynchronous Procedure Calls (APC) alih-alih utas pekerja untuk memproses permintaan TransmitPackets yang panjang. Permintaan TransmitPackets panjang didefinisikan sebagai permintaan yang memerlukan lebih dari satu bacaan dari file atau cache; oleh karena itu definisi permintaan panjang tergantung pada ukuran file dan panjang paket kirim yang ditentukan. Lihat Keterangan untuk informasi selengkapnya.

Mengembalikan nilai

Jika fungsi TransmitPackets berhasil, nilai yang dikembalikan adalah TRUE. Jika tidak, nilai yang dikembalikan adalah FALSE. Untuk mendapatkan informasi kesalahan yang diperluas, panggil WSAGetLastError. Kode kesalahan WSA_IO_PENDING atau ERROR_IO_PENDING menunjukkan bahwa operasi yang tumpang tindih telah berhasil dimulai dan penyelesaian tersebut akan ditunjukkan di lain waktu. Kode kesalahan lainnya menunjukkan bahwa operasi yang tumpang tindih tidak berhasil dimulai dan tidak ada indikasi penyelesaian yang akan terjadi. Aplikasi harus menangani ERROR_IO_PENDING atau WSA_IO_PENDING dalam hal ini.

Menampilkan kode	Deskripsi
WSAECONNABORTED	Koneksi yang dibuat dibatalkan oleh perangkat lunak di komputer host Anda. Kesalahan ini dikembalikan jika sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya.
WSAECONNRESET	Koneksi yang ada ditutup secara paksa oleh host jarak jauh. Kesalahan ini dikembalikan untuk soket aliran ketika sirkuit virtual direset oleh sisi jarak jauh. Aplikasi harus menutup soket karena tidak lagi dapat digunakan.
WSAEFAULT	Sistem mendeteksi alamat penunjuk yang tidak valid dalam mencoba menggunakan argumen penunjuk dalam panggilan. Kesalahan ini dikembalikan jika lpPacketArray atau parameter lpOverlapped tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
WSAEINVAL	Argumen yang tidak valid disediakan. Kesalahan ini dikembalikan jika parameter dwFlags memiliki set bendera TF_REUSE_SOCKET , tetapi bendera TF_DISCONNECT tidak diatur. Kesalahan ini juga dikembalikan jika offset yang ditentukan dalam struktur TUMPANG TINDIH yang diarahkan oleh lpOverlapped tidak berada dalam file. Kesalahan ini juga dikembalikan jika jumlah total byte yang akan ditransmisikan adalah nilai yang lebih besar dari 2.147.483.646, nilai maksimum untuk bilangan bulat 32-bit dikurangi 1.
WSAENETDOWN	Operasi soket mengalami jaringan mati. Kesalahan ini dikembalikan jika subsistem jaringan gagal.
WSAENETRESET	Koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung. Kesalahan ini dikembalikan untuk soket aliran tempat koneksi rusak karena aktivitas tetap aktif mendeteksi kegagalan.
WSAENOBUFS	Operasi pada soket tidak dapat dilakukan karena sistem tidak memiliki ruang buffer yang cukup atau karena antrean penuh. Kesalahan ini juga dikembalikan jika penyedia Windows Sockets melaporkan kebuntuan buffer.
WSAENOTCONN	Permintaan untuk mengirim atau menerima data tidak diizinkan karena soket tidak tersambung. Kesalahan ini dikembalikan untuk soket aliran.
WSAENOTSOCK	Operasi dicoba pada sesuatu yang bukan soket. Kesalahan ini dikembalikan jika parameter hSocket bukan soket.
WSAESHUTDOWN	Permintaan untuk mengirim atau menerima data tidak diizinkan karena soket telah dimatikan ke arah tersebut dengan panggilan matikan sebelumnya. Kesalahan ini dikembalikan jika soket aliran telah dimatikan untuk dikirim. Tidak dimungkinkan untuk memanggil TransmitFile pada soket aliran setelah fungsi matikan dipanggil pada soket dengan bagaimana parameter diatur ke SD_SEND atau SD_BOTH.
WSANOTINITIALISED	Aplikasi belum memanggil fungsi WSAStartup , atau WSAStartup gagal. Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi TransmitFile .
WSA_IO_PENDING	Operasi I/O yang tumpang tindih sedang berlangsung. Nilai ini dikembalikan jika operasi I/O yang tumpang tindih berhasil dimulai dan menunjukkan bahwa penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED	Operasi I/O telah dibatalkan karena keluarnya utas atau permintaan aplikasi. Kesalahan ini dikembalikan jika operasi yang tumpang tindih telah dibatalkan karena penutupan soket, eksekusi perintah "SIO_FLUSH" di WSAIoctl, atau utas yang memulai permintaan tumpang tindih yang keluar sebelum operasi selesai. 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 asinkron selesai. Untuk informasi selengkapnya, lihat ExitThread.

Keterangan

Fungsi TransmitPackets dioptimalkan sesuai dengan sistem operasi tempatnya digunakan:

Pada edisi server Windows, fungsi TransmitPackets dioptimalkan untuk performa tinggi.
Pada edisi klien Windows, fungsi TransmitPackets dioptimalkan untuk penggunaan memori dan sumber daya minimum.

Jumlah maksimum byte yang dapat ditransmisikan menggunakan satu panggilan ke fungsi TransmitPackets adalah 2.147.483.646, nilai maksimum untuk bilangan bulat 32-bit dikurangi 1. Jika aplikasi perlu mengirimkan data yang lebih besar dari 2.147.483.646 byte, maka beberapa panggilan ke fungsi TransmitPackets dapat digunakan dengan setiap panggilan mentransfer tidak lebih dari 2.147.483.646 byte.

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

Harapkan hasil performa yang lebih baik saat menggunakan fungsi TransmitPackets pada Windows Server 2003.

Ketika lpOverlapped bukan NULL, I/O yang tumpang tindih mungkin tidak selesai sebelum fungsi TransmitPackets kembali. Ketika ini terjadi, fungsi TransmitPackets kembali gagal, dan panggilan ke fungsi WSAGetLastError mengembalikan ERROR_IO_PENDING, memungkinkan pemanggil untuk terus memproses saat transmisi selesai.

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.

Ketika fungsi TransmitPackets mengembalikan TRUE atau mengembalikan FALSE dan WSAGetLastError mengembalikan ERROR_IO_PENDING, Windows mengatur peristiwa yang ditentukan oleh anggota hEvent dari struktur TUMPANG TINDIH atau soket yang ditentukan oleh hSocket ke status tersinyap, dan setelah selesai, mengirimkan pemberitahuan ke port penyelesaian apa pun yang terkait dengan soket. Gunakan GetOverlappedResult, atau WSAGetOverlappedResult, atau GetQueuedCompletionStatus untuk mengambil status akhir dan jumlah byte yang dikirimkan.

TransmitPackets dan Asynchronous Procedure Calls (APC)

Penggunaan bendera TF_USE_KERNEL_APC dapat memberikan manfaat performa yang signifikan. Jika utas yang memulai panggilan fungsi TransmitPackets sedang digunakan untuk komputasi berat, ada kemungkinan, meskipun tidak mungkin, APC dapat dicegah untuk diluncurkan.

Catatan Ada perbedaan antara APC kernel dan mode pengguna:

APC Kernel diluncurkan saat utas dalam status tunggu.
APC mode pengguna diluncurkan saat utas berada dalam status tunggu yang dapat diperingatkan.

Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

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 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	mswsock.h