Syntax

uint32 Rename(
    string Name,
    string Password,
    string UserName
);

Parameters

Name

New computer name. The value of this parameter cannot include control characters, leading or trailing spaces, or any of the following characters: / \\ [ ].

Password

Password to use when connecting to the domain controller if the UserName parameter specifies an account name. Otherwise, this parameter must be NULL. See the Remarks section of this topic for more information about Password and UserName parameters.

UserName

String that specifies the account name to use when connecting to the domain controller. The string must be null-terminated, and must specify a domain NetBIOS name and user account—for example, "DOMAINNAME\username" or "someone@domainname.com", which is a user principal name (UPN). If the UserName parameter is NULL, WMI uses the context of the caller. See the Remarks section of this topic for more information about Password and UserName parameters.

Return Value

Returns a 0 (zero) if successful. A nonzero return value indicates an error. If successful, a reboot is required.

Remarks

If the Password and UserName parameters are specified, the connection to WMI must use the RPC_C_AUTHN_LEVEL_PKT_PRIVACY (wbemAuthenticationLevelPktPrivacy for script and Visual Basic (VB)) authentication level.

To connect to a remote computer and specify credentials, use the locator object connection, which is IWbemLocator for C++, and SWbemLocator for script and VB. Do not use the moniker connection.

To connect to a local computer, you cannot specify a password or an authentication authority, such as Kerberos. You can only specify the password and authority in connections to remote computers.

If the authentication level is too low when a Password and UserName are specified, then WMI returns the WBEM_E_ENCRYPTED_CONNECTION_REQUIRED error for C/C++, and wbemErrEncryptedConnectionRequired for script and VB.

For more information, see SWbemLocator_ConnectServer, IWbemLocator::ConnectServer, and Constructing a Moniker String.

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

The following script shows you how to rename a local computer.

Name = "name"
Password = "password"
Username = "username"

Set objWMIService = GetObject("Winmgmts:root\cimv2")

' Call always gets only one Win32_ComputerSystem object.
For Each objComputer in _
    objWMIService.InstancesOf("Win32_ComputerSystem")

        Return = objComputer.rename(Name,Password,Username)
        If Return <> 0 Then
           WScript.Echo "Rename failed. Error = " & Err.Number
        Else
           WScript.Echo "Rename succeeded." & _
               " Reboot for new name to go into effect"
        End If

Next

Requirements

See Also

Win32_ComputerSystem

Send comments about this topic to Microsoft

Build date: 6/15/2009