OpenSCManagerA-Funktion (winsvc.h)

Artikel
11/20/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

Der 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 bereit.

[in, optional] lpDatabaseName

Der Name der Dienststeuerungs-Manager-Datenbank. Dieser Parameter sollte auf SERVICES_ACTIVE_DATABASE festgelegt werden. Wenn es 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 Service Security and Access Rights.

Bevor die angeforderten Zugriffsrechte gewährt werden, ü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 die Funktion fehlschlägt, ist der Rückgabewert NULL. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

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.

Bemerkungen

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 aus, bevor der angeforderte Zugriff gewährt wird. Weitere Informationen finden Sie unter Service Security and Access Rights.

Wenn der aktuelle Benutzer keinen ordnungsgemäßen Zugriff hat, wenn eine Verbindung mit einem Dienst auf einem anderen Computer hergestellt wird, schlägt der OpenSCManager Funktionsaufruf fehl. Um remote eine Verbindung mit einem Dienst herzustellen, rufen Sie die LogonUser--Funktion mit LOGON32_LOGON_NEW_CREDENTIALS auf, und rufen Sie dann ImpersonateLoggedOnUser- auf, bevor Sie OpenSCManageraufrufen. Weitere Informationen zum Remote-Herstellen einer Verbindung mit Diensten finden Sie unter Services and 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 Konfigurations-eines Diensts.

Anmerkung

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
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winsvc.h (enthalten Windows.h)
Library	Advapi32.lib
DLL-	Advapi32.dll