Функция CreateSortedAddressPairs (netioapi.h)

Статья
02/29/2024

Функция CreateSortedAddressPairs принимает предоставленный список потенциальных IP-адресов назначения, связывает адреса назначения с локальными IP-адресами хост-компьютера и сортирует пары в соответствии с тем, какая пара адресов лучше всего подходит для обмена данными между двумя одноранговых узлами.

Синтаксис

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
);

Параметры

[in, optional] SourceAddressList

Должно иметь значение NULL. Зарезервировано для последующего использования.

[in] SourceAddressCount

Должно быть равно 0. Зарезервировано для последующего использования.

[in] DestinationAddressList

Указатель на массив SOCKADDR_IN6 структур, содержащих список потенциальных адресов назначения IPv6. Все IPv4-адреса должны быть представлены в формате IPv6-адресов, сопоставленных с IPv4, что позволяет приложению только IPv6 взаимодействовать с узлом IPv4.

[in] DestinationAddressCount

Количество адресов назначения, на которые указывает параметр DestinationAddressList .

[in] AddressSortOptions

Зарезервировано для последующего использования.

[out] SortedAddressPairList

Указатель для хранения массива SOCKADDR_IN6_PAIR структур, содержащих список пар IPv6-адресов, отсортированных в предпочтительном порядке обмена данными, если вызов функции выполнен успешно.

[out] SortedAddressPairCount

Указатель для хранения количества пар адресов, на которые указывает параметр SortedAddressPairList , если вызов функции выполнен успешно.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.

Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.

Код возврата	Описание
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если для параметров DestinationAddressList, SortedAddressPairList или SortedAddressPairCountзадано значение NULL или значение DestinationAddressCount больше 500. Эта ошибка также возвращается, если свойство SourceAddressList не равно NULL или параметр SourceAddressPairCount не равен нулю.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно места для обработки этой команды.
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если на локальном компьютере нет стека IPv6.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Функция CreateSortedAddressPairs принимает список исходных и целевых IPv6-адресов и возвращает список пар адресов в отсортированном порядке. Список отсортирован по тому, какая пара адресов лучше всего подходит для обмена данными между исходным и целевым адресами.

Список исходных адресов, на которые указывает SourceAddressList , в настоящее время зарезервирован для будущего и должен быть указателем NULL . SourceAddressCount в настоящее время зарезервирован для будущего и должен быть равен нулю. Функция CreateSortedAddressPairs в настоящее время использует все локальные адреса хост-компьютера для исходного списка адресов.

На список адресов назначения указывает параметр DestinationAddressList . Список адресов назначения представляет собой массив SOCKADDR_IN6 структур. Все IPv4-адреса должны быть представлены в формате IPv6-адресов, сопоставленных с IPv4, что позволяет приложению только IPv6 взаимодействовать с узлом IPv4. Дополнительные сведения о формате IPv4-адресов, сопоставленных с IPv6, см. в разделе Сокеты с двумя стеками. Параметр DestinationAddressCount содержит количество адресов назначения, на которые указывает параметр DestinationAddressList . Функция CreateSortedAddressPairs поддерживает не более 500 целевых адресов.

Если функция CreateSortedAddressPairs выполнена успешно, параметр SortedAddressPairList указывает на массив SOCKADDR_IN6_PAIR структур, содержащих отсортированные пары адресов. Если этот возвращаемый список больше не требуется, освободите память, используемую списком, вызвав функцию FreeMibTable .

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	netioapi.h (включая Iphlpapi.h)
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll