SIO_QUERY_TRANSPORT_SETTING codice di controllo

Articolo
06/12/2023

Descrizione

Il codice di controllo SIO_QUERY_TRANSPORT_SETTING esegue una query sulle impostazioni di trasporto in un socket.

Per eseguire questa operazione, chiamare la funzione WSAIoctl o WSPIoctl con i parametri seguenti.

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.
);

Parametri

s

Descrittore che identifica un socket.

dwIoControlCode

Codice di controllo per l'operazione. Usare SIO_QUERY_TRANSPORT_SETTING per questa operazione.

lpvInBuffer

Puntatore al buffer di input. Questo parametro contiene un puntatore a una struttura in cui il primo membro della struttura è una struttura TRANSPORT_SETTING_ID che determina l'impostazione di trasporto in cui viene eseguita una query.

cbInBuffer

Dimensioni, in byte, del buffer di input. Questo parametro dipende dall'impostazione di trasporto sottoposta a query.

lpvOutBuffer

Puntatore al buffer di output. Questo parametro dipende dall'impostazione di trasporto da eseguire una query se i parametri lpOverlapped e lpCompletionRoutine sono NULL.

cbOutBuffer

Dimensioni, in byte, del buffer di output.

lpcbBytesReturned

Puntatore a una variabile che riceve le dimensioni, in byte, dei dati archiviati nel buffer di output.

Se il buffer di output è troppo piccolo, la chiamata ha esito negativo, WSAGetLastError restituisce WSAEINVAL e il parametro lpcbBytesReturned punta a un valore DWORD pari a zero.

Se lpOverlapped è NULL, il valore DWORD puntato al parametro lpcbBytesReturned restituito in una chiamata riuscita non può essere zero.

Se il parametro lpOverlapped non è NULL per i socket sovrapposti, le operazioni che non possono essere completate immediatamente verranno avviate e il completamento verrà indicato in un secondo momento. Il valore DWORD indicato dal parametro lpcbBytesReturned restituito può essere zero poiché le dimensioni dei dati archiviati non possono essere determinate fino al completamento dell'operazione sovrapposta. Lo stato di completamento finale può essere recuperato quando il metodo di completamento appropriato viene segnalato al termine dell'operazione.

lpvOverlapped

Puntatore a una struttura WSAOVERLAPPED .

Se il socket s è stato creato senza l'attributo sovrapposto, il parametro lpOverlapped viene ignorato .

Se s è stato aperto con l'attributo sovrapposto e il parametro lpOverlapped non è NULL, l'operazione viene eseguita come operazione sovrapposta (asincrona). In questo caso, il parametro lpOverlapped deve puntare a una struttura WSAOVERLAPPED valida.

Per le operazioni sovrapposte, la funzione WSAIoctl o WSPIoctl restituisce immediatamente e il metodo di completamento appropriato viene segnalato al termine dell'operazione. In caso contrario, la funzione non restituisce finché l'operazione non è stata completata o si verifica un errore.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntatore alla routine di completamento chiamata quando l'operazione è stata completata (ignorata per socket non sovrapposti).

lpThreadId

Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID a cui fa riferimento (non lo stesso puntatore) fino a quando la funzione WPUQueueApc restituisce.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

lpErrno

Puntatore al codice di errore.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

Valore restituito

Se l'operazione viene completata correttamente, la funzione WSAIoctl o WSPIoctl restituisce zero.

Se l'operazione ha esito negativo o è in sospeso, la funzione WSAIoctl o WSPIoctl restituisce SOCKET_ERROR. Per ottenere informazioni sull'errore estese, chiamare WSAGetLastError.

Codice di errore	Significato
ERROR_INSUFFICIENT_BUFFER	L'area dati passata a una chiamata di sistema è troppo piccola. Questo errore viene restituito se il buffer puntato al parametro lpvOutBuffer con dimensioni del buffer passate nel parametro cbOutBuffer è troppo piccolo. Le dimensioni del buffer necessarie verranno restituite nel parametro lpcbBytesReturned .
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSA_OPERATION_ABORTED	Un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando IOCTL SIO_FLUSH .
WSAEFAULT	Il parametro lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio indirizzi utente.
WSAEINPROGRESS	La funzione viene richiamata quando un callback è in corso.
WSAEINTR	Un'operazione di blocco è stata interrotta.
WSAEINVAL	Il parametro dwIoControlCode non è un comando valido o un parametro di input specificato non è accettabile oppure il comando non è applicabile al tipo di socket specificato.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOPROTOOPT	L'opzione socket non è supportata nel protocollo specificato.
WSAENOTCONN	Il socket s non è connesso.
WSAENOTSOCK	Il descrittore s non è un socket.
WSAEOPNOTSUPP	Il comando IOCTL specificato non è supportato. Questo errore viene restituito se il SIO_QUERY_TRANSPORT_SETTING IOCTL non è supportato dal provider di trasporto.

Commenti

Il SIO_QUERY_TRANSPORT_SETTING IOCTL è supportato in Windows 8 e Windows Server 2012 e versioni successive del sistema operativo.

Il SIO_QUERY_TRANSPORT_SETTING IOCTL è un IOCTL generico usato per eseguire query sulle impostazioni di trasporto in un socket. L'impostazione di trasporto sottoposta a query è basata sul TRANSPORT_SETTING_ID passato nel parametro lpvInBuffer .

L'unica impostazione di trasporto attualmente definita è per la funzionalità di REAL_TIME_NOTIFICATION_CAPABILITY in un socket TCP.

Se il TRANSPORT_SETTING_ID passato nel parametro lpvInBuffer ha il membro Guid impostato su REAL_TIME_NOTIFICATION_CAPABILITY, si tratta di una richiesta per eseguire query sulle impostazioni di notifica in tempo reale per il socket TCP usato con ControlChannelTrigger per ricevere notifiche di rete in background in un'app di Windows Store. Il parametro lpvInBuffer deve puntare a una struttura TRANSPORT_SETTING_ID . Il parametro lpvOutBuffer deve puntare a una struttura REAL_TIME_NOTIFICATION_SETTING_OUTPUT . Questa impostazione di trasporto si applica solo ai socket TCP. Questa impostazione di trasporto consente a WinInet o a servizi di rete simili di eseguire query su un determinato socket TCP per determinare lo stato controlChannelTrigger . Un'app di Windows Store non chiamerà direttamente questo IOCTL. Se la chiamata WSAIoctl o WSPIoctl ha esito positivo, questo IOCTL restituisce una struttura REAL_TIME_NOTIFICATION_SETTING_OUTPUT con lo stato corrente.

Il SIO_QUERY_TRANSPORT_SETTING IOCTL consente a WinInet o a servizi di rete simili di eseguire query sullo stato dell'impostazione del trasporto per un determinato socket TCP per determinare se ControlChannelTrigger è abilitato nel socket. Un'app di Windows Store non chiamerà direttamente questo IOCTL.

Questo IOCTL si applica solo ai socket TCP.