ChangeServiceConfig2A-Funktion (winsvc.h)

Artikel
11/20/2024

Ändert die optionalen Konfigurationsparameter eines Diensts.

Syntax

BOOL ChangeServiceConfig2A(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPVOID    lpInfo
);

Parameter

[in] hService

Ein Handle für den Dienst. Dieses Handle wird von der OpenService- oder CreateService--Funktion zurückgegeben und muss über das SERVICE_CHANGE_CONFIG Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Service Security and Access Rights.

Wenn der Dienstcontroller die SC_ACTION_RESTART-Aktion verarbeitet, muss hService- über das SERVICE_START Zugriffsrecht verfügen.

[in] dwInfoLevel

Die zu ändernden Konfigurationsinformationen. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
SERVICE_CONFIG_DELAYED_AUTO_START_INFO 3	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_DELAYED_AUTO_START_INFO Struktur. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SERVICE_CONFIG_DESCRIPTION 1	Der parameter lpInfo ist ein Zeiger auf eine SERVICE_DESCRIPTION Struktur.
SERVICE_CONFIG_FAILURE_ACTIONS 2	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_FAILURE_ACTIONS Struktur. Wenn der Dienstcontroller die SC_ACTION_REBOOT-Aktion verarbeitet, muss der Aufrufer über die SE_SHUTDOWN_NAME Berechtigungverfügen. Weitere Informationen finden Sie unter Ausführen mit speziellen Rechten.
SERVICE_CONFIG_FAILURE_ACTIONS_FLAG 4	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_FAILURE_ACTIONS_FLAG Struktur. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SERVICE_CONFIG_PREFERRED_NODE 9	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_PREFERRED_NODE_INFO Struktur. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SERVICE_CONFIG_PRESHUTDOWN_INFO 7	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_PRESHUTDOWN_INFO Struktur. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO 6	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_REQUIRED_PRIVILEGES_INFO Struktur. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SERVICE_CONFIG_SERVICE_SID_INFO 5	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_SID_INFO Struktur.
SERVICE_CONFIG_TRIGGER_INFO 8	Der lpInfo Parameter ist ein Zeiger auf eine SERVICE_TRIGGER_INFO Struktur. Dieser Wert wird von der ANSI-Version von ChangeServiceConfig2nicht unterstützt. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird erst nach Windows Server 2008 R2 unterstützt.
SERVICE_CONFIG_LAUNCH_PROTECTED 12	Der parameter lpInfo ist ein Zeiger einer SERVICE_LAUNCH_PROTECTED_INFO Struktur. Hinweis Dieser Wert wird ab Windows 8.1 unterstützt.

[in, optional] lpInfo

Ein Zeiger auf den neuen Wert, der für die Konfigurationsinformationen festgelegt werden soll. Das Format dieser Daten hängt vom Wert des dwInfoLevel-Parameters ab. Wenn dieser Wert NULL-ist, bleiben die Informationen unverändert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Die ChangeServiceConfig2 Funktion ändert die optionalen Konfigurationsinformationen für den angegebenen Dienst in der Dienststeuerungs-Manager-Datenbank. Sie können die aktuellen optionalen Konfigurationsinformationen mithilfe der QueryServiceConfig2--Funktion abrufen.

Sie können den SERVICE_CONFIG_FAILURE_ACTIONS Wert für einen Dienst nicht festlegen, der den Prozess des Dienststeuerungs-Managers teilt. Dazu gehören alle Dienste, deren ausführbares Image "Services.exe" ist.

Sie können zusätzliche Konfigurationsinformationen ändern und abfragen, indem Sie die funktionen ChangeServiceConfig bzw. QueryServiceConfig.

Wenn ein Dienst so konfiguriert ist, dass er neu gestartet wird, nachdem er mit einem Fehler abgeschlossen wurde, stellt der Dienststeuerungs-Manager die Neustartaktion in die Warteschlange, die nach der angegebenen Zeitverzögerung auftritt. Eine Aktion für einen in die Warteschlange eingereihten Neustart kann nicht abgebrochen werden. Wenn der Dienst manuell neu gestartet und dann vor dem Starten der Warteschlange beendet wird, wird der Dienst unerwartet neu gestartet, wenn die Zeitverzögerung verstrichen ist. Der Dienst muss explizit deaktiviert sein, um zu verhindern, dass er neu gestartet wird.

Der wert SERVICE_CONFIG_LAUNCH_PROTECTED kann verwendet werden, um den Dienst als geschützt zu starten. Um den Dienst als geschützt zu starten, muss der Dienst mit einem speziellen Zertifikat signiert werden.

SERVICE_CONFIG_LAUNCH_PROTECTED Beispiel:

SERVICE_LAUNCH_PROTECTED_INFO Info;
SC_HANDLE hService;

Info.dwLaunchProtected = SERVICE_LAUNCH_PROTECTED_ANTIMALWARE_LIGHT;

hService = CreateService (...);

if (ChangeServiceConfig2(hService, 
                        SERVICE_CONFIG_LAUNCH_PROTECTED,
                        &Info) == FALSE)
{
    Result = GetLastError();
}

Beispiele

Ein Beispiel finden Sie unter Ändern der Konfigurations-eines Diensts.

Anmerkung

Der winsvc.h-Header definiert ChangeServiceConfig2 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