Share via

getHostNameW 函数 (winsock2.h)

  • 项目

GetHostNameW 函数以 Unicode 字符串的形式检索本地计算机的标准主机名。

语法

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

参数

[out] name

指向以 null 结尾的 Unicode 字符串接收本地主机名的缓冲区的指针。

[in] namelen

name 参数指向的缓冲区的长度（以宽字符为单位）。

返回值

如果未发生错误， GetHostNameW 将返回零。 否则，它将返回 SOCKET_ERROR ，并且可以通过调用 WSAGetLastError 来检索特定的错误代码。

错误代码 含义
WSAEFAULT
 name 参数是 NULL 指针，或者不是用户地址空间的有效部分。 如果 namelen 参数指定的缓冲区大小太小而无法容纳完整的主机名，也会返回此错误。
WSANOTINITIALISED
 在使用此函数之前，必须成功调用 WSAStartup 。
WSAENETDOWN
 网络子系统失败。

注解

GetHostNameW 函数将本地主机的名称返回到 Unicode (UTF-16) 中由 name 参数指定的缓冲区中。 主机名作为 以 null 结尾的 Unicode 字符串返回。 主机名的形式取决于 Windows 套接字提供程序，它可以是简单的主机名，也可以是完全限定的域名。 但是，可以保证 GetAddrInfoW 成功分析返回的名称。

随着 Internet 的发展，越来越需要为不由 ASCII 字符集表示的其他语言标识 Internet 主机名。 满足此需求并允许 Unicode) (非 ASCII 字符表示为特殊 ASCII 字符串 (Punycode) 的标识符称为国际化域名 (IDN) 。 (IDNA) 应用程序中称为国际化域名的机制用于以标准方式处理 IDN。 GetHostNameW 函数不会在 Punycode 和 Unicode 之间转换本地主机名。 GetAddrInfoW 函数支持国际化域名 (IDN) 分析和执行 Punycode/IDN 编码和转换。

如果在 Windows Server 2012 上的群集资源上使用 GetHostNameW 函数，并且定义了 CLUSTER_NETWORK_NAME 环境变量，则此环境变量中的值将替代实际主机名并返回。 在群集资源上， CLUSTER_NETWORK_NAME 环境变量包含群集的名称。

GetHostNameW 函数使用 Svgguid.h 头文件中定义的SVCID_HOSTNAME GUID 查询命名空间提供程序以确定本地主机名。 如果没有命名空间提供程序响应，则 GetHostNameW 函数在 Unicode 中返回本地计算机的 NetBIOS 名称。

name 参数指向的缓冲区中返回的字符串的最大长度（以宽字符为单位）取决于命名空间提供程序，但此字符串必须是 256 个或更少的宽字符。 因此，如果在 name 参数中传递了 256 个宽字符的缓冲区，并且 namelen 参数设置为 256，则缓冲区大小始终足够。

注意 如果未配置本地主机名， 则 GetHostNameW 必须成功并返回 GetAddrInfoW 可以解析的令牌主机名。
 

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

Windows 8.1和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持此函数。

要求

   
最低受支持的客户端 Windows 8.1，Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 winsock2.h
Library Ws2_32.lib
DLL Ws2_32.dll

另请参阅

GetAddrInfoW

Winsock 函数

Winsock 参考

gethostname