Função de retorno de chamada LPWSPIOCTL (ws2spi.h)

Artigo
08/28/2023

A função LPWSPIoctl controla o modo de um soquete.

Sintaxe

LPWSPIOCTL Lpwspioctl;

int Lpwspioctl(
  [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,
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPINT lpErrno
)
{...}

Parâmetros

[in] s

Um descritor que identifica um soquete.

[in] dwIoControlCode

O código de controle da operação a ser executada.

[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

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

[in] 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) até que a função WPUQueueApc retorne.

[in] lpErrno

Um ponteiro para o código de erro.

Valor retornado

Se nenhum erro ocorrer e a operação tiver sido concluída imediatamente, LPWSPIoctl retornará zero. Observe que, nesse caso, a rotina de conclusão, se especificada, já terá sido enfileirada. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico estará disponível em lpErrno. O código de erro WSA_IO_PENDING indica que uma operação sobreposta foi iniciada com êxito e que a conclusão será indicada posteriormente. Qualquer outro código de erro indica que nenhuma operação sobreposta foi iniciada e nenhuma indicação de conclusão ocorrerá.

Código do erro	Significado
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente.
WSAEFAULT	O parâmetro lpvInBuffer, lpvOutBuffer ou lpcbBytesReturned 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 dwIoControlCode não é um comando válido ou um parâmetro de entrada fornecido não é aceitável ou o comando não é aplicável ao tipo de soquete fornecido.
WSAEINPROGRESS	A função é invocada quando um retorno de chamada está em andamento.
WSAENETDOWN	O subsistema de rede falhou.
WSAENOTSOCK	O descritor s não é um soquete.
WSAEOPNOTSUPP	O comando IOCTL especificado não pode ser realizado. Por exemplo, as especificações de fluxo especificadas em SIO_SET_QOS não podem ser atendidas.
WSAEWOULDBLOCK	O soquete é marcado como não desbloqueio e a operação solicitada seria bloqueada.

Comentários

Essa rotina é 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 soquetes não sobrepostos, os parâmetros lpOverlapped e lpCompletionRoutine são ignorados e essa função pode bloquear se o soquete s estiver no modo de bloqueio. Observe que, se o soquete s estiver no modo sem bloqueio, essa função poderá retornar WSAEWOULDBLOCK se a operação especificada não puder ser concluída imediatamente. Nesse caso, o cliente SPI do Windows Sockets pode alterar o soquete para o modo de bloqueio e reemita 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 a mensagem do Windows (por meio do LPWSPAsyncSelect ou do evento (usando o mecanismo de notificação baseado em LPWSPEventSelect).

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 cliente SPI do Windows Sockets não puder tolerar o bloqueio em uma chamada LPWSPIoctl , a E/S sobreposta será aconselhada para IOCTLs que são mais 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 particularmente propensas a serem bloqueadas. Verifique o anexo específico do protocolo relevante para obter informações disponíveis.

O protótipo para a rotina de conclusão apontada pelo parâmetro lpCompletionRoutine é o seguinte.

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.

Tanto quanto o parâmetro dwIoControlCode agora é uma entidade de 32 bits, é possível adotar um esquema de codificação que fornece uma maneira conveniente de particionar o espaço do identificador opcode. O parâmetro dwIoControlCode é construído 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 códigos de controle do Windows Sockets 1.1 e UNIX. O parâmetro dwIoControlCode tem o seguinte formato.

bit 31	bit 30	bit 29	bits 28 e 27	bits 26 a 16	bits 15 a 0
I	O	V	T	Família de fornecedores/endereços	Código

Eu serei 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. Observe que, para códigos com parâmetros de entrada e saída, E/S serão definidos.

V será definido se não houver parâmetros para o código, como com IOC_VOID.

T é uma quantidade de dois bits que define o tipo de IOCTL. Os valores a seguir são definidos.

0 indica que o IOCTL é um código IOCTL UNIX padrão, como com FIONREAD, FIONBIO e assim por diante.
1 indica que 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 indica que o IOCTL se aplica apenas a uma família de endereços específica.
3 O IOCTL se aplica somente ao provedor de um fornecedor específico. Esse tipo permite que as empresas sejam atribuídas a um número de fornecedor que aparece no membro da família Fornecedor/Endereço . 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 membro terá o mesmo valor que o código no UNIX. Se esse for um IOCTL do Windows Sockets 2 genérico (T == 1), esse membro poderá ser usado como uma extensão do membro de código para fornecer valores de código adicionais.

O código é o código IOCTL específico para a operação.

Há suporte para os seguintes comandos UNIX:

FIONBIO

Habilita ou desabilita o modo de desbloqueio em soquetes. O parâmetro lpvInBuffer aponta para um longo sem sinal, que é diferente de zero se o modo de não desbloqueio deve ser habilitado e zero se for para ser desabilitado. Quando um soquete é criado, ele opera no modo de bloqueio (ou seja, o modo sem bloqueio é desabilitado). Isso é consistente com soquetes BSD (Berkeley Software Distribution).

A rotina LPWSPAsyncSelect ou LPWSPEventSelect define automaticamente um soquete como modo de desbloqueio. Se LPWSPAsyncSelect ou LPWSPEventSelect tiver sido emitido em um soquete, qualquer tentativa de usar LPWSPIoctl para definir o soquete de volta para o modo de bloqueio falhará com WSAEINVAL. Para definir o soquete de volta para o modo de bloqueio, um cliente SPI do Windows Sockets deve primeiro desabilitar LPWSPAsyncSelect chamando LPWSPAsyncSelect com o parâmetro lEvent igual a zero ou desabilitar LPWSPEventSelect chamando LPWSPEventSelect com o parâmetro lNetworkEvents igual a zero.

FIONREAD

Determine a quantidade de dados que podem ser lidos atomicamente dos soquetes. O parâmetro lpvOutBuffer aponta para um longo sem sinal no qual O WSAIoctl armazena o resultado.

Se o soquete passado no parâmetro s for orientado para fluxo (por exemplo, digite SOCK_STREAM), FIONREAD retornará a quantidade total de dados que podem ser lidos em uma única operação de recebimento; normalmente, isso é o mesmo que a quantidade total de dados enfileirados no soquete (como um fluxo de dados é orientado a bytes, isso não é garantido).

Se o soquete passado no parâmetro s for orientado a mensagens (por exemplo, digite SOCK_DGRAM), FIONREAD retornará aos relatórios o número total de bytes disponíveis para leitura, não o tamanho do primeiro datagrama (mensagem) enfileirado no soquete.

SIOCATMARK

Determina se todos os dados OOB foram lidos ou não. Isso se aplica apenas a um soquete de estilo de fluxo (por exemplo, tipo SOCK_STREAM) que foi configurado para recepção embutida de qualquer dado OOB (SO_OOBINLINE). Se nenhum dado OOB estiver esperando para ser lido, a operação retornará TRUE. Caso contrário, ele retornará FALSE e a próxima operação de recebimento executada no soquete recuperará alguns ou todos os dados anteriores à marca; O cliente SPI do Windows Sockets deve usar a operação SIOCATMARK para determinar se algum permanece. Se houver dados normais anteriores aos dados urgentes (OOB), eles serão recebidos em ordem. (Observe que as operações de recebimento nunca misturarão o OOB e os dados normais na mesma chamada.) lpvOutBuffer aponta para um BOOL no qual LPWSPIoctl armazena o resultado.

Há suporte para os seguintes comandos do Windows Sockets 2:

SIO_ACQUIRE_PORT_RESERVATION (configuração de opcode: I, T==3)

Solicite uma reserva de runtime para um bloco de portas TCP ou UDP. Para reservas de porta de runtime, o pool de portas exige que as reservas sejam consumidas do processo em cujo soquete a reserva foi concedida. As reservas de porta de runtime duram apenas o tempo de vida do soquete no qual o SIO_ACQUIRE_PORT_RESERVATION IOCTL foi chamado. Por outro lado, as reservas de porta persistentes criadas usando a função CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation podem ser consumidas por qualquer processo com a capacidade de obter reservas persistentes.

Para obter informações mais detalhadas, consulte a referência de SIO_ACQUIRE_PORT_RESERVATION .

SIO_ACQUIRE_PORT_RESERVATION tem suporte no Windows Vista e versões posteriores do sistema operacional.

SIO_ADDRESS_LIST_CHANGE (configuração de opcode: T==1)

Para receber a notificação de alterações na lista de endereços de transporte locais da família de protocolos do soquete à qual o cliente SPI do Windows Sockets pode associar. Nenhuma informação de saída será fornecida após a conclusão deste IOCTL; a conclusão apenas indica que a lista de endereços locais disponíveis foi alterada e deve ser consultada novamente por meio de SIO_ADDRESS_LIST_QUERY.

Supõe-se (embora não seja necessário) que o cliente SPI do Windows Sockets use E/S sobrepostas para ser notificado sobre a alteração após a conclusão de SIO_ADDRESS_LIST_CHANGE solicitação. Como alternativa, se o SIO_ADDRESS_LIST_CHANGE IOCTL for emitido em um soquete sem bloqueio e sem parâmetros sobrepostos (lpOverlapped e lpCompletionRoutine estiverem definidos como NULL), ele será concluído imediatamente com o erro WSAEWOULDBLOCK. O cliente SPI do Windows Sockets pode aguardar eventos de alteração de lista de endereços por meio de uma chamada para LPWSPEventSelect ou LPWSPAsyncSelect com o bit FD_ADDRESS_LIST_CHANGE definido na máscara de bits do evento de rede.

SIO_ADDRESS_LIST_QUERY (configuração de opcode: O, T==1)

Obtém uma lista de endereços de transporte locais da família de protocolos do soquete à qual o aplicativo pode ser associado. A lista de endereços varia de acordo com a família de endereços e alguns endereços são excluídos da lista.

Observação

Em ambientes do Windows Plug-n-Play, os endereços podem ser adicionados e removidos dinamicamente. Portanto, os aplicativos não podem contar com as informações retornadas por SIO_ADDRESS_LIST_QUERY para serem persistentes. Os aplicativos podem se registrar para notificações de alteração de endereço por meio do SIO_ADDRESS_LIST_CHANGE IOCTL, que fornece notificação por meio de E/S sobreposta ou FD_ADDRESS_LIST_CHANGE evento. A seguinte sequência de ações pode ser usada para garantir que o aplicativo sempre tenha informações de lista de endereços atuais:

Problema SIO_ADDRESS_LIST_CHANGE IOCTL
Problema SIO_ADDRESS_LIST_QUERY IOCTL
Sempre que SIO_ADDRESS_LIST_CHANGE IOCTL notificar a aplicação de alteração de lista de endereços (por meio de E/S sobreposta ou sinalizando FD_ADDRESS_LIST_CHANGE evento), toda a sequência de ações deve ser repetida.

Para obter informações mais detalhadas, consulte a referência de SIO_ADDRESS_LIST_QUERY . SIO_ADDRESS_LIST_QUERY tem suporte no Windows 2000 e posterior.

SIO_ASSOCIATE_HANDLE (configuração de opcode: I, T==1)

Associa esse soquete ao identificador especificado de uma interface complementar. O buffer de entrada contém o valor inteiro correspondente à constante de manifesto para a interface complementar (por exemplo, TH_NETDEV e TH_TAPI), seguido por um valor que é um identificador da interface complementar especificada, juntamente com quaisquer outras informações necessárias. Consulte a seção apropriada no Windows Sockets 2 Protocol-Specific Anexo e/ou documentação da interface complementar específica para obter detalhes adicionais. (Esses recursos só podem estar disponíveis em inglês.) O tamanho total é refletido no comprimento do buffer de entrada. Nenhum buffer de saída é necessário. O código de erro WSAENOPROTOOPT é indicado para provedores de serviços que não dão suporte a esse IOCTL. O identificador associado a esse IOCTL pode ser recuperado usando SIO_TRANSLATE_HANDLE.

Uma interface complementar poderá ser usada, por exemplo, se um provedor específico fornecer:

Um grande controle adicional sobre o comportamento de um soquete.
Controles específicos do provedor que não são mapeados para funções existentes do Windows Socket (ou aquelas prováveis para o futuro).

É recomendável que o modelo de objeto de componente (COM) seja usado em vez deste IOCTL, para descobrir e controlar outras interfaces que possam ter suporte por um soquete. Este IOCTL está presente para compatibilidade com versões anteriores com sistemas em que COM não está disponível ou não pode ser usado por algum outro motivo.

SIO_ASSOCIATE_PORT_RESERVATION (configuração de opcode: I, T==3)

Associe um soquete a uma reserva persistente ou de runtime para um bloco de portas TCP ou UDP identificadas pelo token de reserva de porta. O SIO_ASSOCIATE_PORT_RESERVATION IOCTL deve ser emitido antes que o soquete seja associado. Se e quando o soquete estiver associado, a porta atribuída a ele será selecionada na reserva de porta identificada pelo token fornecido. Se nenhuma porta estiver disponível na reserva especificada, a chamada de função Bind falhará.

Para obter informações mais detalhadas, consulte a referência de SIO_ASSOCIATE_PORT_RESERVATION .

SIO_ASSOCIATE_PORT_RESERVATION tem suporte no Windows Vista e versões posteriores do sistema operacional.

SIO_BASE_HANDLE (configuração de opcode: O, T==1)

Recupera o identificador do provedor de serviços base para um determinado soquete. O valor retornado é um SOCKET.

Um provedor de serviços em camadas nunca deve interceptar esse IOCTL, pois o valor retornado deve ser o identificador de soquete do provedor de serviços base.

Se o buffer de saída não for grande o suficiente para um identificador de soquete (o cbOutBuffer é menor que o tamanho de um SOCKET) ou o parâmetro lpvOutBuffer é um ponteiro NULL , SOCKET_ERROR é retornado como resultado desse IOCTL e WSAGetLastError retorna WSAEFAULT.

SIO_BASE_HANDLE é definido no arquivo de cabeçalho Mswsock.h e tem suporte no Windows Vista e posterior.

SIO_BSP_HANDLE (configuração de opcode: O, T==1)

Recupera o identificador do provedor de serviços base para um soquete usado pela função WSASendMsg . O valor retornado é um SOCKET.

Esse Ioctl é usado por um provedor de serviços em camadas para garantir que o provedor intercepte a função WSASendMsg .

SIO_BSP_HANDLE é definido no arquivo de cabeçalho Mswsock.h e tem suporte no Windows Vista e posterior.

SIO_BSP_HANDLE_SELECT (configuração de opcode: O, T==1)

Recupera o identificador do provedor de serviços base para um soquete usado pela função select . O valor retornado é um SOCKET.

Esse Ioctl é usado por um provedor de serviços em camadas para garantir que o provedor intercepte a função select .

SIO_BSP_HANDLE_SELECT é definido no arquivo de cabeçalho Mswsock.h e tem suporte no Windows Vista e posterior.

SIO_BSP_HANDLE_POLL (configuração de opcode: O, T==1)

Recupera o identificador do provedor de serviços base para um soquete usado pela função WSAPoll . O parâmetro lpOverlapped deve ser um ponteiro NULL . O valor retornado é um SOCKET.

Esse Ioctl é usado por um provedor de serviços em camadas para garantir que o provedor intercepte a função WSAPoll .

Se o buffer de saída não for grande o suficiente para um identificador de soquete (o cbOutBuffer é menor que o tamanho de um SOCKET), o parâmetro lpvOutBuffer é um ponteiro NULL ou o parâmetro lpOverlapped não é um ponteiro NULL , SOCKET_ERROR é retornado como resultado desse IOCTL e WSAGetLastError retorna WSAEFAULT.

SIO_BSP_HANDLE_POLL é definido no arquivo de cabeçalho Mswsock.h e tem suporte no Windows Vista e posterior.

SIO_CHK_QOS (configuração de opcode: I, O, T==3)

Recupera informações sobre características de tráfego de QoS. Durante a fase de transição no sistema de envio entre a configuração do fluxo e o recebimento de uma mensagem RESV (consulte Como o serviço RSVP invoca tc para obter mais informações sobre a fase de transição), o tráfego associado a um fluxo RSVP é moldado com base no tipo de serviço ( MELHOR ESFORÇO, CARGA CONTROLADA ou GARANTIDO). Para obter mais informações, consulte Usando SIO_CHK_QOS na seção Qualidade do Serviço do SDK (Platform Software Development Kit).

SIO_ENABLE_CIRCULAR_QUEUEING (configuração de opcode: V, T==1)

Indica a um provedor de serviços orientado a mensagens que uma mensagem recém-chegada nunca deve ser descartada devido a um estouro de fila de buffer. Em vez disso, a mensagem mais antiga na fila deve ser eliminada para acomodar a mensagem recém-chegada. Nenhum buffer de entrada e saída é necessário. Observe que esse IOCTL só é válido para soquetes associados a protocolos não confiáveis orientados a mensagens. O código de erro WSAENOPROTOOPT é indicado para provedores de serviços que não dão suporte a esse IOCTL.

SIO_FIND_ROUTE (configuração de opcode: O, T==1)

Quando emitido, esse IOCTL solicita que a rota para o endereço remoto especificado como um sockaddr no buffer de entrada seja descoberta. Se o endereço já existir no cache local, sua entrada será invalidada. No caso do IPX da Novell, essa chamada inicia um IPX GetLocalTarget (GLT), que consulta a rede para o endereço remoto especificado.

SIO_FLUSH (configuração de opcode: V, T==1)

Descarta o conteúdo atual da fila de envio associada a esse soquete. Nenhum buffer de entrada e saída é necessário. O código de erro WSAENOPROTOOPT é indicado para provedores de serviços que não dão suporte a esse IOCTL.

SIO_GET_BROADCAST_ADDRESS (configuração de opcode: O, T==1)

Esse IOCTL preenche o buffer de saída com uma estrutura sockaddr que contém um endereço de difusão adequado para uso com LPWSPSendTo.

SIO_GET_EXTENSION_FUNCTION_POINTER (configuração de opcode: O, I, T==1)

Recupere um ponteiro para a função de extensão especificada com suporte pelo provedor de serviços associado. O buffer de entrada contém um GUID (identificador global exclusivo) cujo valor identifica a função de extensão em questão. O ponteiro para a função desejada é retornado no buffer de saída. Os identificadores de função de extensão são estabelecidos por fornecedores de provedores de serviços e devem ser incluídos na documentação do fornecedor que descreve as funcionalidades e a semântica da função de extensão.

Os valores de GUID para funções de extensão compatíveis com o provedor de serviços TCP/IP do Windows são definidos no arquivo de cabeçalho Mswsock.h . O valor possível para esses GUIDs é o seguinte:

Termo	Descrição
WSAID_ACCEPTEX	A função de extensão AcceptEx .
WSAID_CONNECTEX	A função de extensão ConnectEx .
WSAID_DISCONNECTEX	A função de extensão DisconnectEx .
WSAID_GETACCEPTEXSOCKADDRS	A função de extensão GetAcceptExSockaddrs .
WSAID_TRANSMITFILE	A função de extensão TransmitFile .
WSAID_TRANSMITPACKETS	A função de extensão TransmitPackets .
WSAID_WSARECVMSG	A função de extensão LPFN_WSARECVMSG (WSARecvMsg ).
WSAID_WSASENDMSG	A função de extensão WSASendMsg .

SIO_GET_GROUP_QOS (configuração de opcode: O, T==1)

Reservado.

SIO_GET_INTERFACE_LIST (configuração de opcode: O, T==0)

Retorna uma lista de interfaces IP configuradas e seus parâmetros como uma matriz de estruturas de INTERFACE_INFO .

Observação

O suporte a esse comando é obrigatório para provedores de serviçoS TCP/IP compatíveis com o Windows Sockets 2.

O parâmetro lpvOutBuffer aponta para o buffer no qual armazenar as informações sobre interfaces como uma matriz de estruturas de INTERFACE_INFO para endereços IP unicast nas interfaces. O parâmetro cbOutBuffer especifica o comprimento do buffer de saída. O número de interfaces retornadas (número de estruturas retornadas no buffer apontado pelo parâmetro lpvOutBuffer ) pode ser determinado com base no comprimento real do buffer de saída retornado no parâmetro lpcbBytesReturned .

Se a função WSAIoctl for chamada com SIO_GET_INTERFACE_LIST e o membro de nível do parâmetro de soquete s não for definido como IPPROTO_IP, WSAEINVAL será retornado. Uma chamada para a função WSAIoctl com SIO_GET_INTERFACE_LIST retornará WSAEFAULT se o parâmetro cbOutBuffer que especifica o comprimento do buffer de saída for muito pequeno, ro receberá a lista de interfaces configuradas.

SIO_GET_INTERFACE_LIST_EX (configuração de opcode: O, T==0)

Reservado para uso futuro com soquetes.

Retorna uma lista de interfaces IP configuradas e seus parâmetros como uma matriz de estruturas INTERFACE_INFO_EX .

O parâmetro lpvOutBuffer aponta para o buffer no qual armazenar as informações sobre interfaces como uma matriz de estruturas de INTERFACE_INFO_EX para endereços IP unicast na interface. O parâmetro cbOutBuffer especifica o comprimento do buffer de saída. O número de interfaces retornadas (número de estruturas retornadas em lpvOutBuffer) pode ser determinado com base no comprimento real do buffer de saída retornado no parâmetro lpcbBytesReturned .

SIO_GET_INTERFACE_LIST_EX atualmente não tem suporte no Windows.

SIO_GET_QOS (configuração de opcode: O, T==1)

Recupera a estrutura QOS associada ao soquete. O buffer de entrada é opcional. Alguns protocolos (por exemplo, RSVP) permitem que o buffer de entrada seja usado para qualificar uma solicitação QOS . A estrutura QOS será copiada para o buffer de saída. O buffer de saída deve ser dimensionado grande o suficiente para poder conter a estrutura completa do QOS . O código de erro WSAENOPROTOOPT é indicado para provedores de serviços que não dão suporte à qualidade do serviço.

SIO_IDEAL_SEND_BACKLOG_CHANGE (configuração de opcode: V, T==0)

Notifica um aplicativo quando o valor ideal da lista de pendências de envio (ISB) é alterado para a conexão subjacente.

Ao enviar dados por uma conexão TCP usando soquetes do Windows, é importante manter uma quantidade suficiente de dados pendentes (enviados, mas ainda não confirmados) no TCP para obter a maior taxa de transferência. O valor ideal para a quantidade de dados pendentes para obter a melhor taxa de transferência para a conexão TCP é chamado de tamanho de ISB (lista de pendências de envio ideal). O valor isb é uma função do produto de atraso de largura de banda da conexão TCP e da janela de recebimento anunciada do receptor (e, em parte, a quantidade de congestionamento na rede).

O valor do ISB por conexão está disponível na implementação do protocolo TCP no Windows Server 2008, no Windows Vista com Service Pack 1 (SP1) e em versões posteriores do sistema operacional. O SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL pode ser usado por um aplicativo para receber notificação quando o valor do ISB é alterado dinamicamente para uma conexão.

Para obter informações mais detalhadas, consulte a referência de SIO_IDEAL_SEND_BACKLOG_CHANGE .

SIO_IDEAL_SEND_BACKLOG_CHANGE tem suporte no Windows Server 2008, Windows Vista com SP1 e versões posteriores do sistema operacional.

SIO_IDEAL_SEND_BACKLOG_QUERY (configuração de opcode: O, T==0)

Recupera o valor de ISB (lista de pendências de envio) ideal para a conexão subjacente.

O valor isb por conexão está disponível na implementação do protocolo TCP no Windows Server 2008 e posterior. O SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL pode ser usado por um aplicativo para consultar o valor isb de uma conexão.

Para obter informações mais detalhadas, consulte a referência de SIO_IDEAL_SEND_BACKLOG_QUERY .

SIO_IDEAL_SEND_BACKLOG_QUERY tem suporte no Windows Server 2008, Windows Vista com SP1 e versões posteriores do sistema operacional.

SIO_KEEPALIVE_VALS (configuração de opcode: I, T==3)

Habilita ou desabilita a configuração por conexão da opção keep alive TCP, que especifica o tempo limite e o intervalo de keep alive do TCP. Para obter mais informações sobre a opção keep alive, consulte a seção 4.2.3.6 sobre os Requisitos para Hosts da Internet – Camadas de Comunicação especificadas no RFC 1122 disponíveis no site do IETF.

SIO_KEEPALIVE_VALS pode ser usado para habilitar ou desabilitar investigações keep alive e definir o tempo limite e o intervalo de keep alive. O tempo limite keep alive especifica o tempo limite, em milissegundos, sem atividade até que o primeiro pacote keep alive seja enviado. O intervalo keep alive especifica o intervalo, em milissegundos, entre quando pacotes keep alive sucessivos são enviados se nenhuma confirmação for recebida.

A opção SO_KEEPALIVE , que é uma das opções de soquete SOL_SOCKET, também pode ser usada para habilitar ou desabilitar o keep alive do TCP em uma conexão, bem como consultar o estado atual dessa opção. Para consultar se o keep alive TCP está habilitado em um soquete, a função getsockopt pode ser chamada com a opção SO_KEEPALIVE . Para habilitar ou desabilitar o keep alive do TCP, a função setsockopt pode ser chamada com a opção SO_KEEPALIVE . Se o keep alive do TCP estiver habilitado com SO_KEEPALIVE, as configurações de TCP padrão serão usadas para tempo limite e intervalo keep alive, a menos que esses valores tenham sido alterados usando SIO_KEEPALIVE_VALS.

Para obter informações mais detalhadas, consulte a referência de SIO_KEEPALIVE_VALS . SIO_KEEPALIVE_VALS tem suporte no Windows 2000 e posterior.

SIO_MULTIPOINT_LOOPBACK (configuração de opcode: I, T==1)

Controla se os dados enviados por um aplicativo no computador local (não necessariamente pelo mesmo soquete) em uma sessão multicast serão recebidos por um soquete unido ao grupo de destino multicast na interface de loopback. Um valor true faz com que os dados multicast enviados por um aplicativo no computador local sejam entregues a um soquete de escuta na interface de loopback. Um valor false impede que dados multicast enviados por um aplicativo no computador local sejam entregues a um soquete de escuta na interface de loopback. Por padrão, SIO_MULTIPOINT_LOOPBACK está habilitado.

SIO_MULTICAST_SCOPE (configuração de opcode: I, T==1)

Especifica o escopo sobre o qual as transmissões multicast ocorrerão. O escopo é definido como o número de segmentos de rede roteado a serem cobertos. Um escopo de zero indicaria que a transmissão multicast não seria colocada no fio, mas poderia ser disseminada entre soquetes dentro do host local. Um valor de escopo de 1 (o padrão) indica que a transmissão será colocada na transmissão, mas não atravessará nenhum roteador. Valores de escopo mais altos determinam o número de roteadores que podem ser cruzados. Observe que isso corresponde ao parâmetro TTL (vida útil) no multicasting de IP.

SIO_QUERY_RSS_SCALABILITY_INFO (configuração de opcode: O, T==3)

Consultas descarregam interfaces para a funcionalidade de RSS (dimensionamento do lado do recebimento). A estrutura de argumentos retornada para SIO_QUERY_RSS_SCALABILITY_INFO é especificada na estrutura RSS_SCALABILITY_INFO definida no arquivo de cabeçalho Mstcpip.h . Essa estrutura é definida da seguinte maneira.

void CALLBACK 
CompletionRoutine(  
  IN DWORD           dwError, 
  IN DWORD           cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD           dwFlags 
);

O valor retornado no membro RssEnabled indica se o RSS está habilitado em pelo menos uma interface.

Se o buffer de saída não for grande o suficiente para a estrutura de RSS_SCALABILITY_INFO ( cbOutBuffer for menor que o tamanho de um RSS_SCALABILITY_INFO) ou o parâmetro lpvOutBuffer for um ponteiro NULL , SOCKET_ERROR será retornado como resultado desse IOCTL e WSAGetLastError retornará WSAEINVAL.

Na rede de alta velocidade em que várias CPUs residem em um único sistema, a capacidade da pilha de protocolos de rede de dimensionar bem em um sistema de várias CPU é inibida porque a arquitetura do NDIS 5.1 e versões anteriores limita o processamento de protocolo de recebimento para uma única CPU. O RSS (dimensionamento do lado do recebimento) resolve esse problema permitindo que a carga de rede de um adaptador de rede seja balanceada em várias CPUs.

SIO_QUERY_RSS_SCALABILITY_INFO tem suporte no Windows Vista e posterior.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE (configuração de opcode: O, T==3)

Consulta o identificador de ponto de extremidade ALE (Application Layer Enforcement).

A Plataforma de Filtragem do Windows (WFP) dá suporte à inspeção e modificação de tráfego de rede. No Windows Vista, o WFP se concentra em cenários em que o computador host é o ponto de extremidade de comunicação. No Windows Server 2008, no entanto, há implementações de firewall de borda que gostariam de aproveitar a plataforma WFP para inspecionar e fazer proxy do tráfego de passagem. O servidor ISA (Segurança e Aceleração da Internet) é um exemplo desse dispositivo de borda.

Há alguns cenários de firewall que podem exigir a capacidade de injetar um pacote de entrada no caminho de envio associado a um ponto de extremidade existente. Precisa haver um mecanismo para descobrir o identificador de ponto de extremidade da camada de transporte associado ao ponto de extremidade de destino. O aplicativo que criou o ponto de extremidade possui esses pontos de extremidade de camada de transporte. Esse IOCTL é usado para fornecer o identificador de soquete para transportar o mapeamento do identificador de ponto de extremidade da camada.

Se o buffer de saída não for grande o suficiente para o identificador do ponto de extremidade ( cbOutBuffer for menor que o tamanho de um UINT64) ou o parâmetro lpvOutBuffer for um ponteiro NULL , SOCKET_ERROR será retornado como resultado desse IOCTL e WSAGetLastError retornará WSAEINVAL.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE tem suporte no Windows Vista e posterior.

SIO_QUERY_PNP_TARGET_HANDLE (configuração de opcode: O, T==1)

Para obter o descritor de soquete do próximo provedor na cadeia na qual o soquete atual depende no sentido PnP. Esse IOCTL é invocado pela DLL do Windows Sockets 2 somente em soquetes de provedores de serviços não IFS criados por meio da chamada WPUCreateSocketHandle . O provedor deve retornar no buffer de saída o identificador de soquete do próximo provedor na cadeia na qual um determinado identificador de soquete depende no sentido PnP (por exemplo, a remoção do dispositivo que dá suporte ao identificador subjacente resultará na invalidação do identificador acima dele na cadeia).

Se uma operação sobreposta for concluída imediatamente, essa função retornará um valor 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 é concluída, 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 em LPWSPGetOverlappedResult.

SIO_RCVALL (configuração de opcode: I, T==3)

Permite que um soquete receba todos os pacotes IPv4 ou IPv6 que passam por um adaptador de rede. O identificador de soquete passado para a função WSAIoctl deve ser um dos seguintes:

Um soquete IPv4 que foi criado com a família de endereços definida como AF_INET, o tipo de soquete definido como SOCK_RAW e o protocolo definido como IPPROTO_IP.
Um soquete IPv6 que foi criado com a família de endereços definida como AF_INET6, o tipo de soquete definido como SOCK_RAW e o protocolo definido como IPPROTO_IPV6.

O soquete também deve estar associado a uma interface IPv4 ou IPv6 local explícita, o que significa que você não pode se associar a INADDR_ANY ou in6addr_any.

No Windows Server 2008 e versões anteriores, a configuração SIO_RCVALL IOCTL não capturaria pacotes locais enviados de um adaptador de rede. Isso incluiu pacotes recebidos em outra interface e encaminhou o adaptador de rede especificado para o SIO_RCVALL IOCTL.

No Windows 7 e no Windows Server 2008 R2, isso foi alterado para que os pacotes locais enviados de um adaptador de rede também sejam capturados. Isso inclui pacotes recebidos em outra interface e, em seguida, encaminhou o adaptador de rede associado ao soquete com SIO_RCVALL IOCTL.

Definir esse IOCTL requer privilégio de Administrador no computador local.

Às vezes, esse recurso é chamado de modo promíscuo.

Os valores possíveis para a opção SIO_RCVALL IOCTL são especificados na enumeração RCVALL_VALUE definida no arquivo de cabeçalho Mstcpip.h . Os valores possíveis para SIO_RCVALL são os seguintes:

Termo	Descrição
RCVALL_OFF	Desabilite essa opção para que um soquete não receba todos os pacotes IPv4 ou IPv6 na rede.
RCVALL_ON	Habilite essa opção para que um soquete receba todos os pacotes IPv4 ou IPv6 na rede. Essa opção habilita o modo promíscuo na NIC (cartão de interface de rede), se a NIC der suporte ao modo promíscuo. Em um segmento lan com um hub de rede, uma NIC que dá suporte ao modo promíscuo capturará todo o tráfego IPv4 ou IPv6 na LAN, incluindo o tráfego entre outros computadores no mesmo segmento lan. Todos os pacotes capturados (IPv4 ou IPv6, dependendo do soquete) serão entregues ao soquete bruto. Essa opção não capturará outros pacotes (pacotes ARP, IPX e NetBEUI, por exemplo) na interface . O Netmon usa o mesmo modo para o adaptador de rede, mas não usa essa opção para capturar o tráfego.
RCVALL_SOCKETLEVELONLY	Esse recurso não está implementado no momento, portanto, definir essa opção não tem nenhum efeito.
RCVALL_IPLEVEL	Habilite essa opção para que um soquete IPv4 ou IPv6 receba todos os pacotes no nível de IP na rede. Essa opção não habilita o modo promíscuo no cartão do adaptador de rede. Essa opção afeta apenas o processamento de pacotes no nível de IP. A NIC ainda recebe apenas pacotes direcionados para seus endereços unicast e multicast configurados. No entanto, um soquete com essa opção habilitada receberá não apenas pacotes direcionados a endereços IP específicos, mas receberá todos os pacotes IPv4 ou IPv6 que a NIC recebe. Essa opção não capturará outros pacotes (pacotes ARP, IPX e NetBEUI, por exemplo) recebidos na interface .

Para obter informações mais detalhadas, consulte a referência de SIO_RCVALL .

SIO_RCVALL tem suporte no Windows 2000 e posterior.

SIO_RELEASE_PORT_RESERVATION (configuração de opcode: I, T==3)

Libera uma reserva de runtime para um bloco de portas TCP ou UDP. A reserva de runtime a ser liberada deve ter sido obtida do processo de emissão usando o SIO_ACQUIRE_PORT_RESERVATION IOCTL.

Para obter informações mais detalhadas, consulte a referência de SIO_RELEASE_PORT_RESERVATION .

SIO_RELEASE_PORT_RESERVATION tem suporte no Windows Vista e versões posteriores do sistema operacional.

SIO_ROUTING_INTERFACE_CHANGE (configuração de opcode: I, T==1)

Para receber uma notificação de uma alteração de interface de roteamento que deve ser usada para alcançar o endereço remoto no buffer de entrada (especificado como uma estrutura sockaddr ). Nenhuma informação de saída sobre a nova interface de roteamento será fornecida após a conclusão deste IOCTL; a conclusão apenas indica que a interface de roteamento de um determinado destino foi alterada e deve ser consultada usando o SIO_ROUTING_INTERFACE_QUERY IOCTL.

Supõe-se (embora não seja necessário) que o aplicativo use E/S sobreposta para ser notificado sobre a alteração da interface de roteamento por meio da conclusão de SIO_ROUTING_INTERFACE_CHANGE solicitação. Como alternativa, se o SIO_ROUTING_INTERFACE_CHANGE IOCTL for emitido em um soquete sem bloqueio com os parâmetros lpOverlapped e lpCompletionRoutine definidos como NULL), ele será concluído imediatamente com o erro WSAEWOULDBLOCK e o cliente SPI do Windows Socket pode aguardar eventos de alteração de roteamento usando uma chamada para LPWSPEventSelect ou LPWSPAsyncSelect com o FD_ROUTING_INTERFACE_CHANGE bit definido na máscara de bits do evento de rede.

É reconhecido que as informações de roteamento permanecem estáveis na maioria dos casos, de modo que exigir que o aplicativo mantenha várias IOCTLs pendentes para receber notificações sobre todos os destinos em que está interessado, bem como fazer com que o provedor de serviços acompanhe essas solicitações de notificação usará uma quantidade significativa de recursos do sistema. Essa situação pode ser evitada estendendo o significado dos parâmetros de entrada e relaxando os requisitos do provedor de serviços da seguinte maneira:

O cliente SPI do Windows Sockets pode especificar um endereço curinga específico da família de protocolos (o mesmo usado na chamada Bind ao solicitar a associação a qualquer endereço disponível) para solicitar notificações de quaisquer alterações de roteamento. Isso permite que o cliente SPI do Windows Sockets mantenha apenas um SIO_ROUTING_INTERFACE_CHANGE pendente para todos os soquetes e destinos que ele tem e, em seguida, use SIO_ROUTING_INTERFACE_QUERY para obter as informações de roteamento reais.

O provedor de serviços pode optar por ignorar as informações fornecidas pelo cliente SPI do Windows Sockets no buffer de entrada do SIO_ROUTING_INTERFACE_CHANGE (como se o cliente SPI do Windows Sockets especificasse um endereço curinga) e concluir o SIO_ROUTING_INTERFACE_CHANGE ioctl ou sinalizar FD_ROUTING_INTERFACE_CHANGE evento no caso de qualquer alteração de informações de roteamento (não apenas a rota para o destino especificado no buffer de entrada).

SIO_ROUTING_INTERFACE_QUERY (configuração de opcode: I, O, T==1)

Para obter o endereço da interface local (representada como estrutura sockaddr ) que deve ser usado para enviar para o endereço remoto especificado no buffer de entrada (como sockaddr). Endereços multicast remotos podem ser enviados no buffer de entrada para obter o endereço da interface preferencial para transmissão multicast. De qualquer forma, o endereço de interface retornado pode ser usado pelo aplicativo em uma solicitação Bind subsequente.

Observe que as rotas estão sujeitas a alterações. Portanto, os clientes SPI do Windows Socket não podem depender das informações retornadas por SIO_ROUTING_INTERFACE_QUERY para serem persistentes. Os clientes SPI podem se registrar para rotear notificações de alteração usando o SIO_ROUTING_INTERFACE_CHANGE IOCTL, que fornece notificação por meio de E/S sobreposta ou um evento de FD_ROUTING_INTERFACE_CHANGE. A seguinte sequência de ações pode ser usada para garantir que o cliente SPI do Windows Socket sempre tenha informações atuais da interface de roteamento para um determinado destino:

Problema SIO_ROUTING_INTERFACE_CHANGE IOCTL.
Problema SIO_ROUTING_INTERFACE_QUERY IOCTL.
Sempre que SIO_ROUTING_INTERFACE_CHANGE IOCTL notifica o cliente SPI do WinSock de alteração de roteamento (por meio de E/S sobreposta ou sinalizando FD_ROUTING_INTERFACE_CHANGE evento), toda a sequência de ações deve ser repetida.

Se o buffer de saída não for grande o suficiente para conter o endereço da interface, SOCKET_ERROR será retornado como resultado desse IOCTL e WSAGetLastError retornará WSAEFAULT. O tamanho necessário do buffer de saída será retornado em lpcbBytesReturned nesse caso. Observe que o código de erro WSAEFAULT também será retornado se o parâmetro lpvInBuffer, lpvOutBuffer ou lpcbBytesReturned não estiver totalmente contido em uma parte válida do espaço de endereço do usuário.

Se o endereço de destino especificado no buffer de entrada não puder ser acessado por meio de nenhuma das interfaces disponíveis, SOCKET_ERROR será retornado como resultado desse IOCTL e WSAGetLastError retornará WSAENETUNREACH ou mesmo WSAENETDOWN se toda a conectividade de rede for perdida.

SIO_SET_COMPATIBILITY_MODE (configuração de opcode: I, T==3)

Solicita como a pilha de rede deve lidar com determinados comportamentos para os quais a maneira padrão de lidar com o comportamento pode diferir entre as versões do Windows. A estrutura do argumento para SIO_SET_COMPATIBILITY_MODE é especificada na estrutura WSA_COMPATIBILITY_MODE definida no arquivo de cabeçalho Mswsockdef.h . Essa estrutura é definida da seguinte maneira:

} WSA_COMPATIBILITY_MODE, *PWSA_COMPATIBILITY_MODE;

