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

Статья
03/08/2023

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

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

Синтаксис

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               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, а для строк Юникода — в WCHAR. В выходных данных этот параметр возвращает длину строки, включая признак конца NULL , фактически скопированный в буфер, на который указывает параметр lpszAddressString . Если указанный буфер недостаточно велик, функция завершается сбоем с определенной ошибкой WSAEFAULT , и этот параметр обновляется требуемым размером.

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

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

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

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

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

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

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

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

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

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winsock2.h
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll