Função SetComputerNameExA (sysinfoapi.h)

Artigo
08/26/2023

Define um novo nome NetBIOS ou DNS para o computador local. As alterações de nome feitas por SetComputerNameEx não entrarão em vigor até que o usuário reinicie o computador.

Sintaxe

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

Parâmetros

[in] NameType

O tipo de nome a ser definido. Esse parâmetro pode ser um dos seguintes valores do tipo de enumeração COMPUTER_NAME_FORMAT .

Valor	Significado
ComputerNamePhysicalDnsDomain	Define o sufixo DNS primário do computador.
ComputerNamePhysicalDnsHostname	Define o NetBIOS e o Nome do Computador (o primeiro rótulo do nome DNS completo) como o nome especificado em lpBuffer. Se o nome exceder MAX_COMPUTERNAME_LENGTH caracteres, o nome NetBIOS será truncado para MAX_COMPUTERNAME_LENGTH caracteres, não incluindo o caractere nulo de terminação.
ComputerNamePhysicalNetBIOS	Define o nome NetBIOS como o nome especificado em lpBuffer. O nome não pode exceder MAX_COMPUTERNAME_LENGTH caracteres, sem incluir o caractere nulo de terminação. Aviso: usar essa opção para definir o nome NetBIOS interrompe a convenção de nomes NetBIOS e DNS interdependentes. Os aplicativos que usam a função DnsHostnameToComputerName para derivar o nome NetBIOS do primeiro rótulo do nome DNS falharão se essa convenção for interrompida.

[in] lpBuffer

O novo nome. O nome não pode incluir caracteres de controle, espaços à esquerda ou à direita ou qualquer um dos seguintes caracteres: " / \ [ ] : | <> + = ; , ?

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.

Comentários

SetComputerNameEx pode definir o Nome do Computador (o primeiro rótulo do nome DNS completo) ou o sufixo DNS primário do computador local. Ele não pode definir um nome DNS totalmente qualificado em uma chamada.

Se o computador local for um nó em um cluster, SetComputerNameEx definirá NetBIOS ou nome DNS do computador local, não o do servidor virtual do cluster.

O processo que chama a função SetComputerNameEx deve ter privilégios de administrador no computador local.

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

Observação

O cabeçalho sysinfoapi.h define SetComputerNameEx 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