WSAGetOverlappedResult-Funktion (winsock2.h)

Artikel
08/27/2023

Die WSAGetOverlappedResult-Funktion ruft die Ergebnisse eines überlappenden Vorgangs für den angegebenen Socket ab.

Syntax

BOOL WSAAPI WSAGetOverlappedResult(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD         lpcbTransfer,
  [in]  BOOL            fWait,
  [out] LPDWORD         lpdwFlags
);

Parameter

[in] s

Ein Deskriptor, der den Socket identifiziert.

Dies ist derselbe Socket, der beim Starten des überlappenden Vorgangs durch einen Aufruf einer der Winsock-Funktionen angegeben wurde, die überlappende Vorgänge unterstützt. Zu diesen Funktionen gehören AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets, WSARecv, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg, WSASendTo und WSAIoctl.

[in] lpOverlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur , die beim Starten des überlappenden Vorgangs angegeben wurde. Dieser Parameter darf kein NULL-Zeiger sein.

[out] lpcbTransfer

Ein Zeiger auf eine 32-Bit-Variable, die die Anzahl der Bytes empfängt, die tatsächlich durch einen Sende- oder Empfangsvorgang oder durch die WSAIoctl-Funktion übertragen wurden. Dieser Parameter darf kein NULL-Zeiger sein.

[in] fWait

Ein Flag, das angibt, 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 die WSAGetLastError-Funktion gibt WSA_IO_INCOMPLETE zurück. Der fWait-Parameter kann nur dann auf TRUE festgelegt werden, wenn der überlappende Vorgang die ereignisbasierte Vervollständigungsbenachrichtigung ausgewählt hat.

[out] lpdwFlags

Ein Zeiger auf eine 32-Bit-Variable, die ein oder mehrere Flags erhält, die die Vervollständigung status. Wenn der überlappende Vorgang über WSARecv oder WSARecvFrom initiiert wurde, enthält dieser Parameter den Ergebniswert für den lpFlags-Parameter . Dieser Parameter darf kein NULL-Zeiger sein.

Rückgabewert

Wenn WSAGetOverlappedResult erfolgreich ist, ist der Rückgabewert TRUE. Dies bedeutet, dass der überlappende Vorgang erfolgreich abgeschlossen wurde und dass der Wert aktualisiert wurde, auf den von lpcbTransfer verwiesen wird.

Wenn WSAGetOverlappedResultFALSE zurückgibt, bedeutet dies, dass entweder der überlappende Vorgang nicht abgeschlossen ist, der überlappende Vorgang abgeschlossen wurde, jedoch mit Fehlern, oder die Vervollständigung des überlappenden Vorgangs status aufgrund von Fehlern in einem oder mehreren Parametern für WSAGetOverlappedResult nicht ermittelt werden konnte. Bei Einem Fehler wird der Wert, auf den von lpcbTransfer verwiesen wird, nicht aktualisiert. Verwenden Sie WSAGetLastError , um die Ursache des Fehlers zu ermitteln (entweder durch die WSAGetOverlappedResult-Funktion oder durch den zugeordneten überlappenden Vorgang).

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSA_INVALID_HANDLE	Der hEvent-Parameter der WSAOVERLAPPED-Struktur enthält kein gültiges Ereignisobjekthandle.
WSA_INVALID_PARAMETER	Einer der Parameter ist inakzeptabel.
WSA_IO_INCOMPLETE	Der fWait-Parameter ist FALSE , und der E/A-Vorgang ist noch nicht abgeschlossen.
WSAEFAULT	Mindestens eins der Parameter lpOverlapped, lpcbTransfer oder lpdwFlags befinden sich nicht in einem gültigen Teil des Benutzeradressraums. Dieser Fehler wird zurückgegeben, wenn der parameter lpOverlapped, lpcbTransfer oder lpdwFlags ein NULL-Zeiger unter Windows Server 2003 und früher war.

Hinweise

Die WSAGetOverlappedResult-Funktion meldet die Ergebnisse des überlappenden Vorgangs, der im lpOverlapped-Parameter für den socket angegeben ist, der im s-Parameter angegeben ist. Die WSAGetOverlappedResult-Funktion wird der Socketdeskriptor und die WSAOVERLAPPED-Struktur übergeben, die beim Aufruf der überlappenden Funktion angegeben wurde. Ein ausstehender Vorgang wird angezeigt, wenn die Funktion, die den Vorgang gestartet hat, FALSE und die WSAGetLastError-Funktion WSA_IO_PENDING zurückgibt. Wenn ein E/A-Vorgang wie WSARecv aussteht, setzt die Funktion, die den Vorgang gestartet hat, den hEvent-Member der WSAOVERLAPPED-Struktur auf den nicht signalierten Zustand zurück. Wenn der ausstehende Vorgang abgeschlossen ist, legt das System das Ereignisobjekt auf den signalierten Zustand fest.

Wenn der fWait-ParameterTRUE ist, bestimmt WSAGetOverlappedResult , ob der ausstehende Vorgang abgeschlossen wurde, indem darauf gewartet wird, dass sich das Ereignisobjekt im signalierten Zustand befindet. Ein Client kann den fWait-Parameter auf TRUE festlegen, aber nur, 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-Parameters der WSAOVERLAPPED-Struktur , und das Festlegen von fWait auf TRUE führt zu unvorhersehbaren Ergebnissen.

Wenn die WSAGetOverlappedResult-Funktion aufgerufen wird, wobei der Parameter lpOverlapped, lpcbTransfer oder lpdwFlags unter Windows Vista auf einen NULL-Zeiger festgelegt ist, führt dies zu einer Zugriffsverletzung. Wenn die WSAGetOverlappedResult-Funktion aufgerufen wird, wobei der LpOverlapped-, lpcbTransfer- oder lpdwFlags-Parameter unter Windows Server 2003 und früher auf einen NULL-Zeiger festgelegt ist, wird der WSAEFAULT-Fehlercode zurückgegeben.

Hinweis Alle E/A-Vorgänge werden abgebrochen, wenn ein 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 .

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.

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	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll