Функция 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 и имеет форму ИмяУзла.ИмяДомена. Если локальный компьютер является узлом в кластере, lpBuffer получает полное DNS-имя виртуального сервера кластера.
ComputerNameDnsHostname	Имя узла DNS локального компьютера. Если локальный компьютер является узлом в кластере, lpBuffer получает DNS-имя узла виртуального сервера кластера.
ComputerNameNetBIOS	Имя NetBIOS локального компьютера. Если локальный компьютер является узлом в кластере, lpBuffer получает NetBIOS-имя виртуального сервера кластера.
ComputerNamePhysicalDnsDomain	Имя домена DNS, назначенное локальному компьютеру. Если локальный компьютер является узлом в кластере, lpBuffer получает dns-имя локального компьютера, а не имя виртуального сервера кластера.
ComputerNamePhysicalDnsFullyQualified	Полное имя DNS, служащее уникальным идентификатором компьютера. Если локальный компьютер является узлом в кластере, lpBuffer получает полное DNS-имя локального компьютера, а не имя виртуального сервера кластера. Полное имя DNS является сочетанием имени узла DNS и доменного имени DNS и имеет форму ИмяУзла.ИмяДомена.
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, где полное доменное имя компьютера не соответствует полному доменному имени домена, используйте вместо него 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	sysinfoapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll