SIO_KEEPALIVE_VALS-Steuerelementcode

Artikel
06/13/2023

BESCHREIBUNG

Der SIO_KEEPALIVE_VALS-Steuerungscode aktiviert oder deaktiviert die Verbindungseinstellung der TCP-Keep-Alive-Option, die das TCP-Keep-Alive-Timeout und das TCP-Intervall angibt.

Um diesen Vorgang auszuführen, rufen Sie die Funktion WSAIoctl oder WSPIoctl mit den folgenden Parametern auf.

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameter

s

Ein Deskriptor, der einen Socket identifiziert.

dwIoControlCode

Der Steuerelementcode für den Vorgang. Verwenden Sie für diesen Vorgang SIO_KEEPALIVE_VALS .

lpvInBuffer

Ein Zeiger auf den Eingabepuffer. Dieser Parameter sollte auf eine tcp_keepalive-Struktur verweisen.

cbInBuffer

Die Größe des Eingabepuffers in Bytes. Dieser Parameter sollte der Größe der tcp_keepalive Struktur entsprechen oder größer sein, auf die der lpvInBuffer-Parameter verweist.

lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer. Dieser Parameter wird für diesen Vorgang nicht verwendet.

cbOutBuffer

Die Größe des Ausgabepuffers in Bytes. Dieser Parameter muss auf 0 festgelegt werden.

lpcbBytesReturned

Ein Zeiger auf eine Variable, die die Größe der im Ausgabepuffer gespeicherten Daten in Bytes empfängt. Dieser zurückgegebene Parameter zeigt für diesen Vorgang auf den DWORD-Wert 0 (null), da keine Ausgabe vorhanden ist.

lpvOverlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur .

Wenn Socket s ohne das überlappende Attribut erstellt wurde, wird der lpOverlapped-Parameter ignoriert.

Wenn s mit dem überlappenden Attribut geöffnet wurde und der lpOverlapped-Parameter nicht NULL ist, wird der Vorgang als überlappender (asynchroner) Vorgang ausgeführt. In diesem Fall muss der lpOverlapped-Parameter auf eine gültige WSAOVERLAPPED-Struktur verweisen.

Bei überlappenden Vorgängen wird die WSAIoctl - oder WSPIoctl-Funktion sofort zurückgegeben, und die entsprechende Abschlussmethode wird nach Abschluss des Vorgangs signalisiert. Andernfalls wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde oder ein Fehler auftritt.

lpCompletionRoutine

Typ: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Ein Zeiger auf die Abschlussroutine, die aufgerufen wird, wenn der Vorgang abgeschlossen wurde (bei nicht überlappenden Sockets ignoriert).

lpThreadId

Ein Zeiger auf eine WSATHREADID-Struktur , die vom Anbieter in einem nachfolgenden Aufruf von WPUQueueApc verwendet werden soll. Der Anbieter sollte die referenzierte WSATHREADID-Struktur (nicht den Zeiger auf dieselbe) speichern, bis die WPUQueueApc-Funktion zurückgegeben wird.

Hinweis Dieser Parameter gilt nur für die WSPIoctl-Funktion .

lpErrno

Ein Zeiger auf den Fehlercode.

Hinweis Dieser Parameter gilt nur für die WSPIoctl-Funktion .

Rückgabewert

Wenn der Vorgang erfolgreich abgeschlossen wird, gibt die WSAIoctl - oder WSPIoctl-Funktion null zurück.

Wenn der Vorgang fehlschlägt oder aussteht, gibt die WSAIoctl - oder WSPIoctl-FunktionSOCKET_ERROR zurück. Rufen Sie WSAGetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Fehlercode	Bedeutung
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und der Abschluss wird zu einem späteren Zeitpunkt angezeigt.
WSA_OPERATION_ABORTED	Ein überlappender Vorgang wurde aufgrund des Schließens des Sockets oder der Ausführung des SIO_FLUSH IOCTL-Befehls abgebrochen.
WSAEFAULT	Der LpOverlapped- oder lpCompletionRoutine-Parameter ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten.
WSAEINPROGRESS	Die Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird.
WSAEINTR	Ein blockierende Vorgang wurde unterbrochen.
WSAEINVAL	Der dwIoControlCode-Parameter ist kein gültiger Befehl, oder ein angegebener Eingabeparameter ist nicht akzeptabel, oder der Befehl gilt nicht für den angegebenen Sockettyp.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAENOPROTOOPT	Die Socketoption wird im angegebenen Protokoll nicht unterstützt. Dieser Fehler wird für einen Datagrammsocket zurückgegeben.
WSAENOTSOCK	Der Deskriptor s ist kein Socket.
WSAEOPNOTSUPP	Der angegebene IOCTL-Befehl wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn die SIO_KEEPALIVE_VALS IOCTL vom Transportanbieter nicht unterstützt wird.

