SIO_IDEAL_SEND_BACKLOG_CHANGE-Steuerungscode

Artikel
10/13/2023

Beschreibung

Der Steuerungscode SIO_IDEAL_SEND_BACKLOG_CHANGE benachrichtigt eine Anwendung, wenn sich der ISB-Wert (Ideal Send Backlog) für die Verbindung ändert.

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_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  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_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  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 Steuerungscode für den Vorgang. Verwenden Sie SIO_IDEAL_SEND_BACKLOG_CHANGE für diesen Vorgang.

lpvInBuffer

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

cbInBuffer

Die Größe des Eingabepuffers in Byte. Dieser Parameter wird für diesen Vorgang nicht verwendet.

lpvOutBuffer

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

cbOutBuffer

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

lpcbBytesReturned

Ein Zeiger auf eine Variable, die die Größe der im Ausgabepuffer gespeicherten Daten in Byte empfängt. Dieser zurückgegebene Parameter verweist für diesen Vorgang auf einen DWORD-Wert von Null, da keine Ausgabe vorhanden ist.

lpvOverlapped

Ein Zeiger auf eine WSAOVERLAPPED-Struktur.

Wenn der Socket s ohne das Attribut für „überlappend“ erstellt wurde, wird der Parameter lpOverlapped ignoriert.

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

