código de controle SIO_APPLY_TRANSPORT_SETTING
Descrição
O código de controle SIO_APPLY_TRANSPORT_SETTING aplica uma ou mais configurações de transporte a 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_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.
);
Parâmetros
s
Um descritor que identifica um soquete.
Dwiocontrolcode
O código de controle para a operação. Use SIO_APPLY_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 aplicada.
Cbinbuffer
O tamanho, em bytes, do buffer de entrada. Esse parâmetro depende da configuração de transporte que está sendo aplicada.
Lpvoutbuffer
Um ponteiro para o buffer de saída. Esse parâmetro depende da configuração de transporte que está sendo aplicada.
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 podem 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. O status de conclusão final pode ser recuperado quando o método de conclusão apropriado é sinalizado quando a operação é concluída.
lpvOverlapped
Um ponteiro para uma estrutura WSAOVERLAPPED .
Se 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 |
|---|---|
| WSA_IO_PENDING | A operação de E/S sobreposta está em andamento. Esse valor será retornado se uma operação sobreposta tiver sido iniciada com êxito e a conclusão será indicada posteriormente. |
| WSA_OPERATION_ABORTED | A operação de E/S foi anulada devido ao encerramento de um thread ou a uma solicitação de aplicativo. Esse erro será retornado se uma operação sobreposta tiver sido cancelada devido ao fechamento do soquete ou à execução do comando IOCTL SIO_FLUSH . |
| WSAEFAULT | O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada. Esse erro é retornado do parâmetro lpvInBuffer, 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 | Uma operação de bloqueio está atualmente em execução. Esse erro será retornado se a função for invocada quando um retorno de chamada estiver em andamento. |
| WSAEINTR | Uma operação de bloqueio foi interrompida por uma chamada para WSACancelBlockingCall. Esse erro será retornado se uma operação de bloqueio tiver sido interrompida. |
| WSAEINVAL | Foi fornecido um argumento inválido. Esse erro será retornado se o parâmetro dwIoControlCode não for um comando válido ou se um parâmetro de entrada especificado não for aceitável ou o comando não for aplicável ao tipo de soquete especificado. |
| WSAENETDOWN | Uma operação de soquete encontrou uma rede inoperante. Esse erro será retornado se o subsistema de rede falhar. |
| WSAENOTSOCK | Uma operação foi tentada em algo que não é um soquete. Esse erro será retornado se o descritor s não for um soquete. |
| WSAEOPNOTSUPP | Não há suporte para a tentativa de operação para o tipo de objeto referenciado. Esse erro será retornado se não houver suporte para o comando IOCTL especificado. Esse erro também será retornado se o SIO_APPLY_TRANSPORT_SETTING IOCTL não tiver suporte do provedor de transporte. Esse erro também é retornado quando uma tentativa de usar o SIO_APPLY_TRANSPORT_SETTING IOCTL é feita em um soquete diferente de UDP ou TCP. |
Comentários
O SIO_APPLY_TRANSPORT_SETTING IOCTL tem suporte em Windows 8 e Windows Server 2012 e versões posteriores do sistema operacional.
O SIO_APPLY_TRANSPORT_SETTING IOCTL é um IOCTL genérico usado para aplicar a configuração de transporte ao soquete. A configuração de transporte que está sendo aplicada baseia-se no TRANSPORT_SETTING_ID passado no parâmetro lpvInBuffer .
Começando com Windows 8 e Windows Server 2012, o sistema define a funcionalidade REAL_TIME_NOTIFICATION_CAPABILITY em um soquete TCP. Começando com Windows 10 e Windows Server 2016, também é definido ASSOCIATE_NAMERES_CONTEXT. Para obter mais informações, consulte addrinfoex4 e ASSOCIATE_NAMERES_CONTEXT_INPUT.
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 aplicar 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 de REAL_TIME_NOTIFICATION_SETTING_INPUT . O parâmetro lpvOutBuffer não é usado para essa operação. Essa configuração de transporte se aplica somente a soquetes TCP. Essa configuração de transporte fornece uma maneira de WinInet ou serviços de rede semelhantes marcarem um determinado soquete TCP como ControlChannelTrigger habilitado. O Windows marcará o soquete TCP correspondente e definirá as configurações de hardware e software apropriadas quando essa opção for chamada. Um aplicativo da Windows Store não chamará esse IOCTL diretamente.