Função WSAIoctl (winsock2.h)
A função WSAIoctl controla o modo de um soquete.
Sintaxe
int WSAAPI WSAIoctl(
[in] SOCKET s,
[in] DWORD dwIoControlCode,
[in] LPVOID lpvInBuffer,
[in] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Parâmetros
[in] s
Um descritor que identifica um soquete.
[in] dwIoControlCode
O código de controle da operação a ser executada. Consulte Winsock IOCTLs.
[in] lpvInBuffer
Um ponteiro para o buffer de entrada.
[in] cbInBuffer
O tamanho, em bytes, do buffer de entrada.
[out] lpvOutBuffer
Um ponteiro para o buffer de saída.
[in] cbOutBuffer
O tamanho, em bytes, do buffer de saída.
[out] lpcbBytesReturned
Um ponteiro para o número real de bytes de saída.
[in] lpOverlapped
Um ponteiro para uma estrutura WSAOVERLAPPED (ignorado para soquetes não sobrepostos).
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valor retornado
Após a conclusão bem-sucedida, o WSAIoctl retorna zero. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico poderá ser recuperado chamando WSAGetLastError.
| Código do erro | Significado |
|---|---|
| Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. | |
| O subsistema de rede falhou. | |
| O 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 ou o parâmetro cbInBuffer ou cbOutBuffer é muito pequeno. | |
| 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. | |
| A função é invocada quando um retorno de chamada está em andamento. | |
| O descritor s não é um soquete. | |
| O comando IOCTL especificado não pode ser realizado. (Por exemplo, as estruturas FLOWSPEC especificadas em SIO_SET_QOS ou SIO_SET_GROUP_QOS não podem ser atendidas.) | |
| O soquete é marcado como sem bloqueio e a operação solicitada seria bloqueada. | |
| Não há suporte para a opção de soquete no protocolo especificado. Por exemplo, uma tentativa de usar o SIO_GET_BROADCAST_ADDRESS IOCTL foi feita em um soquete IPv6 ou uma tentativa de usar o TCP SIO_KEEPALIVE_VALS IOCTL foi feita em um soquete de datagrama. |
Comentários
A função WSAIoctl é usada para definir ou recuperar parâmetros operacionais associados ao soquete, ao protocolo de transporte ou ao subsistema de comunicações.
Se lpOverlapped e lpCompletionRoutine forem NULL, o soquete nessa função será tratado como um soquete não sobreposto. Para um soquete não sobreposto, os parâmetros lpOverlapped e lpCompletionRoutine são ignorados, o que faz com que a função se comporte como a função ioctlsocket padrão, exceto que a função pode bloquear se o soquete s estiver no modo de bloqueio. Se o soquete s estiver no modo sem bloqueio, essa função poderá retornar WSAEWOULDBLOCK quando a operação especificada não puder ser concluída imediatamente. Nesse caso, o aplicativo pode alterar o soquete para o modo de bloqueio e reemissar a solicitação ou aguardar o evento de rede correspondente (como FD_ROUTING_INTERFACE_CHANGE ou FD_ADDRESS_LIST_CHANGE no caso de SIO_ROUTING_INTERFACE_CHANGE ou SIO_ADDRESS_LIST_CHANGE) usando uma mensagem do Windows (usando wsaAsyncSelect) baseada em evento (usando o mecanismo de notificação baseado em WSAEventSelect).
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 ignorado. A conclusão final status e bytes retornados podem ser recuperados quando o método de conclusão apropriado é sinalizado quando a operação é concluída.
Qualquer IOCTL pode ser bloqueada indefinidamente, dependendo da implementação do provedor de serviços. Se o aplicativo não puder tolerar o bloqueio em uma chamada WSAIoctl , a E/S sobreposta será aconselhada para IOCTLs que são especialmente propensas a bloquear, incluindo:
SIO_ADDRESS_LIST_CHANGE
SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_SET_QOS
SIO_SET_GROUP_QOS
Algumas IOCTLs específicas do protocolo também podem ser especialmente propensas a serem bloqueadas. Verifique se há informações disponíveis no anexo específico do protocolo relevante.
O protótipo para a rotina de conclusão apontada pelo parâmetro lpCompletionRoutine é o seguinte:
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
void CALLBACK CompletionRoutine (
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
A CompletionRoutine é um espaço reservado para um nome de função fornecido pelo aplicativo. O parâmetro dwError especifica o status de conclusão para a operação sobreposta, conforme indicado pelo parâmetro lpOverlapped. O parâmetro cbTransferred especifica o número de bytes recebidos. O parâmetro dwFlags não é usado para este IOCTL. A rotina de conclusão não retorna um valor.
É possível adotar um esquema de codificação que preserva os opcodes ioctlsocket definidos no momento, fornecendo uma maneira conveniente de particionar o espaço do identificador opcode tanto quanto o parâmetro dwIoControlCode agora é uma entidade de 32 bits. O parâmetro dwIoControlCode é criado para permitir a independência do protocolo e do fornecedor ao adicionar novos códigos de controle, mantendo a compatibilidade com versões anteriores com os códigos de controle Windows Sockets 1.1 e Unix. O parâmetro dwIoControlCode tem o seguinte formato.
| I | O | V | T | Família de fornecedores/endereços | Código |
|---|---|---|---|---|---|
| 3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
| 1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
O será definido se o buffer de saída for válido para o código, como com IOC_OUT. Códigos de controle usando buffers de entrada e saída definem E/S.
V será definido se não houver parâmetros para o código, como com IOC_VOID.
T é uma quantidade de 2 bits que define o tipo do IOCTL. Os seguintes valores são definidos:
0 O IOCTL é um código IOCTL unix padrão, como com FIONREAD e FIONBIO.
1 O IOCTL é um código IOCTL genérico do Windows Sockets 2. Novos códigos IOCTL definidos para Windows Sockets 2 terão T == 1.
2 O IOCTL aplica-se somente a uma família de endereços específica.
3 O IOCTL aplica-se somente a um provedor de fornecedor específico, como acontece com IOC_VENDOR. Esse tipo permite que as empresas sejam atribuídas a um número de fornecedor que aparece no parâmetro da família Vendor/Address . Em seguida, o fornecedor pode definir novas IOCTLs específicas para esse fornecedor sem precisar registrar o IOCTL com uma casa de compensação, fornecendo assim flexibilidade e privacidade ao fornecedor.
Família de fornecedores/endereços Uma quantidade de 11 bits que define o fornecedor que possui o código (se T == 3) ou que contém a família de endereços à qual o código se aplica (se T == 2). Se esse for um código IOCTL unix (T == 0), esse parâmetro terá o mesmo valor que o código no Unix. Se esse for um IOCTL genérico do Windows Sockets 2 (T == 1), esse parâmetro poderá ser usado como uma extensão do parâmetro de código para fornecer valores de código adicionais.
Código A quantidade de 16 bits que contém o código IOCTL específico para a operação.
Há suporte para os seguintes códigos IOCTL do Unix (comandos).
Há suporte para os seguintes comandos do Windows Sockets 2.
Se uma operação sobreposta for concluída imediatamente, WSAIoctl retornará um valor igual a zero e o parâmetro lpcbBytesReturned será atualizado com o número de bytes no buffer de saída. Se a operação sobreposta for iniciada com êxito e for concluída posteriormente, essa função retornará SOCKET_ERROR e indicará o código de erro WSA_IO_PENDING. Nesse caso, lpcbBytesReturned não é atualizado. Quando a operação sobreposta conclui a quantidade de dados no buffer de saída é indicada por meio do parâmetro cbTransferred na rotina de conclusão (se especificada) ou por meio do parâmetro lpcbTransfer no WSAGetOverlappedResult.
Quando chamado com um soquete sobreposto, o parâmetro lpOverlapped deve ser válido durante a operação sobreposta. O parâmetro lpOverlapped contém o endereço de uma estrutura WSAOVERLAPPED .
Se o parâmetro lpCompletionRoutine for NULL, o parâmetro hEvent de lpOverlapped será sinalizado quando a operação sobreposta for concluída se contiver um identificador de objeto de evento válido. Um aplicativo pode usar WSAWaitForMultipleEvents ou WSAGetOverlappedResult para aguardar ou sondar o objeto de evento.
O protótipo da rotina de conclusão é o seguinte:
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Este CompletionRoutine é um espaço reservado para uma função definida pelo aplicativo ou definida pela biblioteca. A rotina de conclusão será invocada somente se o thread estiver em um estado alertável. Para colocar um thread em um estado alertável, use a função WSAWaitForMultipleEvents, WaitForSingleObjectEx ou WaitForMultipleObjectsEx com o parâmetro fAlertable ou bAlertable definido como TRUE.
O parâmetro dwError de CompletionRoutine especifica o status de conclusão para a operação sobreposta, conforme indicado por lpOverlapped. O parâmetro cbTransferred especifica o número de bytes retornados. Atualmente, nenhum valor de sinalizador é definido e dwFlags será zero. A função CompletionRoutine não retorna um valor.
Retornar dessa função permite a invocação de outra rotina de conclusão pendente para esse soquete. As rotinas de conclusão podem ser chamadas em qualquer ordem, não necessariamente na mesma ordem em que as operações sobrepostas são concluídas.
Compatibilidade
Os códigos IOCTL com T == 0 são um subconjunto dos códigos IOCTL usados em soquetes berkeley. Em particular, não há nenhum comando equivalente a FIOASYNC.Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de