LPWSPSETSOCKOPT-Rückruffunktion (ws2spi.h)

Artikel
08/28/2023

Die LPWSPSetSockOpt-Funktion legt eine Socketoption fest.

Syntax

LPWSPSETSOCKOPT Lpwspsetsockopt;

int Lpwspsetsockopt(
  [in]  SOCKET s,
  [in]  int level,
  [in]  int optname,
  [in]  const char *optval,
  [in]  int optlen,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Der Deskriptor, der einen Socket identifiziert.

[in] level

Die Ebene, auf der die Option definiert ist; die unterstützten Ebenen umfassen SOL_SOCKET. Weitere Informationen finden Sie unter Winsock-Anhänge.

[in] optname

Die Socketoption, für die der Wert festgelegt werden soll.

[in] optval

Ein Zeiger auf den Puffer, in dem der Wert für die angeforderte Option angegeben wird.

[in] optlen

Die Größe des Optval-Puffers in Bytes.

[out] lpErrno

Ein Zeiger auf den Fehlercode.

Rückgabewert

Wenn kein Fehler auftritt, gibt LPWSPSetSockOpt null zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar.

Fehlercode	Bedeutung
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAEFAULT	Der optval befindet sich nicht in einem gültigen Teil des Prozessadressraums oder der optlen-Parameter ist zu klein.
WSAEINPROGRESS	Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird.
WSAEINPROGRESS	Der Windows Sockets-Aufruf wird blockiert, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.
WSAEINVAL	Die Ebene ist ungültig, oder die Informationen in optval sind ungültig.
WSAENETRESET	Die Verbindung wurde unterbrochen, weil eine Keep-Alive-Aktivität einen Fehler erkannt hat, während der Vorgang ausgeführt wurde.
WSAENOPROTOOPT	Die Option ist für den angegebenen Anbieter unbekannt oder wird nicht unterstützt.
WSAENOTCONN	Die Verbindung wurde zurückgesetzt, wenn SO_KEEPALIVE festgelegt wurde.
WSAENOTSOCK	Der Deskriptor ist kein Socket.

Hinweise

Die LPWSPSetSockOpt-Funktion legt den aktuellen Wert für eine Socketoption fest, die einem Socket eines beliebigen Typs in einem beliebigen Zustand zugeordnet ist. Obwohl Optionen auf mehreren Protokollebenen vorhanden sein können, sind sie immer auf der obersten Socketebene vorhanden. Optionen wirken sich auf Socketvorgänge aus, z. B. ob Broadcastnachrichten auf dem Socket gesendet werden können.

Es gibt zwei Arten von Socketoptionen: Boolesche Optionen, die ein Feature oder Verhalten aktivieren oder deaktivieren, und Optionen, die einen ganzzahligen Wert oder eine Struktur erfordern. Um eine boolesche Option zu aktivieren, zeigt optval auf eine ganze Zahl ohne Zero. Um die Option zu deaktivieren, zeigt optval auf eine ganze Zahl gleich 0. Der optlen-Parameter sollte für boolesche Optionen gleich sizeof (int) sein. Bei anderen Optionen zeigt optval auf eine ganze Zahl oder Struktur, die den gewünschten Wert für die Option enthält, und optlen ist die Länge der ganzzahligen Oder Struktur.

Weitere Informationen zu Socketoptionen finden Sie unter Socketoptionen.

level = SOL_SOCKET

Wert	Typ	Bedeutung
SO_BROADCAST	BOOL	Ermöglicht die Übertragung und den Empfang von Broadcastnachrichten auf dem Socket.
SO_DEBUG	BOOL	Zeichnet Debuginformationen auf.
SO_DONTLINGER	BOOL	Reserviert.
SO_DONTROUTE	BOOL	Routing deaktiviert: Senden Sie direkt an eine Schnittstelle. Das Festlegen dieser Socketoption ist erfolgreich, wird jedoch auf AF_INET Sockets ignoriert. tritt auf AF_INET6 Sockets mit WSAENOPROTOOPT aus. Diese Option wird für ATM-Sockets nicht unterstützt (führt zu einem Fehler).
SO_GROUP_PRIORITY	INT	Reserviert.
SO_KEEPALIVE	BOOL	Sendet Keep-Alives. Wird für ATM-Sockets nicht unterstützt (führt zu einem Fehler).
SO_LINGER	Struktur verharren	Bleibt geschlossen, wenn nicht gesendete Daten vorhanden sind.
SO_OOBINLINE	BOOL	Empfängt OOB-Daten im normalen Datenstrom.
SO_RCVBUF	INT	Gibt den Gesamtpufferspeicher pro Socket an, der für Empfangsvorgänge reserviert ist. Dies hat nichts mit SO_MAX_MSG_SIZE zu tun und entspricht nicht unbedingt der Größe des TCP-Empfangsfensters.
SO_REUSEADDR	BOOL	Ermöglicht, dass der Socket an eine bereits verwendete Adresse gebunden wird. (Siehe Bind.) Gilt nicht für Atm-Sockets.
SO_SNDBUF	INT	Gibt den Gesamtpufferspeicher pro Socket an, der für Sendevorgänge reserviert ist. Dies hat nichts mit SO_MAX_MSG_SIZE zu tun und entspricht nicht unbedingt der Größe eines TCP-Sendefensters.
PVD_CONFIG	Dienstanbieterabhängig	Dieses Objekt speichert die Konfigurationsinformationen für den Dienstanbieter, der Sockets zugeordnet ist. Das genaue Format dieser Datenstruktur ist dienstanbieterspezifisch.

Das Aufrufen von LPWSPGetSockopt mit einer nicht unterstützten Option führt zu einem Fehlercode von WSAENOPROTOOPT , der in lpErrno zurückgegeben wird.

SO_DEBUG

Windows Sockets-Dienstanbieter werden empfohlen, aber nicht erforderlich, Ausgabedebuginformationen zur Verfügung zu stellen, wenn die Option SO_DEBUG von einem Windows Sockets SPI-Client festgelegt wird. Der Mechanismus zum Generieren der Debuginformationen und des Formats sprengt den Rahmen dieser Spezifikation.

SO_GROUP_PRIORITY

Reserviert.

SO_KEEPALIVE

Ein Windows Sockets SPI-Client kann anfordern, dass ein TCP/IP-Anbieter die Verwendung von Keep-Alive-Paketen für TCP-Verbindungen aktiviert, indem er die option SO_KEEPALIVE Socket aktiviert. Ein Windows Sockets-Anbieter muss die Verwendung von Keep-Alives nicht unterstützen: Wenn dies der Fall ist, ist die genaue Semantik implementierungsspezifisch, sollte jedoch Abschnitt 4.2.3.6 von RFC 1122: Anforderungen für Internethosts – Kommunikationsebenen entsprechen. (Diese Ressource ist möglicherweise nur auf Englisch verfügbar.) Wenn eine Verbindung als Ergebnis von Keep-Alive abgebrochen wird, wird der Fehlercode WSAENETRESET an alle aufrufenden Am Socket zurückgegeben, und alle nachfolgenden Aufrufe schlagen mit WSAENOTCONN fehl.

SO_LINGER

SO_LINGER steuert die Aktion, die ausgeführt wird, wenn nicht gesendete Daten auf einem Socket in die Warteschlange gestellt werden und ein LPWSPCloseSocket ausgeführt wird. Unter LPWSPCloseSocket finden Sie eine Beschreibung der Art und Weise, in der sich die SO_LINGER-Einstellungen auf die Semantik von LPWSPCloseSocket auswirken. Der Windows Sockets SPI-Client legt das gewünschte Verhalten fest, indem eine LINGER-Struktur erstellt wird, auf die der optval-Parameter verweist, mit den folgenden Elementen.

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

Um SO_LINGER zu aktivieren, sollte ein Windows Sockets SPI-Client l_onoff auf einen Nichtzero-Wert festlegen, l_linger auf Null oder das gewünschte Timeout in Sekunden festlegen und LPWSPSetSockOpt aufrufen. Um SO_DONTLINGER zu aktivieren, d. h. deaktivieren Sie SO_LINGER, l_onoff sollte auf Null und LPWSPSetSockOpt aufgerufen werden. Beachten Sie, dass die Aktivierung SO_LINGER mit einem Nonzero-Timeout auf einem nicht blockierenden Socket nicht empfohlen wird. Weitere Informationen finden Sie unter LPWSPCloseSocket.

Wenn Sie SO_LINGER aktivieren, wird auch SO_DONTLINGER deaktiviert und umgekehrt. Beachten Sie, dass kein Timeoutwert angegeben wird, wenn SO_DONTLINGER deaktiviert ist (d. h. SO_LINGER aktiviert ist). In diesem Fall ist das verwendete Timeout implementierungsabhängig. Wenn ein früheres Timeout für einen Socket festgelegt wurde (durch Aktivieren SO_LINGER), sollte dieser Timeoutwert vom Dienstanbieter wiederhergestellt werden.

SO_REUSEADDR

Standardmäßig kann ein Socket nicht (weitere Informationen finden Sie unter LPWSPBind) an eine lokale Adresse gebunden werden, die bereits verwendet wird. Gelegentlich kann es jedoch wünschenswert sein, eine Adresse auf diese Weise wiederzuverwenden. Da jede Verbindung durch die Kombination von lokalen und Remoteadressen eindeutig identifiziert wird, ist es kein Problem, zwei Sockets an dieselbe lokale Adresse gebunden zu haben, solange sich die Remoteadressen unterscheiden. Um den Windows Sockets-Anbieter darüber zu informieren, dass ein LPWSPBind auf einem Socket an eine lokale Adresse gebunden werden soll, die bereits von einem anderen Socket verwendet wird, sollte der Windows Sockets SPI-Client die SO_REUSEADDR Socketoption für den Socket festlegen, bevor lpWSPBind ausgegeben wird. Beachten Sie, dass die Option nur zum Zeitpunkt des LPWSPBind interpretiert wird: Es ist daher unnötig, aber harmlos, die Option für einen Socket festzulegen, der nicht an eine vorhandene Adresse gebunden werden soll, und das Festlegen oder Zurücksetzen der Option nach dem LPWSPBind hat keine Auswirkungen auf diesen oder einen anderen Socket.

SO_SNDBUF

Wenn eine Windows Sockets-Implementierung die optionen SO_RCVBUF und SO_SNDBUF unterstützt, kann ein Windows Sockets SPI-Client verschiedene Puffergrößen anfordern (größer oder kleiner). Der Anruf kann erfolgreich sein, obwohl der Dienstanbieter nicht den gesamten angeforderten Betrag zur Verfügung gestellt hat. Ein Windows Sockets SPI-Client muss LPWSPGetSockopt mit derselben Option aufrufen, um die tatsächlich bereitgestellte Puffergröße zu überprüfen.

PVD_CONFIG

Dieses Objekt speichert die Konfigurationsinformationen für den Dienstanbieter, der Sockets zugeordnet ist. Das genaue Format dieser Datenstruktur ist dienstanbieterspezifisch.

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