SIO_APPLY_TRANSPORT_SETTING-Steuerelementcode

Artikel
06/13/2023

BESCHREIBUNG

Der SIO_APPLY_TRANSPORT_SETTING-Steuerelementcode wendet eine oder mehrere Transporteinstellungen auf einen Socket an.

Rufen Sie zum Ausführen dieses Vorgangs die Funktion WSAIoctl oder WSPIoctl mit den folgenden Parametern auf.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to the output buffer
  (DWORD) cbOutBuffer,   // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING .

lpvInBuffer

Ein Zeiger auf den Eingabepuffer. Dieser Parameter enthält einen Zeiger auf eine Struktur, bei der das erste Element der Struktur eine TRANSPORT_SETTING_ID Struktur ist, die bestimmt, welche Transporteinstellung angewendet wird.

cbInBuffer

Die Größe des Eingabepuffers in Bytes. Dieser Parameter hängt von der angewendeten Transporteinstellung ab.

lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer. Dieser Parameter hängt von der angewendeten Transporteinstellung ab.

cbOutBuffer

Die Größe des Ausgabepuffers in Bytes.

lpcbBytesReturned

Ein Zeiger auf eine Variable, die die Größe der im Ausgabepuffer gespeicherten Daten in Bytes empfängt.

Wenn der Ausgabepuffer zu klein ist, schlägt der Aufruf fehl, WSAGetLastError gibt WSAEINVAL zurück, und der lpcbBytesReturned-Parameter verweist auf einen DWORD-Wert von 0.

Wenn lpOverlappedNULL ist, kann der DWORD-Wert , auf den der parameter lpcbBytesReturned verweist, der bei einem erfolgreichen Aufruf zurückgegeben wird, nicht 0 sein.

Wenn der lpOverlapped-Parameter für überlappende Sockets nicht NULL ist, werden Vorgänge initiiert, die nicht sofort abgeschlossen werden können, und die Vervollständigung wird zu einem späteren Zeitpunkt angezeigt. Der vom zurückgegebenen parameter lpcbBytesReturned angegebene DWORD-Wert kann 0 sein, da die Größe der gespeicherten Daten erst bestimmt werden kann, wenn der überlappende Vorgang abgeschlossen ist. Die endgültige Vervollständigung status kann abgerufen werden, wenn die entsprechende Vervollständigungsmethode signalisiert wird, wenn der Vorgang abgeschlossen 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 Vervollständigungsmethode 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 Vervollständigungsroutine, 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 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 wurde, 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	Der überlappende E/A-Vorgang wird ausgeführt. Dieser Wert wird zurückgegeben, wenn ein überlappender Vorgang erfolgreich initiiert wurde und der Abschluss zu einem späteren Zeitpunkt angezeigt wird.
WSA_OPERATION_ABORTED	Der E/A-Vorgang wurde wegen eines Threadendes oder einer Anwendungsanforderung abgebrochen. Dieser Fehler wird zurückgegeben, wenn ein überlappender Vorgang aufgrund des Schließens des Sockets oder der Ausführung des SIO_FLUSH IOCTL-Befehls abgebrochen wurde.
WSAEFAULT	Das System hat beim Versuch, ein Zeigerargument in einem Aufruf zu verwenden, eine ungültige Zeigeradresse erkannt. Dieser Fehler wird zurückgegeben, wenn der Parameter lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped oder lpCompletionRoutine nicht vollständig in einem gültigen Teil des Benutzeradressraums enthalten ist.
WSAEINPROGRESS	Ein Blockierungsvorgang wird momentan ausgeführt. Dieser Fehler wird zurückgegeben, wenn die Funktion aufgerufen wird, wenn ein Rückruf ausgeführt wird.
WSAEINTR	Ein blockierender Vorgang wurde durch einen Aufruf von WSACancelBlockingCall unterbrochen. Dieser Fehler wird zurückgegeben, wenn ein blockierende Vorgang unterbrochen wurde.
WSAEINVAL	Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn der dwIoControlCode-Parameter kein gültiger Befehl ist, ein angegebener Eingabeparameter nicht akzeptabel ist oder der Befehl nicht auf den angegebenen Sockettyp anwendbar ist.
WSAENETDOWN	Bei einem Socketvorgang war das Netzwerk inaktiv. Dieser Fehler wird zurückgegeben, wenn für das Netzwerksubsystem ein Fehler aufgetreten ist.
WSAENOTSOCK	Es wurde ein Vorgang für etwas versucht, das kein Socket ist. Dieser Fehler wird zurückgegeben, wenn der Deskriptor s kein Socket ist.
WSAEOPNOTSUPP	Der versuchte Vorgang wird für den Typ des Objekts, auf das verwiesen wird, nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der angegebene IOCTL-Befehl nicht unterstützt wird. Dieser Fehler wird auch zurückgegeben, wenn die SIO_APPLY_TRANSPORT_SETTING IOCTL vom Transportanbieter nicht unterstützt wird. Dieser Fehler wird auch zurückgegeben, wenn versucht wird, die SIO_APPLY_TRANSPORT_SETTING IOCTL für einen anderen Socket als UDP oder TCP zu verwenden.

Bemerkungen

Die SIO_APPLY_TRANSPORT_SETTING IOCTL wird auf Windows 8 und Windows Server 2012 und höheren Versionen des Betriebssystems unterstützt.

Die SIO_APPLY_TRANSPORT_SETTING IOCTL ist eine generische IOCTL, die zum Anwenden der Transporteinstellung auf den Socket verwendet wird. Die angewendete Transporteinstellung basiert auf dem im lpvInBuffer-Parameter übergebenen TRANSPORT_SETTING_ID.

Ab Windows 8 und Windows Server 2012 definiert das System die REAL_TIME_NOTIFICATION_CAPABILITY-Funktion für einen TCP-Socket. Ab Windows 10 und Windows Server 2016 wird auch ASSOCIATE_NAMERES_CONTEXT definiert. Weitere Informationen finden Sie unter addrinfoex4 und ASSOCIATE_NAMERES_CONTEXT_INPUT.

Wenn für die im Parameter lpvInBuffer übergebene TRANSPORT_SETTING_ID das Guid-Element auf REAL_TIME_NOTIFICATION_CAPABILITY festgelegt ist, ist dies eine Anforderung, Echtzeitbenachrichtigungseinstellungen für den TCP-Socket anzuwenden, der mit controlChannelTrigger verwendet wird, um Hintergrundnetzwerkbenachrichtigungen in einer Windows Store-App zu empfangen. Der lpvInBuffer-Parameter sollte auf eine REAL_TIME_NOTIFICATION_SETTING_INPUT Struktur verweisen. Der lpvOutBuffer-Parameter wird für diesen Vorgang nicht verwendet. Diese Transporteinstellung gilt nur für TCP-Sockets. Diese Transporteinstellung bietet eine Möglichkeit für WinInet oder ähnliche Netzwerkdienste, einen bestimmten TCP-Socket als ControlChannelTrigger aktiviert zu markieren. Windows markiert den entsprechenden TCP-Socket und konfiguriert die entsprechenden Hardware- und Softwareeinstellungen, wenn diese Option aufgerufen wird. Eine Windows Store-App ruft diese IOCTL nicht direkt auf.