Código de controle SIO_ADDRESS_LIST_QUERY
Descrição
O código de controle SIO_ADDRESS_LIST_QUERY obtém uma lista de endereços de transporte local 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.
Para executar essa operação, chame a função WSAIoctl ou WSPIoctl com os parâmetros a seguir.
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_ADDRESS_LIST_QUERY, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
(LPVOID) lpvOutBuffer, // output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
);
int WSPIoctl(
(socket) s, // descriptor identifying a socket
SIO_ADDRESS_LIST_QUERY, // dwIoControlCode
NULL, // lpvInBuffer
0, // cbInBuffer
(LPVOID) lpvOutBuffer, // output buffer
(DWORD) cbOutBuffer, // size of output buffer
(LPDWORD) lpcbBytesReturned, // number of bytes returned
(LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
(LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine, // completion routine
(LPWSATHREADID) lpThreadId, // a WSATHREADID structure
(LPINT) lpErrno // a pointer to the error code.
);
Parâmetros
s
Um descritor que identifica um soquete.
Dwiocontrolcode
O código de controle da operação. Use SIO_ADDRESS_LIST_QUERY para esta operação.
Lpvinbuffer
Um ponteiro para o buffer de entrada. Esse parâmetro não é usado para essa operação.
Cbinbuffer
O tamanho, em bytes, do buffer de entrada. Esse parâmetro não é usado para essa operação.
Lpvoutbuffer
Um ponteiro para o buffer de saída.
cbOutBuffer
O tamanho, em bytes, do buffer de saída.
Lpcbbytesreturned
Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados armazenados no buffer de saída.
lpvOverlapped
Um ponteiro para uma estrutura WSAOVERLAPPED .
Se o soquete s tiver sido criado sem o atributo sobreposto, o parâmetro lpOverlapped será ignorado.
Se s tiver sido aberto com o atributo sobreposto e o parâmetro lpOverlapped não for NULL, a operação será executada como uma operação sobreposta (assíncrona). Nesse caso, o parâmetro lpOverlapped deve apontar para uma estrutura WSAOVERLAPPED válida.
Para operações sobrepostas, a função WSAIoctl ou WSPIoctl retorna imediatamente e o método de conclusão apropriado é sinalizado quando a operação é concluída. Caso contrário, a função não retornará até que a operação seja concluída ou ocorra um erro.
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).
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 para o mesmo) até que a função WPUQueueApc retorne.
Nota Esse parâmetro se aplica somente à função WSPIoctl .
Lperrno
Um ponteiro para o código de erro.
Nota Esse parâmetro se aplica somente à função WSPIoctl .
Valor retornado
Se a operação for concluída com êxito, a função WSAIoctl ou WSPIoctl retornará zero.
Se a operação falhar ou estiver pendente, a função WSAIoctl ou WSPIoctl retornará SOCKET_ERROR. Para obter informações de erro estendidas, chame WSAGetLastError.
| Código do erro | Significado |
|---|---|
| WSA_IO_PENDING | Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. |
| WSA_OPERATION_ABORTED | Uma operação sobreposta foi cancelada devido ao fechamento do soquete ou à execução do SIO_FLUSH comando IOCTL . |
| WSAEFAULT | O parâmetro lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário. |
| WSAEINPROGRESS | A função é invocada quando um retorno de chamada está em andamento. |
| WSAEINTR | Uma operação de bloqueio foi interrompida. |
| 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. Esse erro será retornado se o parâmetro cbInBuffer não estiver definido como NULL. |
| WSAENETDOWN | O subsistema de rede falhou. |
| WSAENOBUFS | Nenhum espaço em buffer disponível. |
| WSAENOPROTOOPT | Não há suporte para a opção de soquete no protocolo especificado. |
| WSAENOTSOCK | O descritor s não é um soquete. |
| WSAEOPNOTSUPP | Não há suporte para o comando IOCTL especificado. Esse erro será retornado se o SIO_ADDRESS_LIST_QUERY IOCTL não tiver suporte do provedor de transporte. |
Comentários
O SIO_ADDRESS_LIST_QUERY IOCTL tem suporte no Windows 2000 e versões posteriores do sistema operacional.
O código de controle SIO_ADDRESS_LIST_QUERY obtém uma lista de endereços de transporte local 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.
Para a família de endereços AF_INET6, todos os endereços são retornados, exceto o seguinte:
- Qualquer endereço IP em que o estado de detecção de endereço duplicado (DAD) não é IpDadStatePreferred.
- Qualquer endereço IP com um nível de escopo inferior a ScopeLevelSubnet em uma interface em que o tipo de interface é IF_TYPE_SOFTWARE_LOOPBACK. Isso significa que os endereços link-local (fe80:*) e loopback (::1) em interfaces do tipo IF_TYPE_SOFTWARE_LOOPBACK serão excluídos, mas não se esses endereços estiverem em uma interface com um tipo diferente.
Para a família de endereços AF_INET , todos os endereços são retornados, exceto o seguinte:
- Qualquer endereço IP em que o estado de detecção de endereço duplicado (DAD) não é IpDadStatePreferred.
- Qualquer endereço IP em uma interface em que o tipo de interface é IF_TYPE_SOFTWARE_LOOPBACK e o link é local. Isso significa que os endereços link-local (169.254.) e loopback (127.) em interfaces do tipo IF_TYPE_SOFTWARE_LOOPBACK serão excluídos, mas não se esses endereços estiverem em uma interface com um tipo diferente.
Para obter mais informações sobre o estado DAD, consulte a documentação do Auxiliar de IP sobre a estrutura de IP_DAD_STATE enumeração e IP_ADAPTER_UNICAST_ADDRESS e a documentação do MIB sobre a estrutura de MIB_UNICASTIPADDRESS_ROW . Para obter mais informações sobre o tipo de interface, consulte a documentação do Auxiliar de IP sobre a estrutura IP_ADAPTER_ADDRESSES e a função GetAdaptersAddresses e a documentação do MIB sobre MIB_IF_ROW2 estrutura. Para obter mais informações sobre o nível de escopo, consulte a documentação do Auxiliar de IP sobre a estrutura de IP_ADAPTER_ADDRESSES e a enumeração SCOPE_LEVEL .
A lista retornada no buffer de saída apontado pelo parâmetro lpvOutBuffer está na forma de uma estrutura SOCKET_ADDRESS_LIST .
Se o buffer de saída especificado no parâmetro lpvOutBuffer não for grande o suficiente para conter a lista de endereços, SOCKET_ERROR será retornado como resultado desse IOCTL e WSAGetLastError retornará WSAEFAULT. O tamanho necessário, em bytes, para o buffer de saída é retornado no parâmetro 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 completamente contido em uma parte válida do espaço de endereço do usuário.
O SIO_ADDRESS_LIST_QUERY IOCTL normalmente é chamado de forma síncrona com o parâmetro lpvOverlapped definido como NULL, já que a lista de endereços é retornada imediatamente.
Nota Em ambientes do Windows Plug-n-Play, os endereços podem ser adicionados e removidos dinamicamente. Portanto, os aplicativos não podem depender das 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 evento de FD_ADDRESS_LIST_CHANGE . A seguinte sequência de ações pode ser usada para garantir que o aplicativo sempre tenha informações da lista de endereços atual:
- Emitir o SIO_ADDRESS_LIST_CHANGE IOCTL
- Emitir o SIO_ADDRESS_LIST_QUERY IOCTL
- Sempre que a chamada IOCTL SIO_ADDRESS_LIST_CHANGE notificar a aplicação de uma 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.
No Microsoft Windows Software Development Kit (SDK) lançado para Windows Vista e posterior, a organização de arquivos de cabeçalho foi alterada e o código de controle SIO_ADDRESS_LIST_QUERY é definido no arquivo de cabeçalho Ws2def.h . Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Winsock2.h e nunca deve ser usado diretamente.