SetComputerNameExA function (sysinfoapi.h)
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 SetComputerNameExA(
[in] COMPUTER_NAME_FORMAT NameType,
[in] LPCSTR lpBuffer
);
Parameters
[in] NameType
The type of name to be set. This parameter can be one of the following values from the COMPUTER_NAME_FORMAT enumeration type.
| Value | Meaning |
|---|---|
|
Sets the primary DNS suffix of the computer. |
|
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. |
|
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. |
[in] lpBuffer
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.
Note
The sysinfoapi.h header defines SetComputerNameEx as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | sysinfoapi.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |