GetComputerNameExA 函数 (sysinfoapi.h)

项目
08/26/2023

检索与本地计算机关联的 NetBIOS 或 DNS 名称。当系统从注册表读取名称时，会在系统启动时建立这些名称。

语法

BOOL GetComputerNameExA(
  [in]      COMPUTER_NAME_FORMAT NameType,
  [out]     LPSTR                lpBuffer,
  [in, out] LPDWORD              nSize
);

参数

[in] NameType

要检索的名称的类型。此参数是 COMPUTER_NAME_FORMAT 枚举类型的值。下表提供了其他信息。

值	含义
ComputerNameDnsDomain	分配给本地计算机的 DNS 域的名称。如果本地计算机是群集中的节点， lpBuffer 将接收群集虚拟服务器的 DNS 域名。
ComputerNameDnsFullyQualified	唯一标识本地计算机的完全限定 DNS 名称。此名称是 DNS 主机名和 DNS 域名的组合，格式为 HostName.DomainName。如果本地计算机是群集中的节点， lpBuffer 将接收群集虚拟服务器的完全限定 DNS 名称。
ComputerNameDnsHostname	本地计算机的 DNS 主机名。如果本地计算机是群集中的节点， lpBuffer 将接收群集虚拟服务器的 DNS 主机名。
ComputerNameNetBIOS	本地计算机的 NetBIOS 名称。如果本地计算机是群集中的节点， lpBuffer 将接收群集虚拟服务器的 NetBIOS 名称。
ComputerNamePhysicalDnsDomain	分配给本地计算机的 DNS 域的名称。如果本地计算机是群集中的节点，则 lpBuffer 接收本地计算机的 DNS 域名，而不是群集虚拟服务器的名称。
ComputerNamePhysicalDnsFullyQualified	唯一标识计算机的完全限定 DNS 名称。如果本地计算机是群集中的节点， lpBuffer 将接收本地计算机的完全限定 DNS 名称，而不是群集虚拟服务器的名称。此完全限定的 DNS 名称是 DNS 主机名和 DNS 域名的组合，格式为 HostName.DomainName。
ComputerNamePhysicalDnsHostname	本地计算机的 DNS 主机名。如果本地计算机是群集中的节点， lpBuffer 将接收本地计算机的 DNS 主机名，而不是群集虚拟服务器的名称。
ComputerNamePhysicalNetBIOS	本地计算机的 NetBIOS 名称。如果本地计算机是群集中的节点， lpBuffer 将接收本地计算机的 NetBIOS 名称，而不是群集虚拟服务器的名称。

[out] lpBuffer

指向接收计算机名称或群集虚拟服务器名称的缓冲区的指针。

名称的长度可能大于MAX_COMPUTERNAME_LENGTH个字符，因为 DNS 允许更长的名称。若要确保此缓冲区足够大，请将此参数设置为 NULL ，并使用 lpnSize 参数中返回的所需缓冲区大小。

[in, out] nSize

输入时，指定缓冲区的大小（以 TCHAR 为单位）。在输出时，接收复制到目标缓冲区的 TCHAR 数，不包括终止 null 字符。

如果缓冲区太小，函数将失败， GetLastError 将返回ERROR_MORE_DATA。此参数接收所需缓冲区的大小，包括终止 null 字符。

如果 lpBuffer 为 NULL，则此参数必须为零。

返回值

如果函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。可能的值包括以下值。

返回代码	说明
ERROR_MORE_DATA	lpBuffer 缓冲区太小。 lpnSize 参数包含接收名称所需的字节数。

注解

如果未为本地计算机设置组策略， GetComputerNameEx 函数将检索在系统启动时建立的 NetBIOS 或 DNS 名称。如果设置了组策略，该函数将返回组策略设置的主域名。在用户重新启动计算机之前， SetComputerName 或 SetComputerNameEx 函数所做的名称更改不会生效。

如果未将本地计算机配置为使用 DNS 名称， GetComputerNameEx 将不会返回 DNS 信息。若要配置计算机以执行此操作，请按照操作系统帮助中概述的步骤更改计算机的主 DNS 后缀，然后重新启动计算机。

如果本地计算机是群集中的节点，则此函数的行为可能会受到影响。有关详细信息，请参阅 ResUtilGetEnvironmentWithNetName 和 UseNetworkName。

如果使用的是使用不同 DNS 布局的环境，其中计算机的 FQDN 与其域的 FQDN 不匹配，请改用 LsaQueryInformationPolicy 。

若要编译使用此函数的应用程序，请将_WIN32_WINNT宏定义为 0x0500 或更高版本。有关详细信息，请参阅使用 Windows 标头。

示例

#define _WIN32_WINNT 0x0500

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _tmain(void)
{
    TCHAR buffer[256] = TEXT("");
    TCHAR szDescription[8][32] = {TEXT("NetBIOS"), 
        TEXT("DNS hostname"), 
        TEXT("DNS domain"), 
        TEXT("DNS fully-qualified"), 
        TEXT("Physical NetBIOS"), 
        TEXT("Physical DNS hostname"), 
        TEXT("Physical DNS domain"), 
        TEXT("Physical DNS fully-qualified")};
    int cnf = 0;
    DWORD dwSize = _countof(buffer);
    
    for (cnf = 0; cnf < ComputerNameMax; cnf++)
    {
        if (!GetComputerNameEx((COMPUTER_NAME_FORMAT)cnf, buffer, &dwSize))
        {
            _tprintf(TEXT("GetComputerNameEx failed (%d)\n"), GetLastError());
            return;
        }
        else _tprintf(TEXT("%s: %s\n"), szDescription[cnf], buffer);

        dwSize = _countof(buffer);
        ZeroMemory(buffer, dwSize);
    }
}

注意

sysinfoapi.h 标头将 GetComputerNameEx 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	sysinfoapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll