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

Статья
08/27/2023

Функция GetHostNameW получает стандартное имя узла для локального компьютера в виде строки Юникода.

Синтаксис

int WSAAPI GetHostNameW(
  [out] PWSTR name,
  [in]  int   namelen
);

Параметры

[out] name

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

[in] namelen

Длина буфера в широких символах, на которую указывает параметр name .

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

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

Код ошибки	Значение
WSAEFAULT	Параметр name является указателем NULL или не является допустимой частью адресного пространства пользователя. Эта ошибка также возвращается, если размер буфера, указанный параметром namelen , слишком мал для хранения полного имени узла.
WSANOTINITIALISED	Перед использованием этой функции должен произойти успешный вызов WSAStartup .
WSAENETDOWN	Произошел сбой сетевой подсистемы.

Функция GetHostNameW возвращает имя локального узла в буфер, указанный параметром name в Юникоде (UTF-16). Имя узла возвращается в виде строки Юникода, завершаемой null. Форма имени узла зависит от поставщика сокетов Windows — это может быть простое имя узла или полное доменное имя. Тем не менее, гарантируется, что возвращенное имя будет успешно проанализировано Командлетом GetAddrInfoW.

С ростом интернета растет потребность в определении имен узлов Интернета для других языков, не представленных кодировкой ASCII. Идентификаторы, которые упрощают эту задачу и позволяют представлять символы, отличные от ASCII (Юникод), в виде специальных строк символов ASCII (Punycode), называются интернационализированными доменными именами (IDN). Механизм под названием Интернационализация доменных имен в приложениях (IDNA) используется для стандартной обработки IDN. Функция GetHostNameW не преобразует локальное имя узла между Punycode и Юникодом. Функция GetAddrInfoW обеспечивает поддержку синтаксического анализа международного доменного имени (IDN) и выполняет кодирование и преобразование punycode/IDN.

Если функция GetHostNameW используется в ресурсе кластера в Windows Server 2012 и определена переменная среды CLUSTER_NETWORK_NAME , то значение в этой переменной среды переопределяет фактическое имя узла и возвращается. В ресурсе кластера переменная среды CLUSTER_NETWORK_NAME содержит имя кластера.

Функция GetHostNameW запрашивает поставщиков пространства имен, чтобы определить имя локального узла с помощью SVCID_HOSTNAME GUID, определенного в файле заголовка Svgguid.h . Если поставщик пространства имен не отвечает, функция GetHostNameW возвращает netBIOS-имя локального компьютера в Юникоде.

Максимальная длина (в расширенных символах) строки, возвращаемой в буфере, на которую указывает параметр name , зависит от поставщика пространства имен, но эта строка должна быть не более 256 символов. Таким образом, если в параметр name передается буфер размером 256 символов, а для параметра namelen задано значение 256, размер буфера всегда будет достаточным.

Примечание Если имя локального узла не настроено, getHostNameW должен завершиться успешно и вернуть имя узла маркера, которое может разрешить GetAddrInfoW .

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

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

Требования


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

См. также раздел

GetAddrInfoW

Функции Winsock

Справочник по Winsock

gethostname

Share via