TransmitFile-Funktion (winsock.h)
Die TransmitFile-Funktion überträgt Dateidaten über ein verbundenes Sockethandle. Diese Funktion verwendet den Cache-Manager des Betriebssystems, um die Dateidaten abzurufen, und ermöglicht eine leistungsstarke Dateidatenübertragung über Sockets.
Syntax
BOOL TransmitFile(
SOCKET hSocket,
HANDLE hFile,
DWORD nNumberOfBytesToWrite,
DWORD nNumberOfBytesPerSend,
LPOVERLAPPED lpOverlapped,
LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
DWORD dwReserved
);
Parameter
hSocket
Ein Handle für einen verbundenen Socket. Die TransmitFile-Funktion überträgt die Dateidaten über diesen Socket. Der vom hSocket-Parameter angegebene Socket muss ein verbindungsorientierter Socket vom Typ SOCK_STREAM, SOCK_SEQPACKET oder SOCK_RDM sein.
hFile
Ein Handle für die geöffnete Datei, die von der TransmitFile-Funktion übertragen wird. Da das Betriebssystem die Dateidaten sequenziell liest, können Sie die Zwischenspeicherleistung verbessern, indem Sie das Handle mit FILE_FLAG_SEQUENTIAL_SCAN öffnen.
Der hFile-Parameter ist optional. Wenn der hFile-ParameterNULL ist, werden nur Daten im Header und/oder im Endpuffer übertragen. Alle zusätzlichen Aktionen, z. B. Sockettrennung oder Wiederverwendung, werden wie vom dwFlags-Parameter angegeben ausgeführt.
nNumberOfBytesToWrite
Die Anzahl der Zu übertragenden Bytes in der Datei. Die TransmitFile-Funktion wird abgeschlossen, wenn sie die angegebene Anzahl von Bytes gesendet hat oder wenn ein Fehler auftritt, je nachdem, was zuerst auftritt.
Legen Sie diesen Parameter auf 0 fest, um die gesamte Datei zu übertragen.
nNumberOfBytesPerSend
Die Größe jedes Datenblocks, der in jedem Sendevorgang gesendet wird, in Bytes. Dieser Parameter wird von der Socketschicht von Windows verwendet, um die Blockgröße für Sendevorgänge zu bestimmen. Um die Standardsendegröße auszuwählen, legen Sie diesen Parameter auf Null fest.
Der nNumberOfBytesPerSend-Parameter ist nützlich für Protokolle, die Einschränkungen für die Größe einzelner Sendeanforderungen aufweisen.
lpOverlapped
Ein Zeiger auf eine Struktur OVERLAPPED. Wenn das Sockethandle als überlappend geöffnet wurde, geben Sie diesen Parameter an, um einen überlappenden (asynchronen) E/A-Vorgang zu erzielen. Standardmäßig werden Sockethandles als überlappend geöffnet.
Sie können den lpOverlapped-Parameter verwenden, um einen 64-Bit-Offset in der Datei anzugeben, an dem die Dateidatenübertragung gestartet werden soll, indem Sie das Offset - und OffsetHigh-Element der OVERLAPPED-Struktur festlegen. Wenn lpOverlapped ein NULL-Zeiger ist, beginnt die Übertragung von Daten immer mit dem aktuellen Byteoffset in der Datei.
Wenn lpOverlapped nicht NULL ist, wird die überlappende E/A möglicherweise nicht beendet, bevor TransmitFile zurückgegeben wird. In diesem Fall gibt die TransmitFile-FunktionFALSE und WSAGetLastError ERROR_IO_PENDING oder WSA_IO_PENDING zurück. Dadurch kann der Aufrufer die Verarbeitung fortsetzen, während der Dateiübertragungsvorgang abgeschlossen ist. Windows legt das vom hEvent-Member der OVERLAPPED-Struktur angegebene Ereignis oder den von hSocket angegebenen Socket nach Abschluss der Datenübertragungsanforderung auf den signalierten Zustand fest.
lpTransmitBuffers
Ein Zeiger auf eine TRANSMIT_FILE_BUFFERS Datenstruktur, die Zeiger auf Daten enthält, die vor und nach dem Senden der Dateidaten gesendet werden sollen. Dieser Parameter sollte auf einen NULL-Zeiger festgelegt werden, wenn Sie nur die Dateidaten übertragen möchten.
dwReserved
Eine Reihe von Flags, die verwendet werden, um das Verhalten des TransmitFile-Funktionsaufrufs zu ändern. Der dwFlags-Parameter kann eine Kombination der folgenden Optionen enthalten, die in der Headerdatei "Mswsock.h " definiert sind:
| Flag | Bedeutung |
|---|---|
|
Beginnt, die Verbindung auf Transportebene zu trennen, nachdem alle Dateidaten in die Übertragungswarteschlange gestellt wurden. |
|
Bereiten Sie das Sockethandle für die Wiederverwendung vor. Dieses Flag ist nur gültig, wenn auch TF_DISCONNECT angegeben ist.
Wenn die TransmitFile-Anforderung abgeschlossen ist, kann das Sockethandle an den Funktionsaufruf übergeben werden, der zuvor zum Herstellen der Verbindung verwendet wurde, z. B. AcceptEx oder ConnectEx. Eine solche Wiederverwendung schließt sich gegenseitig aus; Wenn beispielsweise die AcceptEx-Funktion für den Socket aufgerufen wurde, ist die Wiederverwendung nur für nachfolgende Aufrufe der AcceptEx-Funktion und nicht für einen nachfolgenden Aufruf von ConnectEx zulässig. Hinweis Die Dateiübertragung auf Socketebene unterliegt dem Verhalten des zugrunde liegenden Transports. Beispielsweise kann ein TCP-Socket dem TCP-TIME_WAIT Zustand unterliegen, was dazu führt, dass der TransmitFile-Aufruf verzögert wird.
|
|
Weist den Windows Sockets-Dienstanbieter an, den Standardthread des Systems zu verwenden, um lange TransmitFile-Anforderungen zu verarbeiten. Der Systemstandardthread kann mithilfe des folgenden Registrierungsparameters als REG_DWORD angepasst werden: HKEY_LOCAL_MACHINE\Currentcontrolset\Dienstleistungen\AFD\Parameter\TransmitWorker |
|
Weist den Windows Sockets-Dienstanbieter an, Systemthreads zum Verarbeiten langer TransmitFile-Anforderungen zu verwenden. |
|
Weist den Treiber an, kernelsynchrone Prozeduraufrufe (ApCs) anstelle von Workerthreads zu verwenden, um lange TransmitFile-Anforderungen zu verarbeiten. Long TransmitFile-Anforderungen werden als Anforderungen definiert, die mehr als einen einzelnen Lesevorgang aus der Datei oder einem Cache erfordern. die Anforderung hängt daher von der Größe der Datei und der angegebenen Länge des Sendepakets ab.
Die Verwendung von TF_USE_KERNEL_APC kann erhebliche Leistungsvorteile bieten. Es ist jedoch möglich (wenn auch unwahrscheinlich), dass der Thread, in dem der Kontext TransmitFile initiiert wird, für schwere Berechnungen verwendet wird. diese Situation kann den Start von APCs verhindern. Beachten Sie, dass der Winsock-Kernelmodustreiber normale Kernel-APCs verwendet, die immer dann gestartet werden, wenn sich ein Thread in einem Wartezustand befindet, der sich von benutzermodus-APCs unterscheidet, die immer dann gestartet werden, wenn sich ein Thread in einem warnbaren Wartezustand befindet, der im Benutzermodus initiiert wurde. |
|
Führen Sie die TransmitFile-Anforderung sofort aus, ohne ausstehend. Wenn dieses Flag angegeben ist und TransmitFile erfolgreich ist, wurden die Daten vom System akzeptiert, aber nicht unbedingt vom Remoteende bestätigt. Verwenden Sie diese Einstellung nicht mit den Flags TF_DISCONNECT und TF_REUSE_SOCKET.
Hinweis Wenn sich die gesendete Datei nicht im Dateisystemcache befindet, wird die Anforderung an einen Stift gesendet.
|
Rückgabewert
Wenn die TransmitFile-Funktion erfolgreich ist, ist der Rückgabewert TRUE. Andernfalls ist der Rückgabewert FALSE. Rufen Sie WSAGetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Ein Fehlercode von WSA_IO_PENDING oder ERROR_IO_PENDING gibt an, dass der überlappende Vorgang erfolgreich initiiert wurde und dass die Vervollständigung zu einem späteren Zeitpunkt angezeigt wird. Jeder andere Fehlercode gibt an, dass der überlappende Vorgang nicht erfolgreich initiiert wurde und keine Vervollständigungsanzeige auftritt. Anwendungen sollten in diesem Fall entweder ERROR_IO_PENDING oder WSA_IO_PENDING verarbeiten.
| Rückgabecode | Beschreibung |
|---|---|
| Eine hergestellte Verbindung wurde durch die Software auf dem Hostcomputer abgebrochen. Dieser Fehler wird zurückgegeben, wenn die virtuelle Verbindung aufgrund eines Timeouts oder eines anderen Fehlers beendet wurde. | |
| An existing connection was forcibly closed by the remote host. Dieser Fehler wird für einen Streamsocket zurückgegeben, wenn die virtuelle Verbindung von der Remoteseite zurückgesetzt wurde. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist. | |
| Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn der lpTransmitBuffers- oder lpOverlapped-Parameter nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten ist. | |
| Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn der hSocket-Parameter einen Socket vom Typ SOCK_DGRAM oder SOCK_RAW angegeben hat. Dieser Fehler wird zurückgegeben, wenn für den dwFlags-Parameter das TF_REUSE_SOCKET-Flag festgelegt ist, das TF_DISCONNECT-Flag jedoch nicht festgelegt wurde. Dieser Fehler wird auch zurückgegeben, wenn sich der in der OVERLAPPED-Struktur angegebene Offset, auf den lpOverlapped verweist, nicht in der Datei befindet. Dieser Fehler wird auch zurückgegeben, wenn der nNumberOfBytesToWrite-Parameter auf einen Wert größer als 2.147.483.646 festgelegt ist, der maximale Wert für eine 32-Bit-Ganzzahl minus 1. | |
| Bei einem Socketvorgang ist ein totes Netzwerk aufgetreten. Dieser Fehler wird zurückgegeben, wenn für das Netzwerksubsystem ein Fehler aufgetreten ist. | |
| Die Verbindung wurde unterbrochen, weil eine Keep-Alive-Aktivität einen Fehler erkannt hat, während der Vorgang ausgeführt wurde. | |
| Ein Vorgang für einen Socket konnte nicht ausgeführt werden, weil dem System ausreichender Pufferspeicherplatz fehlte oder eine Warteschlange voll war. Dieser Fehler wird auch zurückgegeben, wenn der Windows Sockets-Anbieter einen Puffer-Deadlock meldet. | |
| Eine Anforderung zum Senden oder Empfangen von Daten wurde nicht zugelassen, da der Socket nicht verbunden ist. | |
| Es wurde ein Vorgang für eine Komponente versucht, die kein Socket ist. Dieser Fehler wird zurückgegeben, wenn der hSocket-Parameter kein Socket ist. | |
| Eine Anforderung zum Senden oder Empfangen von Daten wurde nicht zugelassen, da der Socket in die entsprechende Richtung bereits durch einen vorangegangenen shutdown-Aufruf heruntergefahren wurde. Dieser Fehler wird zurückgegeben, wenn der Socket zum Senden heruntergefahren wurde. Es ist nicht möglich, TransmitFile in einem Socket aufzurufen, nachdem die Herunterfahrfunktion für den Socket aufgerufen wurde, wobei der Parameter how auf SD_SEND oder SD_BOTH festgelegt ist. | |
| Entweder hat die Anwendung die WSAStartup-Funktion nicht aufgerufen, oder WSAStartup ist fehlgeschlagen. Vor der Verwendung der TransmitFile-Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen. | |
| Ein überlappender E/A-Vorgang wird ausgeführt. Dieser Wert wird zurückgegeben, wenn ein überlappender E/A-Vorgang erfolgreich initiiert wurde und angibt, dass die Vervollständigung zu einem späteren Zeitpunkt angezeigt wird. | |
|
Der E/A-Vorgang wurde wegen eines Threadendes oder einer Anwendungsanforderung abgebrochen. Dieser Fehler wird zurückgegeben, wenn der überlappende Vorgang aufgrund des Schließens des Sockets, der Ausführung des Befehls "SIO_FLUSH" in WSAIoctl oder des Threads, der die überlappende Anforderung initiiert hat, abgebrochen wurde, bevor der Vorgang abgeschlossen wurde.
Hinweis Alle von einem bestimmten Thread initiierten E/A-Vorgänge werden abgebrochen, wenn dieser Thread beendet wird. Bei überlappenden Sockets können ausstehende asynchrone Vorgänge fehlschlagen, wenn der Thread geschlossen wird, bevor die asynchronen Vorgänge abgeschlossen werden. Weitere Informationen finden Sie unter ExitThread.
|
Hinweise
Die TransmitFile-Funktion verwendet den Cache-Manager des Betriebssystems, um die Dateidaten abzurufen und eine leistungsstarke Dateidatenübertragung über Sockets bereitzustellen.
Die TransmitFile-Funktion unterstützt nur verbindungsorientierte Sockets vom Typ SOCK_STREAM, SOCK_SEQPACKET und SOCK_RDM. Sockets vom Typ SOCK_DGRAM und SOCK_RAW werden nicht unterstützt. Die TransmitPackets-Funktion kann mit Sockets vom Typ SOCK_DGRAM verwendet werden.
Die maximale Anzahl von Bytes, die mit einem einzelnen Aufruf an die TransmitFile-Funktion übertragen werden können, beträgt 2.147.483.646, der maximale Wert für eine 32-Bit-Ganzzahl minus 1. Die maximale Anzahl von Bytes, die in einem einzelnen Aufruf gesendet werden sollen, umfasst alle Daten, die vor oder nach den Dateidaten gesendet werden, auf die der parameter lpTransmitBuffers verweist, sowie den wert, der im Parameter nNumberOfBytesToWrite für die Länge der zu sendenden Dateidaten angegeben ist. Wenn eine Anwendung eine Datei übertragen muss, die größer als 2.147.483.646 Bytes ist, können mehrere Aufrufe der TransmitFile-Funktion verwendet werden, wobei bei jedem Aufruf nicht mehr als 2.147.483.646 Bytes übertragen werden. Das Festlegen des Parameters nNumberOfBytesToWrite für eine Datei, die größer als 2.147.483.646 Bytes ist, schlägt ebenfalls fehl, da in diesem Fall die TransmitFile-Funktion die Größe der Datei als Wert für die Anzahl der zu übertragenden Bytes verwendet.
Arbeitsstations- und Clientversionen von Windows optimieren die TransmitFile-Funktion für eine minimale Arbeitsspeicher- und Ressourcenauslastung, indem die Anzahl gleichzeitig zulässiger TransmitFile-Vorgänge auf dem System auf maximal zwei beschränkt wird. Unter Windows Vista, Windows XP, Windows 2000 Professional und Windows NT Workstation 3.51 und höher werden nur zwei ausstehende TransmitFile-Anforderungen gleichzeitig verarbeitet. die dritte Anforderung wartet, bis eine der vorherigen Anforderungen abgeschlossen ist.
Serverversionen von Windows optimieren die TransmitFile-Funktion für hohe Leistung. Bei Serverversionen gibt es keine Standardbeschränkungen für die Anzahl gleichzeitiger TransmitFile-Vorgänge , die auf dem System zulässig sind. Erwarten Sie bessere Leistungsergebnisse, wenn Sie TransmitFile auf Serverversionen von Windows verwenden. Unter Serverversionen von Windows ist es möglich, ein Limit für die maximale Anzahl gleichzeitiger TransmitFile-Vorgänge festzulegen, indem Sie einen Registrierungseintrag erstellen und einen Wert für die folgende REG_DWORD festlegen:
HKEY_LOCAL_MACHINE\Currentcontrolset\Dienstleistungen\AFD\Parameter\MaxActiveTransmitFileCount
Wenn die TransmitFile-Funktion mit TCP-Socket (Protokoll der IPPROTO_TCP) aufgerufen wird, wobei sowohl das TF_DISCONNECT - als auch TF_REUSE_SOCKET-Flags angegeben sind, wird der Aufruf erst abgeschlossen, wenn die beiden folgenden Bedingungen erfüllt sind.
- Alle ausstehenden Empfangensdaten, die von der Remoteseite (empfangen vor einer FIN von der Remoteseite) auf dem TCP-Socket gesendet wurden, wurden gelesen.
- Die Remoteseite hat die Verbindung geschlossen (die ordnungsgemäße TCP-Verbindung wurde geschlossen).
Wenn die TransmitFile-Funktion aufgerufen wird und der lpOverlapped-Parameter auf NULL festgelegt ist, wird der Vorgang als synchrone E/A ausgeführt. Die Funktion wird erst abgeschlossen, wenn die Datei gesendet wurde.
Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.
Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
Hinweise für QoS
Die TransmitFile-Funktion ermöglicht das Festlegen von zwei Flags, TF_DISCONNECT oder TF_REUSE_SOCKET, die den Socket nach der Übertragung in einen "getrennten, wiederverwendbaren" Zustand zurückgeben. Diese Flags sollten nicht für ein Socket verwendet werden, bei dem die Dienstqualität angefordert wurde, da der Dienstanbieter alle mit dem Socket verbundenen Dienstqualität sofort löschen kann, bevor die Dateiübertragung abgeschlossen ist. Der beste Ansatz für einen QoS-fähigen Socket besteht darin, einfach die Closesocket-Funktion aufzurufen, wenn die Dateiübertragung abgeschlossen ist, anstatt sich auf diese Flags zu verlassen.Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 8.1, Windows Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsock.h (einschließen von Mswsock.h) |
| Bibliothek | Mswsock.lib |
| DLL | Mswsock.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für