Herunterfahren-Funktion (winsock2.h)

Artikel
08/27/2023

Die Funktion zum Herunterfahren deaktiviert das Senden oder Empfangen eines Sockets.

Syntax

int WSAAPI shutdown(
  [in] SOCKET s,
  [in] int    how
);

Parameter

[in] s

Ein Deskriptor, der einen Socket identifiziert.

[in] how

Ein Flag, das beschreibt, welche Arten von Vorgängen nicht mehr zulässig sind. Mögliche Werte für dieses Flag sind in der Winsock2.h-Headerdatei aufgeführt.

Wert	Bedeutung
SD_RECEIVE 0	Herunterfahren von Empfangsvorgängen.
SD_SEND 1	Herunterfahren von Sendevorgängen.
SD_BOTH 2	Herunterfahren von Sende- und Empfangsvorgängen.

Rückgabewert

Wenn kein Fehler auftritt, gibt das Herunterfahren null zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSAECONNABORTED	Timeout- oder anderer Fehler. Die virtuelle Verbindung wurde beendet. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist. Dieser Fehler gilt nur für einen verbindungsorientierten Socket.
WSAECONNRESET	Die virtuelle Verbindung wurde von der Remoteseite zurückgesetzt, die einen harten oder abbrechenden Schließvorgang ausgeführt hat. Die Anwendung sollte den Socket schließen, weil er nicht mehr verwendbar ist. Dieser Fehler gilt nur für einen verbindungsorientierten Socket.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.
WSAEINVAL	Der wie-Parameter ist ungültig oder nicht mit dem Sockettyp konsistent. Beispielsweise wird SD_SEND mit einem UNI_RECV Sockettyp verwendet.
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENOTCONN	Der Socket ist nicht verbunden. Dieser Fehler gilt nur für einen verbindungsorientierten Socket.
WSAENOTSOCK	Hinweis Der Deskriptor ist kein Socket.
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.

Hinweise

Die Shutdown-Funktion wird für alle Arten von Sockets verwendet, um den Empfang, die Übertragung oder beides zu deaktivieren.

Wenn der wie-Parameter SD_RECEIVE ist, werden nachfolgende Aufrufe der Recv-Funktion auf dem Socket nicht zugelassen. Dies hat keine Auswirkungen auf die unteren Protokollebenen. Bei TCP-Sockets wird die Verbindung zurückgesetzt, da die Daten nicht an den Benutzer übermittelt werden können, wenn weiterhin Daten auf dem Socket in der Warteschlange stehen, die auf den Empfang warten. Für UDP-Sockets werden eingehende Datagramme akzeptiert und in die Warteschlange gestellt. In keinem Fall wird ein ICMP-Fehlerpaket generiert.

Wenn der how-Parameter SD_SEND ist, werden nachfolgende Aufrufe der Sendefunktion nicht zugelassen. Bei TCP-Sockets wird ein FIN gesendet, nachdem alle Daten gesendet und vom Empfänger bestätigt wurden.

Wenn Sie festlegen, wie SD_BOTH festgelegt wird, werden sowohl Senden als auch Empfangen deaktiviert, wie oben beschrieben.

Die Shutdown-Funktion schließt den Socket nicht. Alle Ressourcen, die an den Socket angefügt sind, werden erst freigegeben, wenn closesocket aufgerufen wird.

Um sicherzustellen, dass alle Daten auf einem verbundenen Socket gesendet und empfangen werden, bevor sie geschlossen werden, sollte eine Anwendung das Herunterfahren verwenden, um die Verbindung vor dem Aufrufen von closesocket zu schließen. Eine Methode zum Warten auf die Benachrichtigung, dass das Remoteende alle zugehörigen Daten gesendet und eine ordnungsgemäße Trennung initiiert hat, verwendet die WSAEventSelect-Funktion wie folgt:

