Função CreateSortedAddressPairs (netioapi.h)

Artigo
03/05/2024

A função CreateSortedAddressPairs usa uma lista fornecida de endereços de destino IP potenciais, emparelha os endereços de destino com os endereços IP locais do computador host e classifica os pares de acordo com qual par de endereços é mais adequado para comunicação entre os dois pares.

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API CreateSortedAddressPairs(
  [in, optional] const PSOCKADDR_IN6 SourceAddressList,
  [in]           ULONG               SourceAddressCount,
  [in]           const PSOCKADDR_IN6 DestinationAddressList,
  [in]           ULONG               DestinationAddressCount,
  [in]           ULONG               AddressSortOptions,
  [out]          PSOCKADDR_IN6_PAIR  *SortedAddressPairList,
  [out]          ULONG               *SortedAddressPairCount
);

Parâmetros

[in, optional] SourceAddressList

Deve ser NULL. Reservado para uso futuro.

[in] SourceAddressCount

Deve ser 0. Reservado para uso futuro.

[in] DestinationAddressList

Um ponteiro para uma matriz de estruturas SOCKADDR_IN6 que contêm uma lista de endereços de destino IPv6 potenciais. Todos os endereços IPv4 devem ser representados no formato de endereço IPv6 mapeado por IPv4, que permite que um aplicativo somente IPv6 se comunique com um nó IPv4.

[in] DestinationAddressCount

O número de endereços de destino apontados pelo parâmetro DestinationAddressList .

[in] AddressSortOptions

Reservado para uso futuro.

[out] SortedAddressPairList

Um ponteiro para armazenar uma matriz de estruturas SOCKADDR_IN6_PAIR que contêm uma lista de pares de endereços IPv6 classificados na ordem preferencial de comunicação, se a chamada de função for bem-sucedida.

[out] SortedAddressPairCount

Um ponteiro para armazenar o número de pares de endereços apontados pelo parâmetro SortedAddressPairList , se a chamada de função for bem-sucedida.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se os parâmetros DestinationAddressList, SortedAddressPairList ou SortedAddressPairCountforem NULL ou DestinationAddressCount for maior que 500. Esse erro também será retornado se SourceAddressList não for NULL ou o parâmetro SourceAddressPairCount não for zero.
ERROR_NOT_ENOUGH_MEMORY	Não há armazenamento suficiente disponível para processar esse comando.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv6 estiver no computador local.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função CreateSortedAddressPairs é definida no Windows Vista e posterior.

A função CreateSortedAddressPairs usa uma lista de endereços IPv6 de origem e destino e retorna uma lista de pares de endereços em ordem classificada. A lista é classificada por qual par de endereços é mais adequado para comunicação entre o endereço de origem e de destino.

A lista de endereços de origem apontados pelo SourceAddressList está atualmente reservada para o futuro e deve ser um ponteiro NULL . O SourceAddressCount está reservado no momento para o futuro e deve ser zero. A função CreateSortedAddressPairs atualmente usa todos os endereços locais do computador host para a lista de endereços de origem.

A lista de endereços de destino é apontada pelo parâmetro DestinationAddressList . A lista de endereços de destino é uma matriz de estruturas SOCKADDR_IN6 . Todos os endereços IPv4 devem ser representados no formato de endereço IPv6 mapeado por IPv4, que permite que um aplicativo somente IPv6 se comunique com um nó IPv4. Para obter mais informações sobre o formato de endereço IPv6 mapeado por IPv4, consulte Dual-Stack Sockets. O parâmetro DestinationAddressCount contém o número de endereços de destino apontados pelo parâmetro DestinationAddressList . A função CreateSortedAddressPairs dá suporte a no máximo 500 endereços de destino.

Se a função CreateSortedAddressPairs for bem-sucedida, o parâmetro SortedAddressPairList apontará para uma matriz de estruturas SOCKADDR_IN6_PAIR que contêm os pares de endereços classificados. Quando essa lista retornada não for mais necessária, libere a memória usada pela lista chamando a função FreeMibTable .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	netioapi.h (inclua Iphlpapi.h)
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll