Código de controle SIO_QUERY_TRANSPORT_SETTING

Artigo
06/13/2023

Descrição

O código de controle SIO_QUERY_TRANSPORT_SETTING consulta as configurações de transporte em um soquete.

Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.

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

Parâmetros

s

Um descritor que identifica um soquete.

Dwiocontrolcode

O código de controle da operação. Use SIO_QUERY_TRANSPORT_SETTING para esta operação.

Lpvinbuffer

Um ponteiro para o buffer de entrada. Esse parâmetro contém um ponteiro para uma estrutura em que o primeiro membro da estrutura é uma estrutura TRANSPORT_SETTING_ID que determina qual configuração de transporte está sendo consultada.

Cbinbuffer

O tamanho, em bytes, do buffer de entrada. Esse parâmetro depende da configuração de transporte que está sendo consultada.

Lpvoutbuffer

Um ponteiro para o buffer de saída. Esse parâmetro depende da configuração de transporte que está sendo consultada se os parâmetros lpOverlapped e lpCompletionRoutine forem NULL.

cbOutBuffer

O tamanho, em bytes, do buffer de saída.

Lpcbbytesreturned

Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados armazenados no buffer de saída.

Se o buffer de saída for muito pequeno, a chamada falhará, WSAGetLastError retornará WSAEINVAL e o parâmetro lpcbBytesReturned apontará para um valor DWORD igual a zero.

Se lpOverlapped for NULL, o valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado em uma chamada bem-sucedida não poderá ser zero.

Se o parâmetro lpOverlapped não for NULL para soquetes sobrepostos, as operações que não puderem ser concluídas imediatamente serão iniciadas e a conclusão será indicada posteriormente. O valor DWORD apontado pelo parâmetro lpcbBytesReturned retornado pode ser zero, pois o tamanho dos dados armazenados não pode ser determinado até que a operação sobreposta seja concluída. A conclusão final status pode ser recuperada quando o método de conclusão apropriado é sinalizado quando a operação é concluída.

lpvOverlapped

Um ponteiro para uma estrutura WSAOVERLAPPED .

Se o soquete s tiver sido criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.

Se s tiver sido aberto com o atributo sobreposto e o parâmetro lpOverlapped não for NULL, a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.

Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.

Lpcompletionroutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Um ponteiro para a rotina de conclusão chamado quando a operação foi concluída (ignorado para soquetes não sobrepostos).

lpThreadId

Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.

Nota Esse parâmetro se aplica somente à função WSPIoctl .

Lperrno

Um ponteiro para o código de erro.

Nota Esse parâmetro se aplica somente à função WSPIoctl .

Valor retornado

Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.

Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.

Código do erro	Significado
ERROR_INSUFFICIENT_BUFFER	A área de dados passada para uma chamada do sistema é muito pequena. Esse erro será retornado se o buffer apontado pelo parâmetro lpvOutBuffer com um tamanho de buffer passado no parâmetro cbOutBuffer for muito pequeno. O tamanho do buffer necessário será retornado no parâmetro lpcbBytesReturned .
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente.
WSA_OPERATION_ABORTED	Uma operação sobreposta foi cancelada devido ao fechamento do soquete ou à execução do SIO_FLUSH comando IOCTL .
WSAEFAULT	O parâmetro lpvOutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário.
WSAEINPROGRESS	A função é invocada quando um retorno de chamada está em andamento.
WSAEINTR	Uma operação de bloqueio foi interrompida.
WSAEINVAL	O parâmetro dwIoControlCode não é um comando válido ou um parâmetro de entrada especificado não é aceitável ou o comando não é aplicável ao tipo de soquete especificado.
WSAENETDOWN	O subsistema de rede falhou.
WSAENOPROTOOPT	Não há suporte para a opção de soquete no protocolo especificado.
WSAENOTCONN	O soquete s não está conectado.
WSAENOTSOCK	O descritor s não é um soquete.
WSAEOPNOTSUPP	Não há suporte para o comando IOCTL especificado. Esse erro será retornado se o SIO_QUERY_TRANSPORT_SETTING IOCTL não tiver suporte do provedor de transporte.

Comentários

O SIO_QUERY_TRANSPORT_SETTING IOCTL tem suporte em Windows 8 e Windows Server 2012 e versões posteriores do sistema operacional.

O SIO_QUERY_TRANSPORT_SETTING IOCTL é um IOCTL genérico usado para consultar as configurações de transporte em um soquete. A configuração de transporte que está sendo consultada baseia-se no TRANSPORT_SETTING_ID passado no parâmetro lpvInBuffer .

A única configuração de transporte definida atualmente é para a funcionalidade REAL_TIME_NOTIFICATION_CAPABILITY em um soquete TCP.

Se o TRANSPORT_SETTING_ID passado no parâmetro lpvInBuffer tiver o membro Guid definido como REAL_TIME_NOTIFICATION_CAPABILITY, essa será uma solicitação para consultar as configurações de notificação em tempo real para o soquete TCP usado com o ControlChannelTrigger para receber notificações de rede em segundo plano em um aplicativo da Windows Store. O parâmetro lpvInBuffer deve apontar para uma estrutura TRANSPORT_SETTING_ID . O parâmetro lpvOutBuffer deve apontar para uma estrutura REAL_TIME_NOTIFICATION_SETTING_OUTPUT . Essa configuração de transporte se aplica somente a soquetes TCP. Essa configuração de transporte fornece uma maneira para o WinInet ou serviços de rede semelhantes consultarem um determinado soquete TCP para determinar o status ControlChannelTrigger. Um aplicativo da Windows Store não chamará esse IOCTL diretamente. Se a chamada WSAIoctl ou WSPIoctl for bem-sucedida, essa IOCTL retornará uma estrutura REAL_TIME_NOTIFICATION_SETTING_OUTPUT com o status atual.

O SIO_QUERY_TRANSPORT_SETTING IOCTL fornece uma maneira para o WinInet ou serviços de rede semelhantes consultarem a configuração de transporte status para um determinado soquete TCP para determinar se ControlChannelTrigger está habilitado no soquete. Um aplicativo da Windows Store não chamará esse IOCTL diretamente.

Esse IOCTL se aplica somente a soquetes TCP.