Rufen Sie WSAEventSelect auf, um sich für FD_CLOSE Benachrichtigung zu registrieren.
Aufrufen des Herunterfahrens mit how=SD_SEND.
Wenn FD_CLOSE empfangen wurde, rufen Sie recv oder WSARecv auf, bis die Funktion erfolgreich abgeschlossen ist und angibt, dass null Bytes empfangen wurden. Wenn SOCKET_ERROR zurückgegeben wird, ist die ordnungsgemäße Trennung nicht möglich.
Rufen Sie closesocket auf.

Eine weitere Methode zum Warten auf die Benachrichtigung, dass das Remoteende alle zugehörigen Daten gesendet und eine ordnungsgemäße Trennung initiiert hat, verwendet überlappende Empfangsaufrufe:

Aufrufen des Herunterfahrens mit how=SD_SEND.
Rufen Sie recv oder WSARecv auf, bis die Funktion erfolgreich abgeschlossen ist und angibt, dass null Bytes empfangen wurden. Wenn SOCKET_ERROR zurückgegeben wird, ist die ordnungsgemäße Trennung nicht möglich.
Rufen Sie closesocket auf.

Hinweis Die Herunterfahrfunktion wird unabhängig von der SO_LINGER Einstellung für den Socket nicht blockiert.

Weitere Informationen finden Sie im Abschnitt zu Graceful Shutdown, Linger Options und Socket Closure.

Sobald die Herunterfahren-Funktion aufgerufen wurde, um senden, empfangen oder beides zu deaktivieren, gibt es keine Methode, um das Senden oder Empfangen für die vorhandene Socketverbindung erneut zu aktivieren.

Eine Anwendung sollte sich nicht darauf verlassen, dass ein Socket nach dem Herunterfahren wiederverwendet werden kann. Insbesondere ist ein Windows Sockets-Anbieter nicht erforderlich, um die Verwendung der Verbindung für einen heruntergefahrenen Socket zu unterstützen.

Wenn eine Anwendung einen Socket wiederverwenden möchte, sollte die DisconnectEx-Funktion aufgerufen werden, wobei der dwFlags-Parameter auf TF_REUSE_SOCKET festgelegt ist, um eine Verbindung in einem Socket zu schließen und das Sockethandle für die Wiederverwendung vorzubereiten. Wenn die DisconnectEx-Anforderung abgeschlossen ist, kann das Sockethandle an die AcceptEx - oder ConnectEx-Funktion übergeben werden.

Wenn eine Anwendung einen Socket wiederverwenden möchte, können die TransmitFile - oder TransmitPackets-Funktionen aufgerufen werden, wenn der dwFlags-Parameter mit TF_DISCONNECT festgelegt ist und TF_REUSE_SOCKET , die Verbindung zu trennen, nachdem alle Daten für die Übertragung in die Warteschlange gestellt wurden, und das Sockethandle für die Wiederverwendung vorbereiten. 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. Wenn die TransmitPackets-Funktion abgeschlossen ist, kann der Sockethandle an die AcceptEx-Funktion übergeben werden.

Hinweis Die Trennung der 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 DisconnectEx-, TransmitFile- oder TransmitPackets-Aufruf verzögert wird.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf wie das Herunterfahren ausstellen, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Anruf abgeschlossen werden kann. Winsock führt in dieser Situation eine warnbare Wartezeit aus, die durch einen asynchronen Prozeduraufruf (APC) unterbrochen werden kann, der für denselben Thread geplant ist. Das Ausgeben eines weiteren blockierenden Winsock-Aufrufs in einem APC, der einen fortlaufenden blockierenden Winsock-Aufruf im selben Thread unterbrochen hat, führt zu nicht definiertem Verhalten und darf niemals von Winsock-Clients versucht werden.

Hinweise für ATM

Bei Verwendung des asynchronen Übertragungsmodus (ATM) und Windows Sockets 2 gibt es wichtige Probleme im Zusammenhang mit dem Verbindungsabriss. Weitere Informationen zu diesen wichtigen Überlegungen finden Sie im Abschnitt Hinweise für ATM im Abschnitt Hinweise der Closesocket-Funktionsreferenz .

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 unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen


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 (einschließlich Winsock2.h, Webhost.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll