OpenSCManagerA-Funktion (winsvc.h)

Artikel
03/13/2024

Stellt eine Verbindung mit dem Dienststeuerungs-Manager auf dem angegebenen Computer her und öffnet die angegebene Dienststeuerungs-Manager-Datenbank.

Syntax

SC_HANDLE OpenSCManagerA(
  [in, optional] LPCSTR lpMachineName,
  [in, optional] LPCSTR lpDatabaseName,
  [in]           DWORD  dwDesiredAccess
);

Parameter

[in, optional] lpMachineName

Name des Zielcomputers. Wenn der Zeiger NULL ist oder auf eine leere Zeichenfolge zeigt, stellt die Funktion eine Verbindung mit dem Dienststeuerungs-Manager auf dem lokalen Computer her.

[in, optional] lpDatabaseName

Der Name der Dienststeuerungs-Manager-Datenbank. Dieser Parameter sollte auf SERVICES_ACTIVE_DATABASE festgelegt werden. Wenn der Wert NULL ist, wird die SERVICES_ACTIVE_DATABASE-Datenbank standardmäßig geöffnet.

[in] dwDesiredAccess

Der Zugriff auf den Dienststeuerungs-Manager. Eine Liste der Zugriffsrechte finden Sie unter Dienstsicherheit und Zugriffsrechte.

Vor dem Erteilen der angeforderten Zugriffsrechte überprüft das System das Zugriffstoken des aufrufenden Prozesses anhand der diskretionären Zugriffssteuerungsliste des Sicherheitsdeskriptors, der dem Dienststeuerungs-Manager zugeordnet ist.

Das SC_MANAGER_CONNECT-Zugriffsrecht wird implizit durch Aufrufen dieser Funktion angegeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für die angegebene Dienststeuerungs-Manager-Datenbank.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Die folgenden Fehlercodes können vom SCM festgelegt werden. Andere Fehlercodes können von den Registrierungsfunktionen festgelegt werden, die vom SCM aufgerufen werden.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der angeforderte Zugriff wurde verweigert.
ERROR_DATABASE_DOES_NOT_EXIST	Die angegebene Datenbank ist nicht vorhanden.

Hinweise

Wenn ein Prozess die OpenSCManager-Funktion verwendet, um ein Handle für eine Dienststeuerungs-Manager-Datenbank zu öffnen, führt das System eine Sicherheitsüberprüfung durch, bevor der angeforderte Zugriff gewährt wird. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.

Wenn der aktuelle Benutzer beim Herstellen einer Verbindung mit einem Dienst auf einem anderen Computer keinen richtigen Zugriff hat, schlägt der OpenSCManager-Funktionsaufruf fehl. Um eine Remoteverbindung mit einem Dienst herzustellen, rufen Sie die LogonUser-Funktion mit LOGON32_LOGON_NEW_CREDENTIALS und dann ImpersonateLoggedOnUser auf, bevor Sie OpenSCManager aufrufen. Weitere Informationen zum Herstellen einer Remoteverbindung mit Diensten finden Sie unter Dienste und RPC/TCP.

Nur Prozesse mit Administratorrechten können ein Datenbankhandle öffnen, das von der CreateService-Funktion verwendet werden kann.

Das zurückgegebene Handle ist nur für den Prozess gültig, der die OpenSCManager-Funktion aufgerufen hat. Sie kann durch Aufrufen der CloseServiceHandle-Funktion geschlossen werden.

Beispiele

Ein Beispiel finden Sie unter Ändern der Konfiguration eines Diensts.

Hinweis

Der winsvc.h-Header definiert OpenSCManager als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winsvc.h (windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll