Rename-Methode der Win32_ComputerSystem-Klasse

Die Rename-Methode benennt einen Computer um.

In diesem Thema wird MOF-Syntax (Managed Object Format) verwendet. Weitere Informationen zur Verwendung dieser Methode finden Sie unter Aufrufen einer Methode.

Syntax

uint32 Rename(
  [in] string Name,
  [in] string Password,
  [in] string UserName
);

Parameter

Name [in]

Neuer Computername. Der Wert dieses Parameters darf keine Steuerzeichen, führende oder nachfolgende Leerzeichen oder eines der folgenden Zeichen enthalten: / \\ [ ].

Kennwort [in]

Kennwort, das beim Herstellen einer Verbindung mit dem Domänencontroller verwendet werden soll, wenn der UserName-Parameter einen Kontonamen angibt. Andernfalls muss dieser Parameter NULL sein. Weitere Informationen zu den Parametern Password und UserName finden Sie im Abschnitt Hinweise dieses Themas.

UserName [in]

Zeichenfolge, die den Kontonamen angibt, der beim Herstellen einer Verbindung mit dem Domänencontroller verwendet werden soll. Die Zeichenfolge muss NULL-endend sein und einen NetBIOS-Domänennamen und ein Benutzerkonto angeben, z. B. "DOMÄNENNAME\Benutzername" oder "someone@domainname.com", bei dem es sich um einen Benutzerprinzipalnamen (UPN) handelt. Wenn der UserName-ParameterNULL ist, verwendet WMI den Kontext des Aufrufers. Weitere Informationen zu den Parametern Password und UserName finden Sie im Abschnitt Hinweise dieses Themas.

Rückgabewert

Gibt bei erfolgreicher Ausführung eine 0 (null) zurück. Ein Rückgabewert ungleich null gibt einen Fehler an. Bei erfolgreicher Ausführung ist ein Neustart erforderlich. Weitere Fehlercodes finden Sie unter WMI-Fehlerkonstanten oder WbemErrorEnum. Allgemeine HRESULT-Werte finden Sie unter Systemfehlercodes.

Erfolg (0)

Sonstige (1 4294967295)

Bemerkungen

Sie können die Rename-Methode verwenden, um einen Computer umzubenennen, wenn Sie Mitglied der lokalen Administratorgruppe sind. Sie können die -Methode jedoch nicht remote für Domänencomputer verwenden.

Wenn die Parameter Password und UserName angegeben sind, muss die Verbindung mit WMI die Authentifizierungsebene RPC_C_AUTHN_LEVEL_PKT_PRIVACY (wbemAuthenticationLevelPktPrivacy für Skript und Visual Basic (VB)) verwenden.

Um eine Verbindung mit einem Remotecomputer herzustellen und Anmeldeinformationen anzugeben, verwenden Sie die Locatorobjektverbindung( IWbemLocator für C++ und SWbemLocator für Skript und VB). Verwenden Sie nicht die Monikerverbindung.

Um eine Verbindung mit einem lokalen Computer herzustellen, können Sie kein Kennwort oder eine Authentifizierungsstelle wie Kerberos angeben. Sie können das Kennwort und die Autorität nur bei Verbindungen mit Remotecomputern angeben.

Wenn die Authentifizierungsebene zu niedrig ist, wenn ein Kennwort und ein Benutzername angegeben werden, gibt WMI den WBEM_E_ENCRYPTED_CONNECTION_REQUIRED Fehler für C/C++ und wbemErrEncryptedConnectionRequired für Skript und VB zurück.

Weitere Informationen finden Sie unter SWbemLocator_ConnectServer,IWbemLocator::ConnectServer und Erstellen einer Monikerzeichenfolge.

Beispiele

Das folgende Skript zeigt, wie Sie einen lokalen Computer umbenennen.

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

Im folgenden C++-Codebeispiel wird ein Computersystem umbenannt.

