Função GetComputerNameExA (sysinfoapi.h)

Artigo
08/26/2023

Recupera um nome NetBIOS ou DNS associado ao computador local. Os nomes são estabelecidos na inicialização do sistema, quando o sistema os lê do registro.

Sintaxe

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

Parâmetros

[in] NameType

O tipo de nome a ser recuperado. Esse parâmetro é um valor do tipo de enumeração COMPUTER_NAME_FORMAT. A tabela a seguir fornece informações adicionais.

Valor	Significado
ComputerNameDnsDomain	O nome do domínio DNS atribuído ao computador local. Se o computador local for um nó em um cluster, lpBuffer receberá o nome de domínio DNS do servidor virtual do cluster.
ComputerNameDnsFullyQualified	O nome DNS totalmente qualificado que identifica exclusivamente o computador local. Esse nome é uma combinação do nome de host do DNS e o nome de domínio do DNS, usando o formato HostName.DomainName. Se o computador local for um nó em um cluster, lpBuffer receberá o nome DNS totalmente qualificado do servidor virtual do cluster.
ComputerNameDnsHostname	O nome do host de DNS do computador local. Se o computador local for um nó em um cluster, lpBuffer receberá o nome do host DNS do servidor virtual do cluster.
ComputerNameNetBIOS	O nome NetBIOS do computador local. Se o computador local for um nó em um cluster, lpBuffer receberá o nome NetBIOS do servidor virtual do cluster.
ComputerNamePhysicalDnsDomain	O nome do domínio DNS atribuído ao computador local. Se o computador local for um nó em um cluster, lpBuffer receberá o nome de domínio DNS do computador local, não o nome do servidor virtual do cluster.
ComputerNamePhysicalDnsFullyQualified	O nome DNS totalmente qualificado que identifica exclusivamente o computador. Se o computador local for um nó em um cluster, lpBuffer receberá o nome DNS totalmente qualificado do computador local, não o nome do servidor virtual do cluster. O nome totalmente qualificado do DNS é uma combinação do nome de host do DNS e o nome de domínio do DNS, usando a forma HostName.DomainName.
ComputerNamePhysicalDnsHostname	O nome do host de DNS do computador local. Se o computador local for um nó em um cluster, lpBuffer receberá o nome do host DNS do computador local, não o nome do servidor virtual do cluster.
ComputerNamePhysicalNetBIOS	O nome NetBIOS do computador local. Se o computador local for um nó em um cluster, lpBuffer receberá o nome NetBIOS do computador local, não o nome do servidor virtual do cluster.

[out] lpBuffer

Um ponteiro para um buffer que recebe o nome do computador ou o nome do servidor virtual do cluster.

O comprimento do nome pode ser maior que MAX_COMPUTERNAME_LENGTH caracteres porque o DNS permite nomes mais longos. Para garantir que esse buffer seja grande o suficiente, defina esse parâmetro como NULL e use o tamanho do buffer necessário retornado no parâmetro lpnSize .

[in, out] nSize

Na entrada, especifica o tamanho do buffer, em TCHARs. Na saída, recebe o número de TCHARs copiados para o buffer de destino, não incluindo o caractere nulo de terminação.

Se o buffer for muito pequeno, a função falhará e GetLastError retornará ERROR_MORE_DATA. Esse parâmetro recebe o tamanho do buffer necessário, incluindo o caractere nulo de terminação.

Se lpBuffer for NULL, esse parâmetro deverá ser zero.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Os possíveis valores incluem os seguintes.

Código de retorno	Descrição
ERROR_MORE_DATA	O buffer lpBuffer é muito pequeno. O parâmetro lpnSize contém o número de bytes necessários para receber o nome.

Comentários

Se a política de grupo não estiver definida para o computador local, a função GetComputerNameEx recuperará os nomes NetBIOS ou DNS estabelecidos na inicialização do sistema. Se a política de grupo estiver definida, a função retornará o nome de domínio primário definido pela política de grupo. As alterações de nome feitas pelas funções SetComputerName ou SetComputerNameEx não entrarão em vigor até que o usuário reinicie o computador.

Se o computador local não estiver configurado para usar nomes DNS, GetComputerNameEx não retornará informações DNS. Para configurar o computador para fazer isso, siga as etapas descritas na ajuda do sistema operacional e altere o sufixo DNS primário do computador e reinicie o computador.

O comportamento dessa função pode ser afetado se o computador local for um nó em um cluster. Para obter mais informações, consulte ResUtilGetEnvironmentWithNetName e UseNetworkName.

Se você estiver trabalhando com ambientes que usam layouts DNS diferentes, em que o FQDN do computador não corresponde ao FQDN de seu domínio, use LsaQueryInformationPolicy .

Para compilar um aplicativo que usa essa função, defina a macro _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Exemplos

#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);
    }
}

Observação

O cabeçalho sysinfoapi.h define GetComputerNameEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	sysinfoapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll