WSPIoctl

9/8/2008

Essa função controla o modo de um Soquete.

Syntax

int WSPIoctl(
  SOCKET s,
  DWORD dwIoControlCode,
  LPVOID lpvInBuffer,
  DWORD cbInBuffer,
  LPVOID lpvOutBuffer,
  DWORD cbOutBuffer,
  LPDWORD lpcbBytesReturned,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  LPWSATHREADID lpThreadId,
  LPINT lpErrno 
);

Parameters

• s
  [no] Identificador para um Soquete.

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

• lpvInBuffer
  [no] Endereço de buffer de entrada.

• cbInBuffer
  [no] Tamanho de buffer de entrada.

• lpvOutBuffer
  [out] Endereço de reserva saída.

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

• lpcbBytesReturned
  [out] Ponteiro para o tamanho do conteúdo do buffer de saída.

• lpOverlapped
  [no] Endereço do 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).

• lpThreadId
  [no] Ponteiro para um WSATHREADID estrutura a ser usado, o provedor para determinar o segmento para executar.

• lpErrno
  [out] Ponteiro para o código de erro.

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 nonoverlapped soquetes, lpOverlapped e lpCompletionRoutine Os parâmetros são ignorados e esta função pode bloco se Soquete s está no bloqueio modo. Observe que se Soquete s Está em de não bloqueio modo, essa função pode retornar WSAEWOULDBLOCK se a operação especificada não pode ser concluída imediatamente. Neste maiúsculas e minúsculas, o cliente Windows Sockets SPI 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 em maiúsculas e minúsculas de SIO_ROUTING_INTERFACE_CHANGE ou SIO_ADDRESS_LIST_CHANGE) Usar mensagem Windows com mecanismo notificação. 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. Status de conclusão finais é recuperada por WSPGetOverlappedResult.

Qualquer IOCTL pode bloco indefinidamente, dependendo de implementação do provedor de serviço. Se o cliente Windows Sockets SPI não é possível tolerar bloqueio em um WSPIoctl chamar, sobreposto E/S poderia ser informado para os IOCTLs que provavelmente ao bloco. A seguinte lista mostra esses IOCTLs:

• SIO_ROUTING_INTERFACE_CHANGE
• SIO_ADDRESS_LIST_CHANGE

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

Em tanto quanto o dwIoControlCode parâmetro é agora um 32-bit entidade, é possível adotar uma codificação esquema que oferece uma maneira conveniente para o espaço identificador Opcode partição. O dwIoControlCode parâmetro é construído para permitir independência protocolo e fornecedor quando adicionando novos códigos controle, mantendo compatibilidade com versões anteriores com códigos controle UNIX e Windows Sockets 1.1. O dwIoControlCode parâmetro tem a seguinte forma.

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

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

V Definir se há sem parâmetros para a codificar, como com IOC_VOID.

T Uma quantidade Two-bit que define o tipo do IOCTL. O seguinte valores são definidos:

0 O IOCTL é um padrão codificar UNIX IOCTL, como com FIONREAD e FIONBIO.

1 O IOCTL é um genérico codificar Windows Sockets 2 IOCTL. Novos códigos IOCTL definidos para 2 Soquetes do Windows 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 Fornecedor/AddressFamily membro. 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.

O Família fornecedor/endereço é um 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 membro tem o mesmo valor como o codificar em UNIX. Se este for um genérico (Soquetes do Windows 2 IOCTLT == 1), em seguida, esse membro pode ser usado como uma extensão de membro de codificar para fornecer valores adicionais codificar.

O código A codificar IOCTL específica para a operação.

O seguinte comandos UNIX estão com suporte.

• FIONBIO
  Habilita ou desabilita de não bloqueio modo em Soquete s. lpvInBuffer pontos em uma 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 Berkeley Software Distribution (BSD).

  O WSPEventSelect Rotina automaticamente define um Soquete para de não bloqueio modo. Se WSPEventSelect Foi emitido em um Soquete, em seguida, qualquer tentativa de usar WSPIoctl Para definir a Soquete voltar para bloqueio modo falhará com WSAEINVAL. Para definir a Soquete voltar para bloqueio modo, um Windows Sockets SPI cliente deve primeiro desativar WSPEventSelect Por chamado WSPEventSelect Com o lNetworkEvents parâmetro igual a zero.

