ChangeServiceConfig2A-Funktion (winsvc.h)

Artikel
03/04/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 zugriffsrecht SERVICE_CHANGE_CONFIG verfügen. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.

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

[in] dwInfoLevel

Die zu ändernden Konfigurationsinformationen. Dieser Parameter kann einen der folgenden Werte annehmen.

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 lpInfo-Parameter 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 berechtigung SE_SHUTDOWN_NAME verfügen. Weitere Informationen finden Sie unter Ausführen mit speziellen Berechtigungen.
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 parameter lpInfo ist ein Zeiger auf eine SERVICE_SID_INFO-Struktur .
SERVICE_CONFIG_TRIGGER_INFO 8	Der parameter lpInfo ist ein Zeiger auf eine SERVICE_TRIGGER_INFO-Struktur . Dieser Wert wird von der ANSI-Version von ChangeServiceConfig2 nicht unterstützt. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird erst unter Windows Server 2008 R2 unterstützt.
SERVICE_CONFIG_LAUNCH_PROTECTED 12	Der lpInfo-Parameter 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 fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

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 Funktion QueryServiceConfig2 abrufen.

Sie können den SERVICE_CONFIG_FAILURE_ACTIONS Wert für einen Dienst nicht festlegen, der den Prozess des Dienststeuerungs-Managers gemeinsam verwendet. Dies schließt alle Dienste ein, deren ausführbares Image "Services.exe" lautet.

Sie können zusätzliche Konfigurationsinformationen mit den Funktionen ChangeServiceConfig bzw . QueryServiceConfig ändern und abfragen.

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, um nach der angegebenen Zeitverzögerung zu erfolgen. Eine Neustartaktion in der Warteschlange kann nicht abgebrochen werden. Wenn der Dienst manuell neu gestartet und dann beendet wird, bevor die Neustartaktion in der Warteschlange auftritt, wird der Dienst unerwartet neu gestartet, wenn die Zeitverzögerung abläuft. Der Dienst muss explizit deaktiviert werden, 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 starten zu können, 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 Konfiguration eines Diensts.

Hinweis

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
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