int set_computer_name(const string &newname/*, const string &username, const string &password*/)
{
 HRESULT hres;


// Step 1: --------------------------------------------------
 // Initialize COM. ------------------------------------------


hres = CoInitializeEx(0, COINIT_MULTITHREADED); 
 if (FAILED(hres))
 {
 cout << "Failed to initialize COM library. Error code = 0x" 
 << hex << hres << endl;
 return 1; // Program has failed.
 }


// Step 2: --------------------------------------------------
 // Set general COM security levels --------------------------
 // Note: If you are using Windows 2000, you need to specify -
 // the default authentication credentials for a user by using
 // a SOLE_AUTHENTICATION_LIST structure in the pAuthList ----
 // parameter of CoInitializeSecurity ------------------------


hres = CoInitializeSecurity(
 NULL, 
 -1, // COM authentication
 NULL, // Authentication services
 NULL, // Reserved
 RPC_C_AUTHN_LEVEL_DEFAULT, // Default authentication 
 RPC_C_IMP_LEVEL_IMPERSONATE, // Default Impersonation 
 NULL, // Authentication info
 EOAC_NONE, // Additional capabilities 
 NULL // Reserved
 );




 if (FAILED(hres))
 {
 cout << "Failed to initialize security. Error code = 0x" 
 << hex << hres << endl;
 CoUninitialize();
 return 1; // Program has failed.
 }

 // Step 3: ---------------------------------------------------
 // Obtain the initial locator to WMI -------------------------


IWbemLocator *pLoc = NULL;


hres = CoCreateInstance(
 CLSID_WbemLocator, 
 0, 
 CLSCTX_INPROC_SERVER, 
 IID_IWbemLocator, (LPVOID *) &pLoc);

 if (FAILED(hres))
 {
 cout << "Failed to create IWbemLocator object."
 << " Err code = 0x"
 << hex << hres << endl;
 CoUninitialize();
 return 1; // Program has failed.
 }


// Step 4: -----------------------------------------------------
 // Connect to WMI through the IWbemLocator::ConnectServer method


IWbemServices *pSvc = NULL;

 // Connect to the root\cimv2 namespace with
 // the current user and obtain pointer pSvc
 // to make IWbemServices calls.
 hres = pLoc->ConnectServer(
 _bstr_t(L"ROOT\\CIMV2"), // Object path of WMI namespace
 NULL, // User name. NULL = current user
 NULL, // User password. NULL = current
 0, // Locale. NULL indicates current
 NULL, // Security flags.
 0, // Authority (e.g. Kerberos)
 0, // Context object 
 &pSvc // pointer to IWbemServices proxy
 );

 if (FAILED(hres))
 {
 cout << "Could not connect. Error code = 0x" 
 << hex << hres << endl;
 pLoc->Release(); 
 CoUninitialize();
 return 1; // Program has failed.
 }


/*cout << "Connected to ROOT\\CIMV2 WMI namespace" << endl;*/




 // Step 5: --------------------------------------------------
 // Set security levels on the proxy -------------------------


hres = CoSetProxyBlanket(
 pSvc, // Indicates the proxy to set
 RPC_C_AUTHN_WINNT, // RPC_C_AUTHN_xxx
 RPC_C_AUTHZ_NONE, // RPC_C_AUTHZ_xxx
 NULL, // Server principal name 
 RPC_C_AUTHN_LEVEL_CALL, // RPC_C_AUTHN_LEVEL_xxx 
 RPC_C_IMP_LEVEL_IMPERSONATE, // RPC_C_IMP_LEVEL_xxx
 NULL, // client identity
 EOAC_NONE // proxy capabilities 
 );


if (FAILED(hres))
 {
 cout << "Could not set proxy blanket. Error code = 0x" 
 << hex << hres << endl;
 pSvc->Release();
 pLoc->Release(); 
 CoUninitialize();
 return 1; // Program has failed.
 }


// Step 6: --------------------------------------------------
 // Use the IWbemServices pointer to make requests of WMI ----


// For example, get the name of the operating system
 IEnumWbemClassObject* pEnumerator = NULL;
 hres = pSvc->ExecQuery(
 bstr_t("WQL"), 
 bstr_t("SELECT * FROM Win32_ComputerSystem"),
 WBEM_FLAG_FORWARD_ONLY | WBEM_FLAG_RETURN_IMMEDIATELY, 
 NULL,
 &pEnumerator);

 if (FAILED(hres))
 {
 cout << "Query for operating system name failed."
 << " Error code = 0x" 
 << hex << hres << endl;
 pSvc->Release();
 pLoc->Release();
 CoUninitialize();
 return 1; // Program has failed.
 }


// Step 7: -------------------------------------------------
 // Get the data from the query in step 6 -------------------

 IWbemClassObject *pclsObj;
 ULONG uReturn = 0;

 while (pEnumerator)
 {
 HRESULT hr = pEnumerator->Next(WBEM_INFINITE, 1, 
 &pclsObj, &uReturn);


if(0 == uReturn)
 {
 break;
 }


// set up to call the Win32_ComputerSystem::Rename method
 BSTR MethodName = SysAllocString(L"Rename");
 BSTR ClassName = SysAllocString(L"Win32_ComputerSystem");


IWbemClassObject* pClass = NULL;
 hres = pSvc->GetObject(ClassName, 0, NULL, &pClass, NULL);


IWbemClassObject* pInParamsDefinition = NULL;
 hres = pClass->GetMethod(MethodName, 0, 
 &pInParamsDefinition, NULL);


IWbemClassObject* pClassInstance = NULL;
 hres = pInParamsDefinition->SpawnInstance(0, &pClassInstance);


// Create the values for the in parameters
 wstring val;
 BSTR NewName;
 val.assign(newname.begin(), newname.end());
 NewName = SysAllocString(val.c_str());


VARIANT varName;
 varName.vt = VT_BSTR;
 varName.bstrVal = NewName;


// Store the value for the in parameters
 hres = pClassInstance->Put(L"Name", 0,
 &varName, 0);
 wprintf(L"Set computer name to %s\n", V_BSTR(&varName));


VARIANT var;
 CIMTYPE pType;
 LONG pFlavor;
 pclsObj->Get(L"__PATH",0,&var,&pType,&pFlavor);


// Execute Method
 IWbemClassObject* pOutParams = NULL;
 hres = pSvc->ExecMethod(var.bstrVal, MethodName, 0,
 NULL, pClassInstance, &pOutParams, NULL);


if (FAILED(hres))
 {
 cout << "Could not execute method. Error code = 0x" 
 << hex << hres << endl;
 VariantClear(&varName);
 SysFreeString(ClassName);
 SysFreeString(MethodName);
 SysFreeString(NewName);
 pClass->Release();
 pInParamsDefinition->Release();
 pOutParams->Release();
 return 1; // Program has failed.
 }


// To see what the method returned,
 // use the following code. The return value will
 // be in &varReturnValue
 VARIANT varReturnValue;
 hres = pOutParams->Get(_bstr_t(L"ReturnValue"), 0, 
 &varReturnValue, NULL, 0);




 // Clean up
 //--------------------------
 VariantClear(&varName);
 VariantClear(&varReturnValue);
 SysFreeString(ClassName);
 SysFreeString(MethodName);
 SysFreeString(NewName);
 pClass->Release();
 pInParamsDefinition->Release();
 pOutParams->Release();
 return 0;


}


// Cleanup
 // ========

 pSvc->Release();
 pLoc->Release();
 pEnumerator->Release();
 pclsObj->Release();
 CoUninitialize();


return 0; // Program successfully completed.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	WindowsServer 2008
Namespace	Root\CIMV2
MOF	CIMWin32.mof
DLL	CIMWin32.dll

Siehe auch

Win32_ComputerSystem

WMI-Aufgaben: Konten und Domänen