Freigeben über


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.

Hinweis Diese Funktion ist eine Microsoft-spezifische Erweiterung der Windows Sockets-Spezifikation.

 

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
TF_DISCONNECT
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.
TF_REUSE_SOCKET
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.
 
TF_USE_DEFAULT_WORKER
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

TF_USE_SYSTEM_THREAD
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.
TF_USE_KERNEL_APC
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
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 lpPacketArray - oder der lpOverlapped-Parameter 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 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.
WSAENETDOWN
Bei einem Socketvorgang ist ein totes Netzwerk aufgetreten. Dieser Fehler wird zurückgegeben, wenn für das Netzwerksubsystem ein Fehler aufgetreten ist.
WSAENETRESET
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.
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. Dieser Fehler wird für einen Streamsocket zurückgegeben.
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 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.
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 die Vervollständigung 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 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.

Hinweis Der Funktionszeiger für die TransmitPackets-Funktion muss zur Laufzeit abgerufen werden, indem die WSAIoctl-Funktion mit dem angegebenen SIO_GET_EXTENSION_FUNCTION_POINTER Opcode aufgerufen wird. Der an die WSAIoctl-Funktion übergebene Eingabepuffer muss WSAID_TRANSMITPACKETS enthalten, einen GUID (Globally Unique Identifier), dessen Wert die TransmitPackets-Erweiterungsfunktion identifiziert. Bei Erfolg enthält die von der WSAIoctl-Funktion zurückgegebene Ausgabe einen Zeiger auf die TransmitPackets-Funktion . Die WSAID_TRANSMITPACKETS GUID ist in der Headerdatei Mswsock.h definiert.
 

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.

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 Vorgänge abgeschlossen sind. Weitere Informationen finden Sie unter ExitThread .
 
Wenn die TransmitPackets-FunktionTRUE oder FALSE zurückgibt und WSAGetLastError ERROR_IO_PENDING zurückgibt, legt Windows das vom hEvent-Member der OVERLAPPED-Struktur angegebene Ereignis oder den von hSocket angegebenen Socket auf den signalierten Zustand fest und sendet nach Abschluss eine Benachrichtigung an jeden Abschlussport, der dem Socket zugeordnet ist. Verwenden Sie GetOverlappedResult, WSAGetOverlappedResult oder GetQueuedCompletionStatus, um die endgültige status und die Anzahl der übertragenen Bytes abzurufen.

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.

Hinweis Es gibt einen Unterschied zwischen Kernel- und Benutzermodus-APCs:
  • 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 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.

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

Weitere Informationen

AcceptEx

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED

TRANSMIT_PACKETS_ELEMENT

Transmitfile

WSAAccept

WSAConnect

WSAGetOverlappedResult

WSAJoinLeaf

Winsock-Funktionen

Winsock-Referenz

Akzeptieren

connect

send