Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

SetComputerNameEx function

Sets a new NetBIOS or DNS name for the local computer. Name changes made by SetComputerNameEx do not take effect until the user restarts the computer.

Syntax


BOOL WINAPI SetComputerNameEx(
  _In_  COMPUTER_NAME_FORMAT NameType,
  _In_  LPCTSTR lpBuffer
);

Parameters

NameType [in]

The type of name to be set. This parameter can be one of the following values from the COMPUTER_NAME_FORMAT enumeration type.

ValueMeaning
ComputerNamePhysicalDnsDomain

Sets the primary DNS suffix of the computer.

ComputerNamePhysicalDnsHostname

Sets the NetBIOS and the Computer Name (the first label of the full DNS name) to the name specified in lpBuffer. If the name exceeds MAX_COMPUTERNAME_LENGTH characters, the NetBIOS name is truncated to MAX_COMPUTERNAME_LENGTH characters, not including the terminating null character.

ComputerNamePhysicalNetBIOS

Sets the NetBIOS name to the name specified in lpBuffer. The name cannot exceed MAX_COMPUTERNAME_LENGTH characters, not including the terminating null character.

Warning: Using this option to set the NetBIOS name breaks the convention of interdependent NetBIOS and DNS names. Applications that use the DnsHostnameToComputerName function to derive the NetBIOS name from the first label of the DNS name will fail if this convention is broken.

 

lpBuffer [in]

The new name. The name cannot include control characters, leading or trailing spaces, or any of the following characters: " / \ [ ] : | < > + = ; , ?

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

SetComputerNameEx can set the Computer Name (the first label of the full DNS name) or the primary DNS suffix of the local computer. It cannot set a fully qualified DNS name in one call.

If the local computer is a node in a cluster, SetComputerNameEx sets NetBIOS or DNS name of the local computer, not that of the cluster virtual server.

The process that calls the SetComputerNameEx function must have administrator privileges on the local computer.

To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

SetComputerNameExW (Unicode) and SetComputerNameExA (ANSI)

See also

Computer Names
COMPUTER_NAME_FORMAT
DnsHostnameToComputerName
GetComputerName
GetComputerNameEx
SetComputerName
System Information Functions

 

 

Community Additions

Show:
© 2014 Microsoft