Función GetComputerNameExA (sysinfoapi.h)

Artículo
08/26/2023

Recupera un nombre NetBIOS o DNS asociado al equipo local. Los nombres se establecen al iniciar el sistema, cuando el sistema los lee del registro.

Sintaxis

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

Parámetros

[in] NameType

Tipo de nombre que se va a recuperar. Este parámetro es un valor del tipo de enumeración COMPUTER_NAME_FORMAT . En la tabla siguiente se proporciona información adicional.

Valor	Significado
ComputerNameDnsDomain	El nombre del dominio DNS asignado al equipo local. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre de dominio DNS del servidor virtual del clúster.
ComputerNameDnsFullyQualified	El nombre DNS completo que identifica exclusivamente el equipo local. Este nombre es una combinación del nombre del host DNS y el nombre del dominio DNS, con el formato nombreDeHost.nombreDeDominio. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre DNS completo del servidor virtual del clúster.
ComputerNameDnsHostname	El nombre del host DNS del equipo local. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre de host DNS del servidor virtual del clúster.
ComputerNameNetBIOS	El nombre NetBIOS del equipo local. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre NetBIOS del servidor virtual del clúster.
ComputerNamePhysicalDnsDomain	El nombre del dominio DNS asignado al equipo local. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre de dominio DNS del equipo local, no el nombre del servidor virtual del clúster.
ComputerNamePhysicalDnsFullyQualified	El nombre DNS completo que identifica exclusivamente el equipo. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre DNS completo del equipo local, no el nombre del servidor virtual del clúster. El nombre DNS completo es una combinación del nombre del host DNS y del nombre del dominio DNS, con el formato nombreDeHost.nombreDeDominio.
ComputerNamePhysicalDnsHostname	El nombre del host DNS del equipo local. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre de host DNS del equipo local, no el nombre del servidor virtual del clúster.
ComputerNamePhysicalNetBIOS	El nombre NetBIOS del equipo local. Si el equipo local es un nodo de un clúster, lpBuffer recibe el nombre NetBIOS del equipo local, no el nombre del servidor virtual del clúster.

[out] lpBuffer

Puntero a un búfer que recibe el nombre del equipo o el nombre del servidor virtual del clúster.

La longitud del nombre puede ser mayor que MAX_COMPUTERNAME_LENGTH caracteres porque DNS permite nombres más largos. Para asegurarse de que este búfer es lo suficientemente grande, establezca este parámetro en NULL y use el tamaño de búfer necesario devuelto en el parámetro lpnSize .

[in, out] nSize

En la entrada, especifica el tamaño del búfer, en TCHAR. En la salida, recibe el número de TCHAR copiados en el búfer de destino, sin incluir el carácter nulo de terminación.

Si el búfer es demasiado pequeño, se produce un error en la función y GetLastError devuelve ERROR_MORE_DATA. Este parámetro recibe el tamaño del búfer necesario, incluido el carácter nulo de terminación.

Si lpBuffer es NULL, este parámetro debe ser cero.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un valor distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError. Estos son algunos de los valores posibles.

Código devuelto	Descripción
ERROR_MORE_DATA	El búfer lpBuffer es demasiado pequeño. El parámetro lpnSize contiene el número de bytes necesarios para recibir el nombre.

Comentarios

Si no se establece la directiva de grupo para el equipo local, la función GetComputerNameEx recupera los nombres NetBIOS o DNS establecidos en el inicio del sistema. Si se establece la directiva de grupo, la función devuelve el nombre de dominio principal establecido por la directiva de grupo. Los cambios de nombre realizados por las funciones SetComputerName o SetComputerNameEx no surten efecto hasta que el usuario reinicie el equipo.

Si el equipo local no está configurado para usar nombres DNS, GetComputerNameEx no devolverá información de DNS. Para configurar el equipo para ello, siga los pasos descritos en la ayuda del sistema operativo y cambie el sufijo DNS principal del equipo y, a continuación, reinicie el equipo.

El comportamiento de esta función puede verse afectado si el equipo local es un nodo de un clúster. Para obtener más información, vea ResUtilGetEnvironmentWithNetName y UseNetworkName.

Si está trabajando con entornos que usan diseños DNS diferentes, donde el FQDN del equipo no coincide con el FQDN de su dominio, use LsaQueryInformationPolicy en su lugar.

Para compilar una aplicación que usa esta función, defina la macro _WIN32_WINNT como 0x0500 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Ejemplos

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

Nota:

El encabezado sysinfoapi.h define GetComputerNameEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	sysinfoapi.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll