Función SetComputerNameExA (sysinfoapi.h)

Artículo
03/05/2024

Establece un nuevo nombre NetBIOS o DNS para el equipo local. Los cambios de nombre realizados por SetComputerNameEx no surten efecto hasta que el usuario reinicie el equipo.

Sintaxis

BOOL SetComputerNameExA(
  [in] COMPUTER_NAME_FORMAT NameType,
  [in] LPCSTR               lpBuffer
);

Parámetros

[in] NameType

Tipo de nombre que se va a establecer. Este parámetro puede ser uno de los siguientes valores del tipo de enumeración COMPUTER_NAME_FORMAT .

Valor	Significado
ComputerNamePhysicalDnsDomain	Establece el sufijo DNS principal del equipo.
ComputerNamePhysicalDnsHostname	Establece NetBIOS y nombre de equipo (la primera etiqueta del nombre DNS completo) en el nombre especificado en lpBuffer. Si el nombre supera MAX_COMPUTERNAME_LENGTH caracteres, el nombre NetBIOS se trunca a MAX_COMPUTERNAME_LENGTH caracteres, no incluido el carácter nulo de terminación.
ComputerNamePhysicalNetBIOS	Establece el nombre NetBIOS en el nombre especificado en lpBuffer. El nombre no puede superar MAX_COMPUTERNAME_LENGTH caracteres, sin incluir el carácter nulo de terminación. Advertencia: Si usa esta opción para establecer el nombre NetBIOS, se interrumpe la convención de nombres NetBIOS y DNS interdependientes. Las aplicaciones que usan la función DnsHostnameToComputerName para derivar el nombre NetBIOS de la primera etiqueta del nombre DNS producirán un error si se interrumpe esta convención.

[in] lpBuffer

Nuevo nombre. El nombre no puede incluir caracteres de control, espacios iniciales o finales, ni ninguno de los siguientes caracteres: " / \ [ ] : | <> + = ; , ?

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.

Comentarios

SetComputerNameEx puede establecer el nombre del equipo (la primera etiqueta del nombre DNS completo) o el sufijo DNS principal del equipo local. No puede establecer un nombre DNS completo en una llamada.

Si el equipo local es un nodo de un clúster, SetComputerNameEx establece NetBIOS o el nombre DNS del equipo local, no el del servidor virtual del clúster.

El proceso que llama a la función SetComputerNameEx debe tener privilegios de administrador en el equipo local.

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

Nota

El encabezado sysinfoapi.h define SetComputerNameEx 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