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

Статья
08/27/2023

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

Синтаксис

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	Недостаточно памяти для выполнения операции.

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

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

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

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]
Целевая платформа	Windows
Header	winsock2.h
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll