LPWSPGETOVERLAPPEDRESULT-Rückruffunktion (ws2spi.h)

Artikel
03/04/2024

Die LPWSPGetOverlappedResult-Funktion gibt die Ergebnisse eines überlappenden Vorgangs für den angegebenen Socket zurück.

Syntax

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Identifiziert den Socket. Dies ist derselbe Socket, der angegeben wurde, als der überlappende Vorgang durch einen Aufruf von LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo oder LPWSPIoctl gestartet wurde.

[in] lpOverlapped

Zeiger auf eine WSAOverlapped-Struktur , die beim Starten des überlappenden Vorgangs angegeben wurde.

[out] lpcbTransfer

Zeiger auf eine 32-Bit-Variable, die die Anzahl der Bytes empfängt, die tatsächlich durch einen Sende- oder Empfangsvorgang oder durch LPWSPIoctl übertragen wurden.

[in] fWait

Gibt an, ob die Funktion warten soll, bis der ausstehende überlappende Vorgang abgeschlossen ist. Wenn TRUE, wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde. Wenn FALSE und der Vorgang noch aussteht, gibt die Funktion FALSE zurück, und lpErrno ist WSA_IO_INCOMPLETE. Der fWait-Parameter kann nur auf TRUE festgelegt werden, wenn der überlappende Vorgang ereignisbasierte Vervollständigungsbenachrichtigung ausgewählt hat.

[out] lpdwFlags

Zeiger auf eine 32-Bit-Variable, die ein oder mehrere Flags erhält, die die Vervollständigung status. Wenn der überlappende Vorgang über LPWSPRecv oder LPWSPRecvFrom initiiert wurde, enthält dieser Parameter den Ergebniswert für den lpFlags-Parameter .

[out] lpErrno

Zeiger auf den Fehlercode.

Rückgabewert

Wenn LPWSPGetOverlappedResult erfolgreich ist, ist der Rückgabewert TRUE. Dies bedeutet, dass der überlappende Vorgang erfolgreich abgeschlossen wurde und der Wert, auf den von lpcbTransfer verwiesen wird, aktualisiert wurde. Wenn LPWSPGetOverlappedResultFALSE zurückgibt, bedeutet dies, dass der überlappende Vorgang nicht abgeschlossen wurde oder der überlappende Vorgang abgeschlossen wurde, aber mit Fehlern oder vervollständigten status aufgrund von Fehlern in einem oder mehreren Parametern für LPWSPGetOverlappedResult nicht ermittelt werden konnte. Bei Einem Fehler wird der Wert, auf den von lpcbTransfer verwiesen wird, nicht aktualisiert. Der lpErrno-Parameter gibt die Ursache des Fehlers an (entweder von LPWSPGetOverlappedResult oder des zugeordneten überlappenden Vorgangs).

Fehlercode	Bedeutung
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSA_INVALID_HANDLE	Das hEvent-Element der WSAOverlapped-Struktur enthält kein gültiges Ereignisobjekthandle.
WSAEINVAL	Einer der Parameter ist inakzeptabel.
WSA_IO_INCOMPLETE	Der fWait-Parameter ist FALSE, und der E/A-Vorgang ist noch nicht abgeschlossen.

Hinweise

Die von der LPWSPGetOverlappedResult-Funktion gemeldeten Ergebnisse sind die Ergebnisse des letzten überlappenden Vorgangs des angegebenen Sockets, für den die angegebene WSAOverlapped-Struktur bereitgestellt wurde und für die die Ergebnisse des Vorgangs ausstehen. Ein ausstehender Vorgang wird angezeigt, wenn die Funktion, die den Vorgang gestartet hat, SOCKET_ERROR zurückgibt und lpErrno WSA_IO_PENDING wird. Wenn ein E/A-Vorgang aussteht, setzt die Funktion, die den Vorgang gestartet hat, den hEvent-Member der WSAOVERLAPPED-Struktur auf den nicht signalierten Zustand zurück. Nach Abschluss des ausstehenden Vorgangs legt das System das Ereignisobjekt auf den signalierten Zustand fest.

Wenn der fWait-ParameterTRUE ist, bestimmt LPWSPGetOverlappedResult , ob der ausstehende Vorgang abgeschlossen wurde, indem blockiert und gewartet wird, bis sich das Ereignisobjekt im signalierten Zustand befindet. Ein Client kann den fWait-Parameter nur dann auf TRUE festlegen, wenn er die ereignisbasierte Vervollständigungsbenachrichtigung ausgewählt hat, als der E/A-Vorgang angefordert wurde. Wenn eine andere Form der Benachrichtigung ausgewählt wurde, unterscheidet sich die Verwendung des hEvent-Members der WSAOverlapped-Struktur , und das Festlegen von fWait auf TRUE führt zu unvorhersehbaren Ergebnissen.

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 werden. Weitere Informationen finden Sie unter ExitThread .

Interaktion mit WPUCompleteOverlappedRequest

Das Verhalten von WPUCompleteOverlappedRequest enthält einige Einschränkungen für die Implementierung von LPWSPGetOverlappedResult durch einen Dienstanbieter, da nur die Offset - und OffsetHigh-Member der WSAOverlapped-Struktur ausschließlich vom Dienstanbieter gesteuert werden, obwohl drei Werte (Byteanzahl, Flags und Fehler) von LPWSPGetOverlappedResult aus der Struktur abgerufen werden müssen. Ein Dienstanbieter kann dies auf beliebige Weise erreichen, solange er ordnungsgemäß mit dem Verhalten von WPUCompleteOverlappedRequest interagiert. Die folgende Beschreibung stellt eine typische Implementierung dar:

Zu Beginn der überlappenden Verarbeitung legt der Dienstanbieter Internal auf WSS_OPERATION_IN_PROGRESS fest.

Wenn der E/A-Vorgang abgeschlossen ist, legt der Anbieter OffsetHigh auf den Fehlercode von Windows Sockets 2 fest, der sich aus dem Vorgang ergibt, legt Offset auf die Flags fest, die sich aus dem E/A-Vorgang ergeben, und ruft WPUCompleteOverlappedRequest auf, wobei die Anzahl der Übertragungsbytes als einen der Parameter übergeben wird. WPUCompleteOverlappedRequest legt Schließlich InternalHigh auf die Anzahl der Übertragungsbytes fest, und legt dann Internal auf einen anderen Wert als WSS_OPERATION_IN_PROGRESS fest.

Wenn LPWSPGetOverlappedResult aufgerufen wird, überprüft der Dienstanbieter Internal. Wenn es WSS_OPERATION_IN_PROGRESS ist, wartet der Anbieter auf dem Ereignishandle im hEvent-Member oder gibt einen Fehler zurück, basierend auf der Einstellung des fWait-Flags von LPWSPGetOverlappedResult. Wenn nicht oder nach Abschluss des Wartens nicht ausgeführt wird, gibt der Anbieter die Werte von InternalHigh, OffsetHigh und Offset als Übertragungsanzahl, Vorgangsergebnisfehlercode und Flags zurück.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Kopfzeile	ws2spi.h