Fungsi TransmitFile (mswsock.h)
Fungsi TransmitFile mengirimkan data file melalui handel soket yang terhubung. Fungsi ini menggunakan manajer cache sistem operasi untuk mengambil data file, dan menyediakan transfer data file berkinerja tinggi melalui soket.
Sintaks
BOOL TransmitFile(
SOCKET hSocket,
HANDLE hFile,
DWORD nNumberOfBytesToWrite,
DWORD nNumberOfBytesPerSend,
LPOVERLAPPED lpOverlapped,
LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
DWORD dwReserved
);
Parameter
hSocket
Handel ke soket yang tersambung. Fungsi TransmitFile akan mengirimkan data file melalui soket ini. Soket yang ditentukan oleh parameter hSocket harus berupa soket berorientasi koneksi dari jenis SOCK_STREAM, SOCK_SEQPACKET, atau SOCK_RDM.
hFile
Handel ke file terbuka yang ditransmisikan oleh fungsi TransmitFile . Karena sistem operasi membaca data file secara berurutan, Anda dapat meningkatkan performa penembolokan dengan membuka handel dengan FILE_FLAG_SEQUENTIAL_SCAN.
Parameter hFile bersifat opsional. Jika parameter hFileNULL, hanya data di header dan/atau buffer ekor yang ditransmisikan. Tindakan tambahan apa pun, seperti pemutusan sambungan soket atau penggunaan kembali, dilakukan seperti yang ditentukan oleh parameter dwFlags .
nNumberOfBytesToWrite
Jumlah byte dalam file yang akan ditransmisikan. Fungsi TransmitFile selesai ketika telah mengirim jumlah byte yang ditentukan, atau ketika kesalahan terjadi, mana pun yang terjadi terlebih dahulu.
Atur parameter ini ke nol untuk mengirimkan seluruh file.
nNumberOfBytesPerSend
Ukuran, dalam byte, dari setiap blok data yang dikirim dalam setiap operasi pengiriman. Parameter ini digunakan oleh lapisan soket Windows untuk menentukan ukuran blok untuk operasi pengiriman. Untuk memilih ukuran kirim default, atur parameter ini ke nol.
Parameter nNumberOfBytesPerSend berguna untuk protokol yang memiliki batasan ukuran permintaan pengiriman individu.
lpOverlapped
Penunjuk ke struktur YANG TUMPANG TINDIH . Jika handel soket telah dibuka sebagai tumpang tindih, tentukan parameter ini untuk mencapai operasi I/O yang tumpang tindih (asinkron). Secara default, handel soket dibuka sebagai tumpang tindih.
Anda dapat menggunakan parameter lpOverlapped untuk menentukan offset 64-bit dalam file untuk memulai transfer data file dengan mengatur anggota Offset dan OffsetHigh dari struktur YANG TUMPANG TINDIH . Jika lpOverlapped adalah penunjuk NULL , transmisi data selalu dimulai pada offset byte saat ini dalam file.
Ketika lpOverlapped bukan NULL, I/O yang tumpang tindih mungkin tidak selesai sebelum TransmitFile kembali. Dalam hal ini, fungsi TransmitFile mengembalikan FALSE, dan WSAGetLastError mengembalikan ERROR_IO_PENDING atau WSA_IO_PENDING. Ini memungkinkan pemanggil untuk terus memproses saat operasi transmisi file selesai. Windows akan mengatur peristiwa yang ditentukan oleh anggota hEvent dari struktur TUMPANG TINDIH , atau soket yang ditentukan oleh hSocket, ke status yang disinyalir setelah menyelesaikan permintaan transmisi data.
lpTransmitBuffers
Penunjuk ke struktur data TRANSMIT_FILE_BUFFERS yang berisi penunjuk ke data untuk dikirim sebelum dan sesudah data file dikirim. Parameter ini harus diatur ke penunjuk NULL jika Anda hanya ingin mengirimkan data file.
dwReserved
Sekumpulan bendera yang digunakan untuk memodifikasi perilaku panggilan fungsi TransmitFile . Parameter dwFlags dapat berisi kombinasi opsi berikut yang ditentukan dalam file header Mswsock.h :
| Bendera | Makna |
|---|---|
|
Mulai pemutusan tingkat transportasi setelah semua data file diantrekan untuk transmisi. |
|
Siapkan handel soket untuk digunakan kembali. Bendera ini hanya valid jika TF_DISCONNECT juga ditentukan.
Ketika permintaan TransmitFile selesai, handel soket dapat diteruskan ke panggilan fungsi yang sebelumnya digunakan untuk membuat koneksi, seperti AcceptEx atau ConnectEx. Penggunaan kembali tersebut saling eksklusif; misalnya, jika fungsi AcceptEx dipanggil untuk soket, penggunaan kembali hanya diizinkan untuk panggilan berikutnya ke fungsi AcceptEx , dan tidak diizinkan untuk panggilan berikutnya ke ConnectEx. Catatan Pengiriman file tingkat soket tunduk pada perilaku transportasi yang mendasar. Misalnya, soket TCP dapat tunduk pada status TIME_WAIT TCP, menyebabkan panggilan TransmitFile tertunda.
|
|
Mengarahkan penyedia layanan Windows Sockets untuk menggunakan utas default sistem untuk memproses permintaan TransmitFile yang panjang. Utas default sistem dapat disesuaikan menggunakan parameter registri berikut sebagai REG_DWORD: \ HKEY_LOCAL_MACHINECurrentControlSet\Layanan\AFD\Parameter\TransmitWorker |
|
Mengarahkan penyedia layanan Windows Sockets untuk menggunakan utas sistem untuk memproses permintaan TransmitFile yang panjang. |
|
Mengarahkan driver untuk menggunakan panggilan prosedur asinkron kernel (APC) alih-alih utas pekerja untuk memproses permintaan TransmitFile yang panjang. Permintaan TransmitFile panjang didefinisikan sebagai permintaan yang memerlukan lebih dari satu bacaan dari file atau cache; oleh karena itu, permintaan tergantung pada ukuran file dan panjang paket kirim yang ditentukan.
Penggunaan TF_USE_KERNEL_APC dapat memberikan manfaat performa yang signifikan. Namun, dimungkinkan (meskipun tidak mungkin), bahwa utas di mana konteks TransmitFile dimulai digunakan untuk komputasi berat; situasi ini dapat mencegah APC diluncurkan. Perhatikan bahwa driver mode kernel Winsock menggunakan APC kernel normal, yang diluncurkan setiap kali utas dalam keadaan tunggu, yang berbeda dari APC mode pengguna, yang diluncurkan setiap kali utas dalam status tunggu yang dapat diperingatkan dimulai dalam mode pengguna). |
|
Selesaikan permintaan TransmitFile segera, tanpa tertunda. Jika bendera ini ditentukan dan TransmitFile berhasil, maka data telah diterima oleh sistem tetapi belum tentu diakui oleh ujung jarak jauh. Jangan gunakan pengaturan ini dengan bendera TF_DISCONNECT dan TF_REUSE_SOCKET.
Catatan Jika file yang dikirim tidak ada dalam cache sistem file, permintaan tertunda.
|
Mengembalikan nilai
Jika fungsi TransmitFile 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 |
|---|---|
| Koneksi yang dibuat dibatalkan oleh perangkat lunak di komputer host Anda. Kesalahan ini dikembalikan jika sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya. | |
| 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. | |
| Sistem mendeteksi alamat penunjuk yang tidak valid dalam mencoba menggunakan argumen penunjuk dalam panggilan. Kesalahan ini dikembalikan jika parameter lpTransmitBuffers atau lpOverlapped tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid. | |
| Argumen yang tidak valid disediakan. Kesalahan ini dikembalikan jika parameter hSocket menentukan soket jenis SOCK_DGRAM atau SOCK_RAW. 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 parameter nNumberOfBytesToWrite diatur ke nilai yang lebih besar dari 2.147.483.646, nilai maksimum untuk bilangan bulat 32-bit dikurangi 1. | |
| Operasi soket mengalami jaringan mati. Kesalahan ini dikembalikan jika subsistem jaringan gagal. | |
| Koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung. | |
| 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. | |
| Permintaan untuk mengirim atau menerima data tidak diizinkan karena soket tidak tersambung. | |
| Operasi dicoba pada sesuatu yang bukan soket. Kesalahan ini dikembalikan jika parameter hSocket bukan soket. | |
| Permintaan untuk mengirim atau menerima data tidak diizinkan karena soket telah dimatikan ke arah tersebut dengan panggilan matikan sebelumnya. Kesalahan ini dikembalikan jika soket telah dimatikan untuk dikirim. Tidak dimungkinkan untuk memanggil TransmitFile pada soket setelah fungsi matikan dipanggil pada soket dengan bagaimana parameter diatur ke SD_SEND atau SD_BOTH. | |
| Aplikasi belum memanggil fungsi WSAStartup , atau WSAStartup gagal. Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi TransmitFile . | |
| 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. | |
|
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 TransmitFile menggunakan manajer cache sistem operasi untuk mengambil data file, dan menyediakan transfer data file berkinerja tinggi melalui soket.
Fungsi TransmitFile hanya mendukung soket berorientasi koneksi dari jenis SOCK_STREAM, SOCK_SEQPACKET, dan SOCK_RDM. Soket jenis SOCK_DGRAM dan SOCK_RAW tidak didukung. Fungsi TransmitPackets dapat digunakan dengan soket jenis SOCK_DGRAM.
Jumlah maksimum byte yang dapat ditransmisikan menggunakan satu panggilan ke fungsi TransmitFile adalah 2.147.483.646, nilai maksimum untuk bilangan bulat 32-bit dikurangi 1. Jumlah maksimum byte yang akan dikirim dalam satu panggilan mencakup data apa pun yang dikirim sebelum atau sesudah data file yang diarahkan oleh parameter lpTransmitBuffers ditambah nilai yang ditentukan dalam parameter nNumberOfBytesToWrite untuk panjang data file yang akan dikirim. Jika aplikasi perlu mengirimkan file yang lebih besar dari 2.147.483.646 byte, maka beberapa panggilan ke fungsi TransmitFile dapat digunakan dengan setiap panggilan mentransfer tidak lebih dari 2.147.483.646 byte. Mengatur parameter nNumberOfBytesToWrite ke nol untuk file yang lebih besar dari 2.147.483.646 byte juga akan gagal karena dalam hal ini fungsi TransmitFile akan menggunakan ukuran file sebagai nilai untuk jumlah byte yang akan dikirimkan.
Workstation dan versi klien Windows mengoptimalkan fungsi TransmitFile untuk memori minimum dan pemanfaatan sumber daya dengan membatasi jumlah operasi TransmitFile bersamaan yang diizinkan pada sistem hingga maksimal dua. Pada Windows Vista, Windows XP, Windows 2000 Professional, dan Windows NT Workstation 3.51 dan yang lebih baru hanya dua permintaan TransmitFile yang beredar yang ditangani secara bersamaan; permintaan ketiga akan menunggu hingga salah satu permintaan sebelumnya selesai.
Versi server Windows mengoptimalkan fungsi TransmitFile untuk performa tinggi. Pada versi server, tidak ada batas default yang ditempatkan pada jumlah operasi TransmitFile bersamaan yang diizinkan pada sistem. Harapkan hasil performa yang lebih baik saat menggunakan TransmitFile pada versi server Windows. Pada versi server Windows, dimungkinkan untuk menetapkan batas jumlah maksimum operasi TransmitFile bersamaan dengan membuat entri registri dan mengatur nilai untuk REG_DWORD berikut:
\ HKEY_LOCAL_MACHINECurrentControlSet\Layanan\AFD\Parameter\MaxActiveTransmitFileCount
Jika fungsi TransmitFile dipanggil dengan soket TCP (protokol IPPROTO_TCP) dengan bendera TF_DISCONNECT dan TF_REUSE_SOCKET yang ditentukan, panggilan tidak akan selesai sampai dua kondisi berikut terpenuhi.
- Semua data yang tertunda yang dikirim oleh sisi jarak jauh (diterima sebelum FIN dari sisi jarak jauh) pada soket TCP telah dibaca.
- Sisi jarak jauh telah menutup koneksi (menyelesaikan penutupan koneksi TCP yang anggun).
Jika fungsi TransmitFile dipanggil dengan parameter lpOverlapped diatur ke NULL, operasi dijalankan sebagai I/O sinkron. Fungsi tidak akan selesai sampai file dikirim.
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.
Catatan untuk QoS
Fungsi TransmitFile memungkinkan pengaturan dua bendera, TF_DISCONNECT atau TF_REUSE_SOCKET, yang mengembalikan soket ke status "terputus, dapat digunakan kembali" setelah file dikirimkan. Bendera ini tidak boleh digunakan pada soket di mana kualitas layanan telah diminta, karena penyedia layanan dapat segera menghapus kualitas layanan apa pun yang terkait dengan soket sebelum transfer file selesai. Pendekatan terbaik untuk soket berkemampuan QoS adalah hanya memanggil fungsi closesocket ketika transfer file telah selesai, daripada mengandalkan bendera ini.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 (termasuk Mswsock.h) |
| Pustaka | Mswsock.lib |
| DLL | Mswsock.dll |