WSAIoctl

Artigo
09/09/2008

Windows Mobile Supported Windows Embedded CE Supported

9/8/2008

Essa função permite que diversos controle de um Soquete.

Syntax

int WSAIoctl(
  SOCKET s,
  DWORD dwIoControlCode,
  LPVOID lpvInBuffer,
  DWORD cbInBuffer,
  LPVOID lpvOutBuffer,
  DWORD cbOutBuffer,
  LPDWORD lpcbBytesReturned,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameters

s
[no] Descritor identificando um Soquete.

dwIoControlCode
[no] Controlar codificar da operação para executar.

lpvInBuffer
[no] Ponteiro para o buffer de entrada.

cbInBuffer
[no] Tamanho da buffer de entrada.

lpvOutBuffer
[out] Ponteiro para a reserva saída.

cbOutBuffer
[no] Tamanho da reserva de saída.

lpcbBytesReturned
[out] Ponteiro para o real número de bytes de saída.

lpOverlapped
[no] Ponteiro para um WSAOVERLAPPED estrutura (ignorada para Soquetes nonoverlapped).

lpCompletionRoutine
[no] Ponteiro para o rotina chamado de conclusão quando a operação for concluída (ignorado para Soquetes nonoverlapped).

Return Value

Se não houver erro, essa função retornará zero. Se ocorrer um erro, será retornado um valor de SOCKET_ERROR e um código de erro específicos podem ser recuperadas por chamado de WSAGetLastError função.

A seguinte tabela mostra uma lista dos códigos de erro possível.

Código de erro	Descrição
WSAENETDOWN	Falha no subsistema da rede.
WSAEFAULT	O lpvInBuffer, lpvOutBuffer lpcbBytesReturned, lpOverlapped, ou lpCompletionRoutine argumento não é totalmente contido em um válido parte espaço de endereço de usuário, ou a cbInBuffer Ou cbOutBuffer argumento é muito pequeno.
WSAEINVAL	O dwIoControlCode parâmetro não é um válido comando, um parâmetro de entrada fornecido não é aceitável ou o comando não é aplicável para o tipo de Soquete fornecido.
WSAEINPROGRESS	A função é chamada quando um callback é em andamento.
WSAENOTSOCK	O descritor s não é um Soquete.
WSAEOPNOTSUPP	O comando IOCTL especificado não pode ser realizado.
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e conclusão será indicada em um tempo posterior.
WSAEWOULDBLOCK	O Soquete é marcado como de não bloqueio e a operação solicitada seria bloco.

Remarks

Essa função é usada para definir ou recuperar parâmetros operacionais associado com o Soquete, protocolo de transporte ou o subsistema de comunicações.

Se os dois lpOverlapped e lpCompletionRoutine São NULL, o Soquete nessa função será tratado como um Soquete nonoverlapped. Para um Soquete nonoverlapped, lpOverlapped e lpCompletionRoutine Os parâmetros são ignorados, que causar a função se comporte como o padrão ioctlsocket função, exceto que WSAIoctl Pode bloco se Soquete s está no bloqueio modo.

Se Soquete s Está em de não bloqueio modo, essa função pode retornar WSAEWOULDBLOCK quando a operação especificada não pode ser concluída imediatamente. Neste maiúsculas e minúsculas, o aplicativo pode alteração o Soquete para bloqueio modo e emita novamente a solicitação ou aguarde para o correspondente evento rede (such as FD_ROUTING_INTERFACE_CHANGE ou FD_ADDRESS_LIST_CHANGE na maiúsculas e minúsculas de SIO_ROUTING_INTERFACE_CHANGE ou SIO_ADDRESS_LIST_CHANGE) usando um mecanismo notificação Event-Based (usando WSAEventSelect).

As estruturas sobrepostas são atualizadas com os resultados de recebimento e o associado evento é signalled.

Para os soquetes sobrepostos, operações que não podem ser concluídas imediatamente serão iniciadas e conclusão será indicada em um tempo posterior. Em Windows Embedded CE, a rotina de conclusão não será chamado. Somente o mecanismo evento pode ser usado. O lpcbBytesReturned parâmetro será ignorado.

Qualquer IOCTL pode bloco indefinidamente, dependendo implementação do provedor de serviços a. Se o aplicativo não pode tolerar bloqueio em um WSAIoctl chamar, sobreposto E/S deve ser informado para o seguinte IOCTLs especialmente que provavelmente bloco SIO_ROUTING_INTERFACE_CHANGE ou SIO_ADDRESS_LIST_CHANGE.

Alguns IOCTLs específicas do protocolo também podem ser especialmente provavelmente ao bloco. Verifique o Annex específicas do protocolo relevante para qualquer disponível informações.

É possível adotar uma codificação esquema que preserva a atualmente definido ioctlsocket Códigos operação enquanto fornecendo uma maneira conveniente para partição espaço identificador codificar a operação no máximo como o dwIoControlCode parâmetro é agora um 32-bit entidade. O dwIoControlCode parâmetro é compilado para permitir independência protocolo e fornecedor quando adicionando novos códigos controle, mantendo compatibilidade com versões anteriores com o sockets do Windows (Winsock) 1.1 e códigos controle UNIX. A seguinte tabela mostra a forma para o dwIoControlCode parâmetro.

Eu	O	V	T	Fornecedor/família de endereços	O 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

Eu será definido se o buffer de entrada é válido para a codificar, como com IOC_IN.

O será definido se a reserva saída é válido para a codificar, como com IOC_OUT. Definir códigos com entrada e saída parâmetros ambos Eu e O.

V é definido se não houver nenhum parâmetro para a codificar, como com IOC_VOID.

T é um 2-quantidade bit que define o tipo do IOCTL.

O seguinte valores são definidos para T:

0 – O IOCTL é um padrão codificar UNIX IOCTL, como com FIONREAD e FIONBIO.
1 – O IOCTL é um genérico codificar Winsock IOCTL. Novos códigos IOCTL definidos para sockets do Windows (Winsock) terá T == 1.
2 – O IOCTL aplica-se somente a um família de endereços específico.
3 – O IOCTL aplica-se somente ao provedor de um fornecedor específico. Este tipo permite que empresas para ser atribuído um número fornecedor que consta o Família Vendor/Address campo. Em seguida, o fornecedor pode definir novos IOCTLs específicos para esse fornecedor sem registrar o IOCTL com uma câmera de compensação, fornecendo, assim, fornecedor flexibilidade e privacidade.
Família Vendor/Address – Uma 11 - quantidade bit que define o fornecedor que possui a codificar (se T == 3) ou que contém o família de endereços ao qual a codificar se aplica se ( T == 2). Se este for um (codificar IOCTL UNIXT == 0), em seguida, esse campo tem o mesmo valor como o codificar em UNIX. Se este for um genérico (IOCTL sockets do Windows (Winsock)T == 1), em seguida, esse campo pode ser usado como uma extensão do parâmetro codificar para fornecer valores adicionais codificar.
O código – A 16 - bit quantidade que contém a codificar IOCTL específica para a operação.

O seguinte códigos IOCTL UNIX (comandos) são com suporte.

FIONBIO

Habilita ou desabilita de não bloqueio FIONBIO modo em Soquete s. lpvInBuffer Pontos em um sem assinatura longos, que é diferente de zero se de não bloqueio modo deve ser habilitado e zero se ele for ser desativado. Quando um Soquete for criada, ela opera no bloqueio modo (ou seja, de não bloqueio modo está desativado). Isso é consistente com soquetes BSD.

O WSAEventSelect Definir automaticamente rotinas de Soquete para de não bloqueio modo. Se WSAEventSelect Foi emitido em um Soquete, em seguida, qualquer tentativa de usar WSAIoctl Para definir a Soquete voltar para bloqueio modo falhará com WSAEINVAL. Para definir a Soquete voltar para bloqueio modo, um aplicativo deve primeiro desativar WSAEventSelect Por chamado WSAEventSelect Com o lNetworkEvents parâmetro igual a zero.

FIONREAD

FIONREAD determina a quantidade de dados que podem ser ler atomicamente do Soquete s. lpvOutBuffer Pontos em um sem assinatura tempo no qual WSAIoctl Armazena o resultado. Se s é fluxo-orientados (por exemplo, tipo SOCK_STREAM), FIONREAD retorna a quantidade total de dados que podem ser ler em um único operação de recebimento; Isso é geralmente o mesmo que a quantidade total de dados enfileirado na Soquete (como o fluxo de dados é orientado a byte, isso não é garantido). Se Soquete s é orientado a mensagem (por exemplo, tipo SOCK_DGRAM), FIONREAD retorna o tamanho do datagrama a primeira (mensagem) enfileirado na Soquete.

O provedor serviço Windows Embedded CE não suporte o comando SIO_FLUSH. Se uma operação sobreposta conclui imediatamente, WSAIoctl Retorna um valor de zero e o lpcbBytesReturned parâmetro é atualizado com o número de bytes de reserva de saída. Se a operação sobreposta é iniciada com êxito e será completo mais recente, essa função retorna SOCKET_ERROR e indica código de erro WSA_IO_PENDING. Neste maiúsculas e minúsculas, lpcbBytesReturned não é atualizado. Quando concluir a operação sobreposta, a quantidade de dados na reserva de saída é indicada através de cbTransferred parâmetro na rotina de conclusão (se especificado) ou através de lpcbTransfer parâmetro no WSAGetOverlappedResult.

Quando chamado com um Soquete sobreposto, o lpOverlapped parâmetro deve ser válido para a duração da operação sobreposta. O lpOverlapped parâmetro contém o endereço de um WSAOVERLAPPED estrutura.

Se a pasta lpCompletionRoutine parâmetro é NULL, o hEvent parâmetro de lpOverlapped é sinalizado quando concluir a operação sobreposta se ela contiver um válido evento objeto identificador. Um aplicativo pode usar WSAGetOverlappedResult Para esperar ou pesquisar no objeto de evento.

Se lpCompletionRoutine não é NULL, o hEvent parâmetro será ignorado e pode ser usado, o aplicativo para transmitir informações contexto para a rotina de conclusão. Um chamador que passa um não-NULL lpCompletionRoutine e chamadas posteriores WSAGetOverlappedResult para o mesmo E/S sobreposto solicitação não pode ser definido de fWait parâmetro para essa chamada de WSAGetOverlappedResult para TRUE. Neste maiúsculas e minúsculas, o uso das hEvent parâmetro é indefinido e tentando esperar na hEvent parâmetro poderia gerar resultados imprevisíveis.

O protótipo do função callback é da seguinte maneira:

        
        
        dwError
        
        
        cbTransferred
        
        
        lpOverlapped
        
        
        dwFlags

CompletionRoutine é um espaço reservado para uma função Application-defined ou Library-defined. O dwError parâmetro especifica o status de conclusão para a operação sobreposta conforme indicado pelo lpOverlapped. O cbTransferred parâmetro especifica o número de bytes retornadas. Atualmente, há não valores sinalizador definidos e dwFlags Será zero. O CompletionRoutine função NÃO retorna um valor.

Retornando desta função permite invocação de pendente outra rotina de conclusão para este Soquete. As rotinas de conclusão podem ser chamado em qualquer ordem, não necessariamente na mesma ordem as operações sobrepostas são concluídas.

Compatibilidade

Os códigos IOCTL com T == 0 são um subconjunto dos códigos de Ioctl usados em soquetes Berkeley. Em particular, há um comando equivalente that is para FIOASYNC.

Observações para Bluetooth

O WSAIoctl e ioctlsocket controle funções o modo de um Soquete. WSAIoctl Requer 2.2 sockets do Windows (Winsock) e permite sobrepostas ou operação assíncrona. O ioctlsocket função pode ser usada com sockets do Windows (Winsock) 1.1 ou posterior. O seguinte são códigos IOCTL Bluetooth-específica disponível:

SIO_RFCOMM_COMM_PARAMETERS define ou consultas atributos modem. As estruturas usadas e a semântica chamado é as mesmas como RFCOMM_COMM_PARAMETERS TDI_ACTION.
SIO_RFCOMM_WAIT_MODEM_STATUS obtém de atual status do modem. A semântica é os mesmos RFCOMM_MODEM_STATUS TDI_ACTION.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later