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

Статья
11/20/2024

Функция WSAStringToAddress преобразует сетевой адрес в стандартной форме представления текста в числовую двоичную форму в структуру sockaddr, подходящую для передачи в подпрограммы сокетов Windows, которые принимают такую структуру.

Синтаксис

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

Параметры

[in] AddressString

Указатель на строку нулевого завершения, содержащую сетевой адрес в стандартной текстовой форме для преобразования.

[in] AddressFamily

Семейство адресов сетевого адреса, на которое указывает параметр AddressString.

[in, optional] lpProtocolInfo

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

[out] lpAddress

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

[in, out] lpAddressLength

Указатель на длину буфера в байтах, на который указывает параметр lpAddress. Если вызов функции выполнен успешно, этот параметр возвращает указатель на размер структуры sockaddr, возвращаемой в параметре lpAddress. Если указанный буфер недостаточно велик, функция завершается ошибкой WSAEFAULT, и этот параметр обновляется с требуемым размером в байтах.

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

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

Код ошибки	Значение
WSAEFAULT	Буфер, на который указывает параметр lpAddress, слишком мал. Передайте больший буфер.
WSAEINVAL	Функции не смогли перевести строку в sockaddr. Дополнительные сведения см. в следующем разделе "Примечания".
WSANOTINITIALISED	WS2_32.DLL не инициализирована. Приложение должно сначала вызвать WSAStartup перед вызовом функций сокета Windows.
WSA_NOT_ENOUGH_MEMORY	Для выполнения операции недостаточно памяти.

Замечания

Функция WSAStringToAddress преобразует сетевой адрес в стандартной текстовой форме в числовую двоичную форму sockaddr.

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

Функция WSAStringToAddress завершается сбоем (и возвращает WSAEINVAL), если элемент sin_family структуры SOCKADDR_IN, который передается в параметре lpAddress в виде структуры sockaddr, не имеет значения AF_INET или AF_INET6.

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

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

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

Заметка

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

Требования

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