SIO_QUERY_TRANSPORT_SETTING-Steuerelementcode

Artikel
06/13/2023

BESCHREIBUNG

Der SIO_QUERY_TRANSPORT_SETTING-Steuerelementcode fragt die Transporteinstellungen für einen Socket ab.

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_QUERY_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 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_QUERY_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 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_QUERY_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 abgefragt wird.

cbInBuffer

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

lpvOutBuffer

Ein Zeiger auf den Ausgabepuffer. Dieser Parameter hängt von der Transporteinstellung ab, die abgefragt wird, wenn die Parameter lpOverlapped und lpCompletionRoutineNULL sind.

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
ERROR_INSUFFICIENT_BUFFER	Der an einen Systemaufruf übergebene Datenbereich ist zu klein. Dieser Fehler wird zurückgegeben, wenn der Puffer, auf den der Parameter lpvOutBuffer verweist, mit einer Puffergröße, die im cbOutBuffer-Parameter übergeben wird, zu klein ist. Die erforderliche Puffergröße wird im parameter lpcbBytesReturned zurückgegeben.
WSA_IO_PENDING	Ein überlappender Vorgang wurde erfolgreich eingeleitet, 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 Parameter lpvOutBuffer, lpcbBytesReturned, lpOverlapped oder lpCompletionRoutine 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 Blockierungsvorgang 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	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAENOPROTOOPT	Die Socketoption wird für das angegebene 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 die SIO_QUERY_TRANSPORT_SETTING IOCTL vom Transportanbieter nicht unterstützt wird.

Bemerkungen

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

Die SIO_QUERY_TRANSPORT_SETTING IOCTL ist eine generische IOCTL, die zum Abfragen der Transporteinstellungen für einen Socket verwendet wird. Die abgefragte Transporteinstellung basiert auf dem im lpvInBuffer-Parameter übergebenen TRANSPORT_SETTING_ID.

Die einzige Transporteinstellung, die derzeit definiert wird, ist für die REAL_TIME_NOTIFICATION_CAPABILITY-Funktion auf einem TCP-Socket.

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 zum Abfragen der Echtzeitbenachrichtigungseinstellungen für den TCP-Socket, der mit controlChannelTrigger zum Empfangen von Hintergrundnetzwerkbenachrichtigungen in einer Windows Store-App verwendet wird. Der lpvInBuffer-Parameter sollte auf eine TRANSPORT_SETTING_ID Struktur verweisen. Der lpvOutBuffer-Parameter sollte auf eine REAL_TIME_NOTIFICATION_SETTING_OUTPUT Struktur verweisen. Diese Transporteinstellung gilt nur für TCP-Sockets. Diese Transporteinstellung bietet winInet oder ähnlichen Netzwerkdiensten die Möglichkeit, einen bestimmten TCP-Socket abzufragen, um die ControlChannelTrigger-status zu bestimmen. Eine Windows Store-App ruft diese IOCTL nicht direkt auf. Wenn der WSAIoctl- oder WSPIoctl-Aufruf erfolgreich ist, gibt diese IOCTL eine REAL_TIME_NOTIFICATION_SETTING_OUTPUT-Struktur mit dem aktuellen status zurück.

Die SIO_QUERY_TRANSPORT_SETTING IOCTL bietet WinInet oder ähnlichen Netzwerkdiensten die Möglichkeit, die Transporteinstellung status für einen bestimmten TCP-Socket abzufragen, um zu bestimmen, ob ControlChannelTrigger für den Socket aktiviert ist. Eine Windows Store-App ruft diese IOCTL nicht direkt auf.

Diese IOCTL gilt nur für TCP-Sockets.