• FIONREAD
  Determina a quantidade de dados que podem ser ler atomicamente do Soquete s. lpvOutBuffer Pontos em um sem assinatura tempo no qual WSPIoctl Armazena o resultado. Se s é transmitir orientado (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. Se s é mensagem orientada (por exemplo, tipo SOCK_DGRAM), FIONREAD Retorna o tamanho do datagrama a primeira (mensagem) enfileirado na Soquete.

O seguinte comandos 2 Soquetes do Windows estão com suporte.

• SIO_GET_BROADCAST_ADDRESS(opcode configuração: O, T == 1)
  Este IOCTL preenche a reserva saída com uma sockaddr estrutura contendo um transmitir adequado endereço para uso com WSPSendTo.

• SIO_MULTIPOINT_LOOPBACK(opcode configuração: Eu, T == 1)
  Os controles se dados enviados em uma sessão multiponto sejam recebidos pela Soquete mesmo sobre o local também hospedar. Um valor de TRUE faz com que o recebimento auto-retorno para ocorrer enquanto um valor de FALSE proíbe que isso.

• SIO_MULTICAST_SCOPE(opcode configuração: Eu, T == 1)
  Especifica o escopo pela qual Multicast transmissões irão ocorrer. Escopo é definido como o número de segmentos rede roteada para ser abordados. Um escopo de zero indicaria que a Multicast a transmissão não poderia ser colocada sobre o rede com fio, mas poderia ser disseminated em soquetes dentro de local hospedar. Um valor escopo 1 (o usar como padrão) indica que a transmissão será colocada sobre o rede com fio, mas será Não cruzado quaisquer roteadores. Valores mais altos escopo determinam o número de roteadores que podem ser ultrapassados. Observe que isso corresponde ao parâmetro Time-To-Live (TTL) em multicast IP.

• SIO_ROUTING_INTERFACE_QUERY(opcode configuração: Eu, O, T == 1)
  Para obter o endereço do local interface (representado como sockaddr estrutura) que deve ser usado para enviar para o remoto endereço especificado na buffer de entrada (como sockaddr). Multicast remoto endereços podem ser enviados no buffer de entrada para get o endereço da interface preferencial para Multicast a transmissão. Em qualquer maiúsculas e minúsculas, o endereço interface retornado pode ser usado pelo aplicativo em um subseqüentes BIND solicitação.

  Observe que as rotas são assunto a alteração. Portanto, clientes SPI Soquete Windows Não é possível dependem de informações retornadas pelo SIO_ROUTING_INTERFACE_QUERY ser persistentes. Clientes SPI podem registrar para roteamento notificações alteração usando a IOCTL SIO_ROUTING_INTERFACE_CHANGE, que fornece para notificação por um sobreposto E/S ou um FD_ROUTING_INTERFACE_CHANGE evento. A seguinte seqüência de ações pode ser usada para garantir que o cliente Windows Socket SPI sempre tem atual roteamento informações interface para um determinado destino:

  1. Problema IOCTL SIO_ROUTING_INTERFACE_CHANGE.
  2. Problema IOCTL SIO_ROUTING_INTERFACE_QUERY.
  3. Sempre que IOCTL SIO_ROUTING_INTERFACE_CHANGE Notifica o cliente WinSock SPI de alteração roteamento através de E/S sobreposto (tanto por sinalização FD_ROUTING_INTERFACE_CHANGE evento), a seqüência inteira de ações deve ser repetida.

  Se reserva saída não é grande o suficiente para conter o endereço interface, SOCKET_ERROR é retornados como resultado deste IOCTL. O exigido tamanho da reserva de saída será retornado em lpcbBytesReturned Nesta maiúsculas e minúsculas. Observe o código de erro WSAEFAULT também é retornado se a lpvInBuffer, lpvOutBuffer, Ou lpcbBytesReturned parâmetro não é totalmente contido em um válido parte espaço de endereço o usuário.

  Se o endereço de destino especificado na buffer de entrada não puder ser acessado por meio de qualquer da disponível interfaces, SOCKET_ERROR é retornado como resultado deste IOCTL.

• SIO_ROUTING_INTERFACE_CHANGE(opcode configuração: Eu, T == 1)
  Para receber notificação de alteração de interface que deve ser usada para alcançar o remoto endereço na buffer de entrada (especificado como um sockaddr estrutura). Há informações saída serão fornecidas na conclusão deste IOCTL; a conclusão simplesmente indica que a interface roteamento para um determinado destino foi alterado e deve ser consultado novamente por meio SIO_ROUTING_INTERFACE_QUERY.

  Presume-se (embora não exigido) que o cliente Windows Socket SPI usa E/S sobreposto para ser notificado sobre roteamento alteração interface a conclusão de SIO_ROUTING_INTERFACE_CHANGE solicitação. Como alternativa, se a IOCTL SIO_ROUTING_INTERFACE_CHANGE é emitido em um de não bloqueio Soquete e Sem sobreposto (parâmetroslpOverlapped / CompletionRoutine estão definidos para NULL), ele serão completo imediatamente com erro WSAEWOULDBLOCK e o cliente Windows Socket SPI pode em seguida, aguardar roteamento eventos alteração usando uma chamar para WSPEventSelect.

  Ele é reconhecido que informações roteamento permaneça estáveis na maioria dos casos. Portanto, exigir que o cliente Windows Sockets SPI para manter múltiplo pendente IOCTLs — para notificações sobre todos os destinos que ele está interessado em, bem como ter que controlar manter provedor de serviço de todos eles — será desnecessariamente ocupar recursos sistema significativos. Essa situação pode ser evitada pelo estendendo o significado da entrada Parâmetros e relaxando requisitos provedor de serviço, conforme descrito abaixo.

  O cliente Windows Sockets SPI pode especificar uma família protocolo endereço curinga específico (mesmo que é usado em BIND chamar quando solicitar para BIND para qualquer disponível endereço) a solicitação notificações de alterações roteamento. Isso permite que o cliente Windows Sockets SPI para manter apenas um pendente SIO_ROUTING_INTERFACE_CHANGE Para todos os soquetes/destinos ele tenha e, em seguida, usar SIO_ROUTING_INTERFACE_QUERY Para o real get informações roteamento.

  Provedor de serviço pode optar por ignorar as informações fornecidas pelo cliente de Windows Sockets SPI no buffer de entrada das SIO_ROUTING_INTERFACE_CHANGE (como se o cliente Windows Sockets SPI especificado um endereço curinga) e completo de IOCTL SIO_ROUTING_INTERFACE_CHANGE ou sinal FD_ROUTING_INTERFACE_CHANGE evento no evento de qualquer roteamento alteração informações (não apenas a rota para o destino especificado na buffer de entrada).

• SIO_ADDRESS_LIST_QUERY(opcode configuração: Eu, O, T == 1)
  Para obter uma lista de local endereços transporte de família protocolo do Soquete ao qual o cliente Windows Sockets SPI pode BIND. A lista retornada na reserva de saída usará o formato no seguinte amostra de código.

  typedef struct _SOCKET_ADDRESS_LIST {
    INT iAddressCount;
    .SOCKET_ADDRESS Address[1];
  } SOCKET_ADDRESS_LIST, FAR * LPSOCKET_ADDRESS_LIST;
  Members:
    iAddressCount- number of address structures in the list;
    Address- array of protocol family specific address structures.
  

  Observe que em ambientes Win32 Plug and Play, os endereços podem ser adicionados e removidos dinamicamente. Portanto, os clientes SPI Soquetes do Windows não é possível dependem de informações retornadas pela SIO_ADDRESS_LIST_QUERY ser persistentes. Clientes SPI Soquetes do Windows podem registrar para notificações alteração endereço através de IOCTL SIO_ADDRESS_LIST_CHANGE que fornece para notificação por qualquer evento sobreposto E/S ou FD_ADDRESS_LIST_CHANGE. A seguinte seqüência de ações pode ser usada para garantir que o cliente Windows Sockets SPI sempre tem atual endereço lista informações:

  1. Emita IOCTL SIO_ADDRESS_LIST_CHANGE.
  2. Emita IOCTL SIO_ADDRESS_LIST_QUERY.
  3. Sempre que IOCTL SIO_ADDRESS_LIST_CHANGE Notifica o cliente Windows Sockets SPI do endereço lista alteração (seja através de E/S sobreposta ou por sinalização evento FD_ADDRESS_LIST_CHANGE), a seqüência inteira de ações deve ser repetida.
     Se a reserva saída não é grande o suficiente para conter a lista endereço, SOCKET_ERROR será retornado como resultado deste IOCTL. O exigido tamanho da reserva de saída será retornado em lpcbBytesReturned Nesta maiúsculas e minúsculas. Observe o código de erro WSAEFAULT também é retornado se a lpvInBuffer, lpvOutBuffer, Ou lpcbBytesReturned parâmetro não é totalmente contido em um válido parte espaço de endereço o usuário.

• SIO_ADDRESS_LIST_CHANGE(opcode configuração: T == 1)
  Para receber notificação de alterações na lista de local endereços transporte de família protocolo do Soquete ao qual o cliente Windows Sockets SPI pode BIND. Há informações saída serão fornecidas na conclusão deste IOCTL; a conclusão simplesmente indica que a lista de disponível local foi alterado e deve ser consultado novamente por endereços SIO_ADDRESS_LIST_QUERY.

  Presume-se (embora não exigido) que o cliente Windows Sockets SPI usa E/S sobreposto para ser notificado da alteração por conclusão da solicitação SIO_ADDRESS_LIST_CHANGE. Como alternativa, se o IOCTL SIO_ADDRESS_LIST_CHANGE é emitido em um de não bloqueio Soquete e Sem sobreposto (parâmetroslpOverlapped e lpCompletionRoutine estão definidos para NULL), ele será completo imediatamente com erro WSAEWOULDBLOCK. O cliente Windows Sockets SPI, em seguida, pode aguardar os eventos alteração lista endereço por um chamar para WSPEventSelect.

Quando chamado com um Soquete sobreposto, o lpOverlapped parâmetro deve ser válido para a duração da operação sobreposta. O seguinte mostra amostra de código o WSAOVERLAPPED formato estrutura.

typedef struct _WSAOVERLAPPED {
  DWORD Internal;      // reserved
  DWORD InternalHigh;  // reserved
  DWORD Offset;        // reserved
  DWORD OffsetHigh;    // reserved
  WSAEVENT hEvent;
} WSAOVERLAPPED, FAR* LPWSAOVERLAPPED;

Se a pasta lpCompletionRoutine parâmetro é NULL, os sinais provedor serviço o hEvent membro de lpOverlapped Quando a operação sobreposta conclui se ela contiver um válido evento objeto identificador. O cliente Windows Sockets SPI pode usar WSPGetOverlappedResult Para pesquisar ou aguarde no objeto de evento.

Se lpCompletionRoutine não é NULL, o hEvent membro será ignorado e pode ser usado pelo cliente de Windows Sockets SPI para transmitir informações contexto para a rotina de conclusão. Um cliente 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 membro é indefinido e tentando esperar na hEvent membro poderia gerar resultados imprevisíveis.

É responsabilidade do provedor de serviços para organizar de invocação de rotina specified–completion a cliente quando concluir a operação sobreposta. Porque a rotina de conclusão deve ser executado no contexto do mesmo segmento que iniciou a operação sobreposta, ele não pode ser chamado diretamente do provedor de serviço. .

O seguinte amostra de código mostra o protótipo para a rotina de conclusão Client-supplied.

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

CompletionRoutine é um espaço reservado para uma função Client-supplied. O dwError Especifica o status de conclusão para a operação sobreposta conforme indicado pelo lpOverlapped. O cbTransferred Especifica o número de bytes retornadas. Atualmente, há não valores sinalizador definidos e dwFlags Será zero. Essa 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, embora não necessariamente na mesma ordem que 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 que é equivalente a FIOASYNC.

Return Value

Se nenhum erro e a operação foi concluída imediatamente, WSPIoctl Retorna zero. Observe que neste maiúsculas e minúsculas a rotina de conclusão, se especificado, será já foram enfileirado. Caso contrário, será retornado um valor de SOCKET_ERROR e um código de erro específico está disponível em lpErrno. O código de erro WSA_IO_PENDING indica que uma operação sobreposta foi iniciada com êxito e que conclusão será indicada em um tempo posterior. Quaisquer outros código de erro indica que nenhuma operação sobreposta foi iniciada e nenhuma indicação de conclusão será ocorrer.

A seguinte tabela mostra os códigos de erro possível.

Requirements

See Also

Reference

WSPSocket
WSPSetSockOpt
WSPGetSockOpt