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. Veja do 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 de WSAOVERLAPPED
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valor de retorno
Após a conclusão bem-sucedida, o WSAIoctl
Código de erro | Significado |
---|---|
Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. | |
O subsistema de rede falhou. | |
OlpvInBuffer |
|
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 não é um soquete. | |
O comando IOCTL especificado não pode ser realizado. (Por exemplo, as estruturas |
|
O soquete é marcado como não bloqueado 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 datagram. |
Observações
A função WSAIoctl
Se lpOverlapped e lpCompletionRoutine estiverem NULL, o soquete nessa função será tratado como um soquete não sobreposto. Para um soquete não sobreposto, lpOverlapped e parâmetros de lpCompletionRoutine são ignorados, o que faz com que a função se comporte como a função de ioctlsocket padrão, exceto que a função pode bloquear se o soquete estiver no modo de bloqueio. Se o soquete 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 reempor 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 WSAAsyncSelectbaseado em )ou evento (usando WSAEventSelectmecanismo de notificação baseado em ).
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 de DWORD
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
Alguns IOCTLs específicos do protocolo também podem ser especialmente propensos a bloquear. Verifique o anexo específico do protocolo relevante para obter informações disponíveis.
O protótipo da rotina de conclusão apontado 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
);
O CompletionRoutine é um espaço reservado para um nome de função fornecido pelo aplicativo. O parâmetro dwError especifica o status de conclusão da operação sobreposta, conforme indicado por parâmetro de 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
Eu | 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. Os códigos de controle usando buffers de entrada e de 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 de 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 o 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 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 fornecedor/endereço do
família fornecedor/endereço 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 do Windows Sockets 2 genérico (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 (comandos) unix.
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 especificado) 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
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 de 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
O parâmetro dwError de CompletionRoutine especifica o status de conclusão da 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
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 no Windows 8.1, Windows Server 2012 R2 e posterior.
Requisitos
Requisito | Valor |
---|---|
de cliente com suporte mínimo | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
da Plataforma de Destino |
Windows |
cabeçalho | winsock2.h |
biblioteca | Ws2_32.lib |
de DLL |
Ws2_32.dll |
Consulte também
opções de soquete SOL_SOCKET
do Winsock Functions
referência Winsock