Функция WSAAddressToStringW (winsock2.h)

Статья
11/20/2024

Функция WSAAddressToStr ing преобразует все компоненты структуры sockaddr в удобочитаемое пользователем строковое представление адреса.

Это предназначено для использования главным образом в целях отображения. Если вызывающий объект требует, чтобы перевод выполнялся определенным поставщиком, он должен предоставить соответствующую структуру WSAPROTOCOL_INFO в параметре lpProtocolInfo.

Синтаксис

INT WSAAPI WSAAddressToStringW(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in, out]      LPWSTR              lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Параметры

[in] lpsaAddress

Указатель на структуру sockaddr для преобразования в строку.

[in] dwAddressLength

Длина адреса в байтах в структуре sockaddr, на которую указывает параметр lpsaAddress. Параметр dwAddressLength может отличаться по размеру с различными протоколами.

[in, optional] lpProtocolInfo

Указатель на структуру WSAPROTOCOL_INFO для конкретного поставщика. Если это параметр NULL, вызов направляется поставщику первого протокола, поддерживающего семейство адресов, указанного в параметре lpsaAddress.

[in, out] lpszAddressString

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

[in, out] lpdwAddressStringLength

При входных данных этот параметр указывает длину буфера, на который указывает параметр lpszAddressString. Длина представлена в байтах для строк ANSI и в WCHARs для строк Юникода. В выходных данных этот параметр возвращает длину строки, включая null терминатор, фактически скопированный в буфер, на который указывает параметр lpszAddressString. Если указанный буфер недостаточно велик, функция завершается ошибкой WSAEFAULT, и этот параметр обновляется с требуемым размером.

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

Если ошибка не возникает, WSAAddressToString возвращает значение нуля. В противном случае возвращается значение SOCKET_ERROR, а определенный номер ошибки можно получить путем вызова WSAGetLastError.

Код ошибки	Значение
WSAEFAULT	Указанные lpcsAddress, lpProtocolInfo, а lpszAddressString указывают на память, которая не все в адресном пространстве процесса, или буфер, указывающий на параметр lpszAddressString слишком мал. Передайте больший буфер.
WSAEINVAL	Недопустимый параметр был передан. Эта ошибка возвращается, если параметр lpsaAddress, dwAddressLengthили lpdwAddressStringLengthNULL. Эта ошибка также возвращается, если указанный адрес не является допустимым адресом сокета или поставщик транспорта не поддерживает указанное семейство адресов.
WSAENOBUFS	Буферное пространство недоступно.
WSANOTINITIALISED	Библиотека DLL Winsock 2 не инициализирована. Приложение должно сначала вызвать WSAStartup перед вызовом функций сокетов Windows.

Замечания

Функция WSAAddressToString предоставляет преобразование строк на основе протокола независимо от протокола. Функция WSAAddressToStr ing принимает структуру адресов сокета, на которую указывает параметр lpsaAddress и возвращает указатель на NULL-завершенную строку, представляющую адрес сокета в параметре lpszAddressString. Хотя функция inet_ntoa работает только с IPv4-адресами, функция WSAAddressToStr ing работает с любым адресом сокета, поддерживаемым поставщиком Winsock на локальном компьютере, включая IPv6-адреса.

Если параметр lpsaAddress указывает на адрес сокета IPv4 (семейство адресов AF_INET), то строка адреса, возвращаемая в буфере, на которую указывает параметр lpszAddressString, находится в точечной десятичной нотации, как в "192.168.16.0", Пример IPv4-адреса в нотации с точками в десятичной нотации.

Если параметр lpsaAddress указывает на адрес сокета IPv6 (семейство адресов AF_INET6), то строка адреса, возвращаемая в буфере, на которую указывает параметр lpszAddressString в формате Internet Standard. Базовое строковое представление состоит из 8 шестнадцатеричных чисел, разделенных двоеточиями. Строка последовательных нулевых чисел заменяется двойной двоеточием. В строковом представлении IPv6-адреса может быть только одна двойная двоеточие.

Если длина буфера, на которую указывает параметр lpszAddressString, недостаточно велик, чтобы получить строковое представление адреса сокета, WSAAddressToString возвращает WSAEFAULT.

Поддержка адресов IPv6 с помощью функции WSAAddressToString добавлена в Windows XP с пакетом обновления 1 (SP1) и более поздних версий. IPv6 также необходимо установить на локальном компьютере для функции WSAAddressToString для поддержки IPv6-адресов.

Windows Phone 8: функция WSAAddressToStringW поддерживается для приложений Магазина Windows Phone в Windows Phone 8 и более поздних версиях.

Windows 8.1 и Windows Server 2012 R2: функция WSAAddressToString W поддерживается для приложений Магазина Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Заметка

Заголовок winsock2.h определяет WSAAddressToString как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP, Windows 8.1 [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	winsock2.h
библиотеки	Ws2_32.lib
DLL	Ws2_32.dll