Bei überlappenden Vorgängen gibt die Funktion WSAIoctl bzw. WSPIoctl die Steuerung sofort zurück, und die entsprechende Abschlussmethode wird signalisiert, wenn der Vorgang abgeschlossen worden ist. 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 worden ist (wird 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 die Steuerung zurückgibt.

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 worden ist, gibt die Funktion WSAIoctl oder WSPIoctl null zurück.

Wenn der Vorgang fehlschlägt oder aussteht, gibt die Funktion WSAIoctl bzw. WSPIoctl den Fehler SOCKET_ERROR zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie WSAGetLastError auf.

Fehlercode	Bedeutung
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich initiiert, und sein Abschluss wird zu einem späteren Zeitpunkt angegeben.
WSA_OPERATION_ABORTED	Ein überlappender Vorgang wurde abgebrochen, weil der Socket geschlossen oder der IOCTL-Befehl SIO_FLUSH ausgeführt wurde.
WSAEFAULT	Der Parameter lpOverlapped oder lpCompletionRoutine ist nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten.
WSAEINPROGRESS	Diese Funktion wird aufgerufen, wenn ein Rückruf ausgeführt wird.
WSAEINTR	Ein Blockierungsvorgang wurde unterbrochen.
WSAEINVAL	Der Parameter dwIoControlCode ist kein gültiger Befehl, oder ein angegebener Eingabeparameter ist nicht akzeptabel, oder der Befehl gilt nicht für den angegebenen Sockettyp. Dieser Fehler wird zurückgegeben, wenn der Parameter cbOutBuffer nicht null ist.
WSAENETDOWN	Im Netzwerksubsystems ist ein Fehler aufgetreten.
WSAENOPROTOOPT	Die Socketoption wird vom angegebenen Protokoll nicht unterstützt.
WSAENOTCONN	Der Socket s ist nicht verbunden.
WSAENOTSOCK	Der Deskriptor s ist kein Socket.
WSAEOPNOTSUPP	Der angegebene IOCTL-Befehl wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE vom Transportanbieter nicht unterstützt wird. Dieser Fehler wird auch zurückgegeben, wenn versucht wird, den IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE für einen Datagrammsocket zu verwenden.

Hinweise

Der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE wird unter Windows Server 2008, Windows Vista mit Service Pack 1 (SP1) und höheren Versionen des Betriebssystems unterstützt.

Beim Senden von Daten über eine TCP-Verbindung mit Windows-Sockets ist es wichtig, eine ausreichende Menge an ausstehenden (gesendeten, aber noch nicht bestätigten) Daten in TCP zu halten, um den höchsten Durchsatz zu erzielen. Der ideale Wert für die ausstehende Datenmenge, um den besten Durchsatz für die TCP-Verbindung zu erzielen, wird als ISB-Größe (Ideal Send Backlog) bezeichnet. Der ISB-Wert ist eine Funktion des Produkts von Bandbreite und Verzögerung der TCP-Verbindung und des angekündigten Empfangsfensters des Empfängers (sowie teilweise des Grades der Netzwerküberlastung).

Der ISB-Wert pro Verbindung ist über die TCP-Protokollimplementierung in Windows Server 2008, Windows Vista mit SP1 und höheren Versionen des Betriebssystems verfügbar. Der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE kann von einer Anwendung verwendet werden, um eine Benachrichtigung zu erhalten, wenn sich der ISB-Wert dynamisch für eine Verbindung ändert.

Unter Windows Server 2008, Windows Vista mit SP1 und höheren Versionen des Betriebssystems werden die IOCTL-Befehle SIO_IDEAL_SEND_BACKLOG_CHANGE und SIO_IDEAL_SEND_BACKLOG_QUERY in streamorientierten Sockets, die einen verbundenen Status haben, unterstützt.

Der Bereich für den ISB-Wert für eine TCP-Verbindung kann theoretisch von 0 bis maximal 16 MB variieren.

Weitere Informationen zur typischen Verwendung des ISB-Mechanismus, um einen besseren Durchsatz über Verbindungen mit hohem Bandbreite-Verzögerung-Produkt zu erzielen, finden Sie auf der IOCTL-Referenzseite SIO_IDEAL_SEND_BACKLOG_QUERY.

Der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE ist nur für Streamsockets zulässig, die sich im verbundenen Zustand befinden. Andernfalls schlägt die Funktion WSAIoctl bzw. WSPIoctl mit dem Fehlercode WSAENOTCONN fehl.

Der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE verwendet weder Eingabe- noch Ausgabepuffer und wartet oder blockiert, bis eine ISB-Änderung in der zugrundeliegenden Verbindung auftritt. Wenn dieser IOCTL-Befehl abgeschlossen ist, können Winsock-Anwendungen mit dem IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_QUERY den neuen ISB-Wert für die Verbindung abrufen.

Der nicht blockierende Modus wird vom IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE nicht unterstützt. Anwendungen dürfen diesen IOCTL-Befehl für einen nicht blockierenden Socket aufrufen, doch der IOCTL-Befehl wird einfach blockiert oder angehalten, bis sich der ISB-Wert ändert.

Wenn die beiden Parameter lpOverlapped und lpCompletionRoutine NULL sind, wird der Socket in dieser Funktion als nicht überlappender Socket behandelt. Bei einem nicht überlappenden Socket werden die Parameter lpOverlapped und lpCompletionRoutine ignoriert, nur kann die Funktion blockieren, wenn beim Socket s der Blockierungsmodus aktiv ist. Selbst wenn beim Socket s der Blockierungsmodus nicht aktiv ist, wird diese Funktion blockiert, da dieser spezielle IOCTL-Befehl den nicht blockierenden Modus nicht unterstützt.

Bei überlappenden Sockets werden Vorgänge initiiert, die nicht sofort abgeschlossen werden können, und der Abschluss wird zu einem späteren Zeitpunkt angegeben.

Jeder IOCTL-Befehl kann je nach Implementierung des Dienstanbieters unbegrenzt blockiert werden. Wenn die Anwendung das Blockieren in einem Funktionsaufruf von WSAIoctl oder WSPIoctl nicht tolerieren kann, werden für IOCTL-Befehle, die besonders hoher Wahrscheinlichkeit blockiert werden, überlappende E/A-Vorgänge empfohlen.

Der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE stellt eine Benachrichtigung bereit und soll blockiert oder angehalten werden, bis sich der ISB-Wert ändert. Daher wird er häufig asynchron aufgerufen, wobei der Parameter lpOverlapped auf eine gültige WSAOVERLAPPED-Struktur festgelegt wird.

Der IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE kann in den folgenden Fällen mit dem Fehlercode WSAEINTR oder WSA_OPERATION_ABORTED fehlschlagen:

Die TCP-Verbindung wird in Senderichtung ordnungsgemäß getrennt. Dies kann das Ergebnis eines Aufrufs der shutdown-Funktion, deren how-Parameter auf SD_SEND festgelegt ist, eines Aufruf der DisconnectEx-Funktion oder eines Aufrufs der TransmissionFile- oder TransmitPackets-Funktion sein, wobei der dwFlags-Parameter auf TF_DISCONNECT oder TF_REUSE festgelegt ist.
Die TCP-Verbindung wurde zurückgesetzt oder abgebrochen.
Die Anwendung ruft den IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE auf, wenn bereits eine ausstehende Benachrichtigungsanforderung vorhanden ist. Zu einem gegebenen Zeitpunkt ist jeweils nur eine ausstehende SIO_IDEAL_SEND_BACKLOG_CHANGE-Anforderung zulässig.
Die Anforderung wird vom E/A-Manager abgebrochen.
Der Socket wird geschlossen.

In der Headerdatei Ws2tcpip.h sind zwei Inlinewrapperfunktionen für diese IOCTL-Befehle definiert. Es wird empfohlen, diese Inlinefunktionen zu verwenden, statt die IOCTL-Befehle SIO_IDEAL_SEND_BACKLOG_CHANGE und SIO_IDEAL_SEND_BACKLOG_QUERY direkt aufzurufen.

Die Funktion idealsendbacklognotify ist die Inlinewrapperfunktion für den IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_CHANGE.

Die Funktion idealsendbacklogquery ist die Inlinewrapperfunktion für den IOCTL-Befehl SIO_IDEAL_SEND_BACKLOG_QUERY.