LPFN_TRANSMITPACKETS Rückruffunktion (mswsock.h)
Die TransmitPackets-Funktion überträgt Speicherdaten oder Dateidaten über einen verbundenen Socket. Die TransmitPackets-Funktion verwendet den Cache-Manager des Betriebssystems zum Abrufen von Dateidaten, sperrt den Arbeitsspeicher für die minimale Übertragungszeit und führt zu einer effizienten, leistungsstarken Übertragung.
Syntax
LPFN_TRANSMITPACKETS LpfnTransmitpackets;
BOOL LpfnTransmitpackets(
SOCKET hSocket,
LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
DWORD nElementCount,
DWORD nSendSize,
LPOVERLAPPED lpOverlapped,
DWORD dwFlags
)
{...}
Parameter
hSocket
Ein Handle für die verbundene Steckdose, die bei der Übertragung verwendet werden soll. Obwohl der Socket keine verbindungsorientierte Verbindung sein muss, sollte das Standardziel/Peer mithilfe der Funktion connect, WSAConnect, accept, WSAAccept, AcceptEx oder WSAJoinLeaf eingerichtet werden.
lpPacketArray
Ein Array vom Typ TRANSMIT_PACKETS_ELEMENT, das die zu übertragenden Daten beschreibt.
nElementCount
Die Anzahl der Elemente in lpPacketArray.
nSendSize
Die Größe des im Sendevorgang verwendeten Datenblocks in Bytes. Legen Sie nSendSize auf Null fest, damit die Socketebene eine Standardsendegröße auswählen kann.
Durch Festlegen von nSendSize auf 0xFFFFFFF kann der Aufrufer die Größe und den Inhalt jeder Sendeanforderung steuern, die mithilfe des TP_ELEMENT_EOP-Flags im TRANSMIT_PACKETS_ELEMENT Arrays erreicht wird, auf das im lpPacketArray-Parameter verwiesen wird. Diese Funktion ist nützlich für Nachrichtenprotokolle, bei denen die Größe einzelner Sendeanforderungen eingeschränkt wird.
lpOverlapped
Ein Zeiger auf eine Struktur OVERLAPPED. Wenn das im hSocket-Parameter angegebene Sockethandle als überlappend geöffnet wurde, verwenden Sie diesen Parameter, um einen asynchronen (überlappenden) E/A-Vorgang zu erzielen. Sockethandles werden standardmäßig als überlappend geöffnet.
dwFlags
Eine Reihe von Flags, die zum Anpassen der Verarbeitung der TransmitPackets-Funktion verwendet werden. In der folgenden Tabelle wird die Verwendung des dwFlags-Parameters beschrieben.
| Wert | Bedeutung |
|---|---|
|
Startet eine Trennung auf Transportebene, nachdem alle Dateidaten für die Übertragung in die Warteschlange gestellt wurden. Gilt nur für verbindungsorientierte Sockets. Das Angeben dieses Flags für Sockets, die keine Trennsemantik (z. B. Datagrammsockets) unterstützen, führt zu einem Fehler. |
|
Bereitet das Sockethandle für die Wiederverwendung vor. Wenn die TransmitPackets-Funktion abgeschlossen ist, kann der Sockethandle an die AcceptEx-Funktion übergeben werden. Nur gültig, wenn ein verbindungsorientierter Socket und TF_DISCONNECT angegeben sind.
Hinweis Die Übertragung des Pakets auf Socketebene unterliegt dem Verhalten des zugrunde liegenden Transports. Beispielsweise kann ein TCP-Socket dem TCP-TIME_WAIT Zustand unterliegen, wodurch der TransmitPackets-Aufruf verzögert wird.
|
|
Weist Winsock an, den Standardthread des Systems zum Verarbeiten langer TransmitPackets-Anforderungen zu verwenden. Long TransmitPackets-Anforderungen werden als Anforderungen definiert, die mehr als einen einzelnen Lesevorgang aus der Datei oder einem Cache erfordern. die Definition der langen Anforderung hängt daher von der Größe der Datei und der angegebenen Länge des Sendepakets ab.
Der Systemstandardthread kann mithilfe des folgenden Registrierungsparameters als REG_DWORD angepasst werden:HKEY_LOCAL_MACHINE\CurrentControlSet\Services\AFD\Parameters\TransmitWorker |
|
Weist Winsock an, Systemthreads zum Verarbeiten langer TransmitPackets-Anforderungen zu verwenden. Long TransmitPackets-Anforderungen werden als Anforderungen definiert, die mehr als einen einzelnen Lesevorgang aus der Datei oder einem Cache erfordern. die Definition der langen Anforderung hängt daher von der Größe der Datei und der angegebenen Länge des Sendepakets ab. |
|
Weist Winsock an, Kernel-APCs (Asynchrone Prozeduraufrufe ) anstelle von Workerthreads zu verwenden, um lange TransmitPackets-Anforderungen zu verarbeiten. Long TransmitPackets-Anforderungen werden als Anforderungen definiert, die mehr als einen einzelnen Lesevorgang aus der Datei oder einem Cache erfordern. die Definition der langen Anforderung hängt daher von der Größe der Datei und der angegebenen Länge des Sendepakets ab. Weitere Informationen finden Sie unter Hinweise. |
Rückgabewert
Wenn die TransmitPackets-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 lpPacketArray - oder der 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 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 die Gesamtanzahl der zu übertragenden Bytes einen Wert größer als 2.147.483.646 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. Dieser Fehler wird für einen Streamsocket zurückgegeben, bei dem die Verbindung unterbrochen wurde, weil eine Keep-Alive-Aktivität einen Fehler erkennt. | |
| 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. Dieser Fehler wird für einen Streamsocket zurückgegeben. | |
| 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 ein Streamsocket für das Senden heruntergefahren wurde. Es ist nicht möglich, TransmitFile in einem Datenstromsocket aufzurufen, nachdem die Herunterfahrfunktion für den Socket aufgerufen wurde, wobei der How-Parameter 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 TransmitPackets-Funktion ist entsprechend dem Betriebssystem optimiert, auf dem sie verwendet wird:
- Bei Windows Server-Editionen ist die TransmitPackets-Funktion für hohe Leistung optimiert.
- Bei Windows-Clienteditionen ist die TransmitPackets-Funktion für eine minimale Arbeitsspeicher- und Ressourcenauslastung optimiert.
Die maximale Anzahl von Bytes, die mit einem einzelnen Aufruf der TransmitPackets-Funktion übertragen werden können, beträgt 2.147.483.646, der maximale Wert für eine 32-Bit-Ganzzahl minus 1. Wenn eine Anwendung Daten übertragen muss, die größer als 2.147.483.646 Bytes sind, können mehrere Aufrufe der TransmitPackets-Funktion verwendet werden, wobei bei jedem Aufruf nicht mehr als 2.147.483.646 Bytes übertragen werden.
Erwarten Sie bessere Leistungsergebnisse, wenn Sie die TransmitPackets-Funktion unter Windows Server 2003 verwenden.
Wenn lpOverlapped nicht NULL ist, werden überlappende E/A möglicherweise nicht abgeschlossen, bevor die TransmitPackets-Funktion zurückgegeben wird. In diesem Fall gibt die TransmitPackets-Funktion einen Fehler zurück, und ein Aufruf der WSAGetLastError-Funktion gibt ERROR_IO_PENDING zurück, sodass der Aufrufer die Verarbeitung fortsetzen kann, während die Übertragung abgeschlossen ist.
TransmitPackets und asynchrone Prozeduraufrufe (APCs)
Die Verwendung des TF_USE_KERNEL_APC-Flags kann erhebliche Leistungsvorteile bieten. Wenn der Thread, der den TransmitPackets-Funktionsaufruf initiiert, für schwere Berechnungen verwendet wird, ist es möglich, wenn auch unwahrscheinlich, dass APCs nicht gestartet werden.
- Kernel-APCs werden gestartet, wenn sich ein Thread im Wartezustand befindet.
- Benutzermodus-APCs werden gestartet, wenn sich ein Thread in einem warnbaren Wartezustand befindet.
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.
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 |