TransmitFile-Funktion (mswsock.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 Tailpuffer übertragen. Jede zusätzliche Aktion, z. B. Socket trennen oder wiederverwenden, wird wie im dwFlags-Parameter angegeben ausgeführt.

nNumberOfBytesToWrite

Die Anzahl der Zu übertragenden Bytes in der Datei. Die TransmitFile-Funktion wird abgeschlossen, wenn die angegebene Anzahl von Bytes gesendet wurde, oder wenn ein Fehler auftritt, je nachdem, was zuerst auftritt.

Legen Sie diesen Parameter auf Null fest, um die gesamte Datei zu übertragen.

nNumberOfBytesPerSend

Die Größe der einzelnen Datenblöcke, die in jedem Sendevorgang gesendet werden, in Bytes. Dieser Parameter wird von der Socketebene 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 für Protokolle nützlich, bei denen die Größe einzelner Sendeanforderungen eingeschränkt ist.

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. Sockethandles werden standardmäßig als überlappend geöffnet.

Sie können den lpOverlapped-Parameter verwenden, um einen 64-Bit-Offset innerhalb der Datei anzugeben, an der die Dateidatenübertragung gestartet werden soll, indem Sie die Elemente Offset und OffsetHigh der OVERLAPPED-Struktur festlegen. Wenn lpOverlapped ein NULL-Zeiger ist, beginnt die Übertragung der Daten immer am aktuellen Byteoffset in der Datei.

Wenn lpOverlapped nicht NULL ist, wird die überlappende E/A möglicherweise nicht abgeschlossen, 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 Mswsock.h-Headerdatei definiert sind:

Flag	Bedeutung
TF_DISCONNECT	Beginnt, die Verbindung auf Transportebene zu trennen, nachdem alle Dateidaten in die Übertragungswarteschlange gestellt wurden.
TF_REUSE_SOCKET	Bereiten Sie das Sockethandle vor, das wiederverwendet werden soll. 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.
TF_USE_DEFAULT_WORKER	Weist den Windows Sockets-Dienstanbieter an, den Standardthread des Systems zu verwenden, um lange TransmitFile-Anforderungen zu verarbeiten. Der Standardthread des Systems kann mithilfe des folgenden Registrierungsparameters als REG_DWORD angepasst werden: HKEY_LOCAL_MACHINE\Currentcontrolset\Dienstleistungen\AFD\Parameter\TransmitWorker
TF_USE_SYSTEM_THREAD	Weist den Windows Sockets-Dienstanbieter an, Systemthreads zum Verarbeiten langer TransmitFile-Anforderungen zu verwenden.
TF_USE_KERNEL_APC	Weist den Treiber an, kernelsynchrone Prozeduraufrufe (ApCs) anstelle von Workerthreads zu verwenden, um lange TransmitFile-Anforderungen zu verarbeiten. Lange TransmitFile-Anforderungen werden als Anforderungen definiert, die mehr als ein einzelnes Lesen 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 gestartet werden, wenn sich ein Thread in einem warnbaren Wartezustand befindet, der im Benutzermodus initiiert wurde.
TF_WRITE_BEHIND	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 Remote-Ende 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 für die Anforderung ein Stift verwendet.

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 der Abschluss zu einem späteren Zeitpunkt angezeigt wird. Ein anderer Fehlercode gibt an, dass der überlappende Vorgang nicht erfolgreich initiiert wurde und keine Abschlussanzeige angezeigt wird. Anwendungen sollten in diesem Fall entweder ERROR_IO_PENDING oder WSA_IO_PENDING verarbeiten.

Rückgabecode	Beschreibung
WSAECONNABORTED	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.
WSAECONNRESET	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.
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn der Parameter lpTransmitBuffers oder lpOverlapped nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten ist.
WSAEINVAL	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 flag TF_REUSE_SOCKET festgelegt ist, das TF_DISCONNECT-Flag jedoch nicht festgelegt wurde. Dieser Fehler wird auch zurückgegeben, wenn der Offset, der in der OVERLAPPED-Struktur angegeben ist, auf die von lpOverlapped verwiesen wird, nicht innerhalb der Datei ist. 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.
WSAENETDOWN	Bei einem Socketvorgang ist ein totes Netzwerk aufgetreten. Dieser Fehler wird zurückgegeben, wenn das Netzwerksubsystem fehlgeschlagen ist.
WSAENETRESET	Die Verbindung wurde unterbrochen, weil eine Keep-Alive-Aktivität einen Fehler erkannt hat, während der Vorgang ausgeführt wurde.
WSAENOBUFS	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.
WSAENOTCONN	Eine Anforderung zum Senden oder Empfangen von Daten wurde nicht zugelassen, da der Socket nicht verbunden ist.
WSAENOTSOCK	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.
WSAESHUTDOWN	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 für das Senden heruntergefahren wurde. Es ist nicht möglich, TransmitFile für einen Socket aufzurufen, nachdem die Funktion zum Herunterfahren für den Socket mit dem parameter how auf SD_SEND oder SD_BOTH festgelegt wurde.
WSANOTINITIALISIERT	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.
WSA_IO_PENDING	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 der Abschluss zu einem späteren Zeitpunkt angezeigt wird.
WSA_OPERATION_ABORTED	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 sind. 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 der 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, umfasst alle Daten, die vor oder nach den Dateidaten gesendet werden, auf die der lpTransmitBuffers-Parameter verweist, sowie den wert, der im nNumberOfBytesToWrite-Parameter 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 nNumberOfBytesToWrite-Parameters 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.

Die TransmitFile-Funktion wurde in erster Linie winsock zur Verwendung durch hochleistungsfähige Serveranwendungen (z. B. Web- und FTP-Server) hinzugefügt.

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 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, einen Grenzwert für die maximale Anzahl gleichzeitiger TransmitFile-Vorgänge festzulegen, indem Sie einen Registrierungseintrag erstellen und einen Wert für die folgenden REG_DWORD festlegen:

HKEY_LOCAL_MACHINE\Currentcontrolset\Dienstleistungen\AFD\Parameter\MaxActiveTransmitFileCount

Wenn die TransmitFile-Funktion mit TCP-Socket (Protokoll der IPPROTO_TCP) mit den angegebenen flags TF_DISCONNECT und TF_REUSE_SOCKET aufgerufen wird, wird der Aufruf erst abgeschlossen, wenn die beiden folgenden Bedingungen erfüllt sind.

• Alle ausstehenden Empfangsdaten, die von Remoteseite (empfangen vor einem FIN von der Remoteseite) auf dem TCP-Socket gesendet werden, wurden gelesen.
• Die Remoteseite hat die Verbindung geschlossen (der ordnungsgemäße TCP-Verbindungsabschluss wurde abgeschlossen).

Wenn die TransmitFile-Funktion aufgerufen wird, wobei 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 ab Windows Phone 8 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 der Datei in einen "getrennten, wiederverwendbaren" Zustand zurückversetzen. Diese Flags sollten nicht für einen Socket verwendet werden, bei dem die Dienstqualität angefordert wurde, da der Dienstanbieter jede Dienstqualität im Zusammenhang mit dem Socket 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	mswsock.h (mswsock.h einschließen)
Bibliothek	Mswsock.lib
DLL	Mswsock.dll

Weitere Informationen

ExitThread

OVERLAPPED

TRANSMIT_FILE_BUFFERS

TransmitPackets

WSASend

closesocket