Bemerkungen

Die SIO_KEEPALIVE_VALS IOCTL wird unter Windows 2000 und höheren Versionen des Betriebssystems unterstützt.

Der SIO_KEEPALIVE_VALS Steuercode aktiviert oder deaktiviert die Verbindungseinstellung der TCP-Keep-Alive-Option, die das TCP-Keep-Alive-Timeout und das Intervall für TCP-Keep-Alive-Pakete angibt. Weitere Informationen zur Keep-Alive-Option finden Sie im Abschnitt 4.2.3.6 unter Anforderungen für Internethosts – Kommunikationsebenen gemäß RFC 1122 auf der IETF-Website. (Diese Ressource ist möglicherweise nur in Englisch verfügbar.)

Der Parameter lpvInBuffer sollte auf eine tcp_keepalive-Struktur verweisen, die in der Mstcpip.h-Headerdatei definiert ist. Diese Struktur ist wie folgt definiert:

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

Der im onoff-Element angegebene Wert bestimmt, ob TCP Keep-Alive aktiviert oder deaktiviert ist. Wenn der onoff-Member auf einen Wert ungleich null festgelegt ist, wird TCP Keep-Alive aktiviert, und die anderen Member in der -Struktur werden verwendet. Das keepalivetime-Element gibt das Timeout in Millisekunden ohne Aktivität an, bis das erste Keep-Alive-Paket gesendet wird. Der keepaliveinterval-Member gibt in Millisekunden das Intervall an, zwischen dem aufeinanderfolgende Keep-Alive-Pakete gesendet werden, wenn keine Bestätigung empfangen wird.

Die option SO_KEEPALIVE , die eine der SOL_SOCKET Socketoptionen ist, kann auch verwendet werden, um tcp keep-alive für eine Verbindung zu aktivieren oder zu deaktivieren sowie den aktuellen Status dieser Option abzufragen. Um abzufragen, ob TCP keep-alive für einen Socket aktiviert ist, kann die getockopt-Funktion mit der Option SO_KEEPALIVE aufgerufen werden. Um TCP Keep-Alive zu aktivieren oder zu deaktivieren, kann die setockopt-Funktion mit der Option SO_KEEPALIVE aufgerufen werden. Wenn TCP keep-alive mit SO_KEEPALIVE aktiviert ist, werden die TCP-Standardeinstellungen für Keep-Alive-Timeout und Intervall verwendet, es sei denn, diese Werte wurden mithilfe von SIO_KEEPALIVE_VALS geändert.

Der systemweite Standardwert des Keep-Alive-Timeouts kann über die Registrierungseinstellung KeepAliveTime gesteuert werden, die einen Wert in Millisekunden benötigt. Wenn der Schlüssel nicht festgelegt ist, beträgt das standardmäßige Keep-Alive-Timeout 2 Stunden. Der systemweite Standardwert des Keep-Alive-Intervalls kann über die Registrierungseinstellung KeepAliveInterval gesteuert werden, die einen Wert in Millisekunden benötigt. Wenn der Schlüssel nicht festgelegt ist, beträgt das Standardmäßige Keep-Alive-Intervall 1 Sekunde.

Unter Windows Vista und höher ist die Anzahl der Keep-Alive-Tests (Datenneuübertragungen) auf 10 festgelegt und kann nicht geändert werden.

Unter Windows Server 2003, Windows XP und Windows 2000 ist die Standardeinstellung für die Anzahl der Keep-Alive-Tests 5. Die Anzahl der Keep-Alive-Tests kann über die Registrierungseinstellungen TcpMaxDataRetransmissions und PPTPTcpMaxDataRetransmissions gesteuert werden. Die Anzahl der Keep-Alive-Tests ist auf den größeren der beiden Registrierungsschlüsselwerte festgelegt. Wenn diese Zahl 0 ist, werden keep-alive-Tests nicht gesendet. Wenn diese Zahl über 255 liegt, wird sie auf 255 angepasst.