O valor especificado no membro BehaviorId indica o comportamento solicitado. O valor especificado no membro TargetOsVersion indica a versão do Windows que está sendo solicitada para o comportamento.

O membro BehaviorId pode ser um dos valores do tipo de enumeração WSA_COMPATIBILITY_BEHAVIOR_ID definido no arquivo de cabeçalho Mswsockdef.h . Os valores possíveis para o membro BehaviorId são os seguintes

Termo	Descrição
WsaBehaviorAll	Isso é equivalente a solicitar todos os possíveis comportamentos compatíveis definidos para WSA_COMPATIBILITY_BEHAVIOR_ID.
WsaBehaviorReceiveBuffering	Quando o membro TargetOsVersion é definido como um valor para o Windows Vista ou posterior, as reduções no tamanho do buffer de recebimento TCP nesse soquete usando a opção de soquete SO_RCVBUF são permitidas mesmo após o estabelecimento de uma conexão TCP. Quando o membro TargetOsVersion é definido como um valor anterior ao Windows Vista, as reduções no tamanho do buffer de recebimento TCP nesse soquete usando a opção de soquete SO_RCVBUF não são permitidas após o estabelecimento da conexão.
WsaBehaviorAutoTuning	Quando o membro TargetOsVersion é definido como um valor para o Windows Vista ou posterior, o ajuste automático da janela de recebimento é habilitado e o fator de escala da janela TCP é reduzido para 2 do valor padrão de 8. Quando TargetOsVersion é definido como um valor anterior ao Windows Vista, o ajuste automático da janela de recebimento é desabilitado. A opção de dimensionamento de janela TCP também está desabilitada e o tamanho máximo da janela de recebimento verdadeiro é limitado a 65.535 bytes. A opção de dimensionamento da janela TCP não poderá ser negociada na conexão mesmo que a opção de soquete SO_RCVBUF tenha sido chamada nesse soquete especificando um valor maior que 65.535 bytes antes da conexão ser estabelecida.

