Função WSAIoctl (winsock2.h)

Artigo
07/16/2024

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 (ignorada para soquetes não sobrepostos).

[in] lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Observação Um ponteiro para a rotina de conclusão chamada quando a operação foi concluída (ignorado para soquetes não sobrepostos). Consulte Comentários.

Valor de retorno

Após a conclusão bem-sucedida, o WSAIoctl retornará 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 de erro	Significado
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente.
WSAENETDOWN	O subsistema de rede falhou.
WSAEFAULT	OlpvInBuffer , lpvOutBuffer, lpcbBytesReturned, lpOverlappedou 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.
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.
WSAEINPROGRESS	A função é invocada quando um retorno de chamada está em andamento.
WSAENOTSOCK	O descritor não é um soquete.
WSAEOPNOTSUPP	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.)
WSAEWOULDBLOCK	O soquete é marcado como não bloqueado e a operação solicitada seria bloqueada.
WSAENOPROTOOPT	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 é 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 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 apontado pelo parâmetro lpcbBytesReturned que é retornado pode ser ignorado. O status de conclusão final e os 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

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 ioctlsocket atualmente definidos, fornecendo uma maneira conveniente de particionar o espaço do identificador de 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 formulário a seguir.

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

Observação Os bits no parâmetro dwIoControlCode exibido na tabela devem ser lidos verticalmente de cima para baixo por coluna. Portanto, o bit mais à esquerda é o bit 31, o próximo bit é o bit 30 e o bit mais à direita é o bit 0.

Estou definido se o buffer de entrada for válido para o código, como com IOC_IN.

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 . 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 do fornecedor.

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 lpOverlapped contém o endereço de uma estrutura de 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.

Observação Todas as E/S iniciadas por um determinado thread são canceladas quando esse thread é encerrado. Para soquetes sobrepostos, as operações assíncronas pendentes podem falhar se o thread for fechado antes da conclusão das operações. Consulte ExitThread para obter mais informações.

Se lpCompletionRoutine não for NULL, o parâmetro hEvent será ignorado e poderá ser usado pelo aplicativo para passar informações de contexto para a rotina de conclusão. Um chamador que passa umNULL não lpCompletionRoutine e chamadas posteriores WSAGetOverlappedResult para a mesma solicitação de E/S sobreposta pode não definir o parâmetro fWait para essa invocação de WSAGetOverlappedResult para true. Nesse caso, o uso do parâmetro hEvent é indefinido e tentar aguardar o parâmetro hEvent produziria resultados imprevisíveis.

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 WSAWaitForMultipleEvents, WaitForSingleObjectExou WaitForMultipleObjectsEx com o fAlertable ou parâmetro bAlertable definido como TRUE.

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

Observação alguns códigos IOCTL exigem arquivos de cabeçalho adicionais. Por exemplo, o uso do SIO_RCVALL IOCTL requer o arquivo de cabeçalho Mstcpip.h.

Windows Phone 8: Essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

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

WSASocket

do Winsock Functions

referência Winsock

de getsockopt

ioctlsocket

setsockopt

soquete

Compartilhar via