Para obter informações mais detalhadas, consulte a referência de SIO_SET_COMPATIBILITY_MODE .

SIO_SET_COMPATIBILITY_MODE tem suporte no Windows Vista e posterior.

SIO_SET_GROUP_QOS (configuração de opcode: I, T==1)

Reservado.

SIO_SET_QOS (configuração de opcode: I, T==1)

Associe a estrutura QOS fornecida ao soquete. Nenhum buffer de saída é necessário, a estrutura QOS será obtida do buffer de entrada. O código de erro WSAENOPROTOOPT é indicado para provedores de serviços que não dão suporte à qualidade do serviço.

SIO_TRANSLATE_HANDLE (configuração de opcode: I, O, T==1)

Para obter um identificador correspondente para soquetes que é válido no contexto de uma interface complementar (por exemplo, TH_NETDEV e TH_TAPI). Uma constante de manifesto que identifica a interface complementar junto com quaisquer outros parâmetros necessários é especificada no buffer de entrada. O identificador correspondente estará disponível no buffer de saída após a conclusão dessa função. Consulte a seção apropriada no Windows Sockets 2 Protocol-Specific Anexo e/ou documentação para obter a interface complementar específica para obter detalhes adicionais. O código de erro WSAENOPROTOOPT é indicado para provedores de serviços que não dão suporte a esse IOCTL para a interface complementar especificada. Esse IOCTL recupera o identificador associado usando SIO_TRANSLATE_HANDLE.

É recomendável que o COM seja usado em vez desse IOCTL para descobrir e rastrear outras interfaces que possam ter suporte de um soquete. Este IOCTL está presente para compatibilidade com versões anteriores com sistemas em que COM não está disponível ou não pode ser usado por algum outro motivo.

SIO_UDP_CONNRESET (configuração de opcode: I, T==3)

Windows XP: Controla se as mensagens de PORT_UNREACHABLE UDP são relatadas. Defina como TRUE para habilitar o relatório. Defina como FALSE para desabilitar o relatório.

Quando chamado com um soquete sobreposto, o parâmetro lpOverlapped deve ser válido durante a operação sobreposta.

Se o parâmetro lpCompletionRoutine for NULL, o provedor de serviços sinalizará o membro hEvent de lpOverlapped quando a operação sobreposta for concluída se contiver um identificador de objeto de evento válido. O cliente SPI do Windows Sockets pode usar LPWSPGetOverlappedResult para sondar ou aguardar o objeto de evento.

Se lpCompletionRoutine não for NULL, o membro hEvent será ignorado e poderá ser usado pelo cliente SPI do Windows Sockets para passar informações de contexto para a rotina de conclusão. Um cliente que passa um lpCompletionRoutine não NULL e, posteriormente, chama WSAGetOverlappedResult para a mesma solicitação de E/S sobreposta pode não definir o parâmetro fWait para essa invocação de WSAGetOverlappedResult como TRUE. Nesse caso, o uso do membro hEvent é indefinido e a tentativa de aguardar o membro hEvent produziria resultados imprevisíveis.

É responsabilidade do provedor de serviços organizar a invocação da rotina de conclusão especificada pelo cliente quando a operação sobreposta for concluída. Como a rotina de conclusão deve ser executada no contexto do mesmo thread que iniciou a operação sobreposta, ela não pode ser invocada diretamente do provedor de serviços. O WS2_32.DLL oferece um mecanismo de APC (chamada de procedimento assíncrono) para facilitar a invocação de rotinas de conclusão.

Um provedor de serviços organiza a execução de uma função no thread e no contexto de processo adequados chamando WPUQueueApc. Essa função pode ser chamada de qualquer contexto de processo e thread, até mesmo de um contexto diferente do thread e do processo que foi usado para iniciar a operação sobreposta.

WPUQueueApc usa como parâmetros de entrada um ponteiro para uma estrutura WSATHREADID (fornecida ao provedor por meio do parâmetro de entrada lpThreadId ), um ponteiro para uma função APC a ser invocada e um valor de contexto de 32 bits que é posteriormente passado para a função APC. Como apenas um único valor de contexto de 32 bits está disponível, a função APC em si não pode ser a rotina de conclusão especificada pelo cliente. Em vez disso, o provedor de serviços deve fornecer um ponteiro para sua própria função APC que usa o valor de contexto fornecido para acessar as informações de resultado necessárias para a operação sobreposta e, em seguida, invoca a rotina de conclusão especificada pelo cliente.

O protótipo para a rotina de conclusão fornecida pelo cliente é o seguinte:

);

CompletionRoutine é um espaço reservado para uma função fornecida pelo cliente. O dwError especifica o status de conclusão para a operação sobreposta, conforme indicado por lpOverlapped. O cbTransferred especifica o número de bytes retornados. Atualmente, não há valores de sinalizador definidos e dwFlags será zero. Essa função não retorna um valor.

O retorno 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, embora não necessariamente na mesma ordem em que as operações sobrepostas sejam 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

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 poderão falhar se o thread for fechado antes da conclusão das operações. Consulte ExitThread para obter mais informações.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ws2spi.h

Confira também

Função de retorno de chamada LPWSPIOCTL (ws2spi.h)

Sintaxe

Parâmetros

Valor retornado

Comentários

Compatibilidade

Requisitos

Confira também

Comentários

Comentários

Recursos adicionais