Freigeben über


ChangeServiceConfigA-Funktion (winsvc.h)

Ändert die Konfigurationsparameter eines Diensts.

Verwenden Sie die Funktion ChangeServiceConfig2 , um die optionalen Konfigurationsparameter zu ändern.

Syntax

BOOL ChangeServiceConfigA(
  [in]            SC_HANDLE hService,
  [in]            DWORD     dwServiceType,
  [in]            DWORD     dwStartType,
  [in]            DWORD     dwErrorControl,
  [in, optional]  LPCSTR    lpBinaryPathName,
  [in, optional]  LPCSTR    lpLoadOrderGroup,
  [out, optional] LPDWORD   lpdwTagId,
  [in, optional]  LPCSTR    lpDependencies,
  [in, optional]  LPCSTR    lpServiceStartName,
  [in, optional]  LPCSTR    lpPassword,
  [in, optional]  LPCSTR    lpDisplayName
);

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.

[in] dwServiceType

Der Diensttyp. Geben Sie SERVICE_NO_CHANGE an, wenn Sie den vorhandenen Diensttyp nicht ändern. Geben Sie andernfalls einen der folgenden Diensttypen an.

Wert Bedeutung
SERVICE_FILE_SYSTEM_DRIVER
0x00000002
Dateisystemtreiberdienst.
SERVICE_KERNEL_DRIVER
0x00000001
Treiberdienst.
SERVICE_WIN32_OWN_PROCESS
0x00000010
Dienst, der in einem eigenen Prozess ausgeführt wird.
SERVICE_WIN32_SHARE_PROCESS
0x00000020
Dienst, der einen Prozess gemeinsam mit anderen Diensten verwendet.
 

Wenn Sie entweder SERVICE_WIN32_OWN_PROCESS oder SERVICE_WIN32_SHARE_PROCESS angeben und der Dienst im Kontext des LocalSystem-Kontos ausgeführt wird, können Sie auch den folgenden Typ angeben.

Wert Bedeutung
SERVICE_INTERACTIVE_PROCESS
0x00000100
Der Dienst kann mit dem Desktop interagieren.

Weitere Informationen finden Sie unter Interaktive Dienste.

[in] dwStartType

Die Startoptionen des Diensts. Geben Sie SERVICE_NO_CHANGE an, wenn Sie den vorhandenen Starttyp nicht ändern. Geben Sie andernfalls einen der folgenden Werte an.

Wert Bedeutung
SERVICE_AUTO_START
0x00000002
Ein Dienst, der während des Systemstarts automatisch vom Dienststeuerungs-Manager gestartet wird.
SERVICE_BOOT_START
0x00000000
Ein Gerätetreiber, der vom Systemladeprogramm gestartet wurde. Dieses Wert ist nur für Treiberdienste gültig.
SERVICE_DEMAND_START
0x00000003
Ein Dienst, der vom Dienststeuerungs-Manager gestartet wird, wenn ein Prozess die StartService-Funktion aufruft.
SERVICE_DISABLED
0x00000004
Ein Dienst, der nicht gestartet werden kann. Versuche, den Dienst zu starten, führen dazu, dass der Fehlercode ERROR_SERVICE_DISABLED.
SERVICE_SYSTEM_START
0x00000001
Ein Gerätetreiber, der von der IoInitSystem-Funktion gestartet wurde. Dieses Wert ist nur für Treiberdienste gültig.

[in] dwErrorControl

Der Schweregrad des Fehlers und der ausgeführten Aktion, wenn dieser Dienst nicht gestartet werden kann. Geben Sie SERVICE_NO_CHANGE an, wenn Sie die vorhandene Fehlersteuerung nicht ändern. Geben Sie andernfalls einen der folgenden Werte an.

Wert Bedeutung
SERVICE_ERROR_CRITICAL
0x00000003
Das Startprogramm protokolliert den Fehler nach Möglichkeit im Ereignisprotokoll. Wenn diese Konfiguration gestartet wird, schlägt der Startvorgang fehl. Andernfalls wird das System mit der zuletzt bekannten guten Konfiguration neu gestartet.
SERVICE_ERROR_IGNORE
0x00000000
Das Startprogramm ignoriert den Fehler und setzt den Startvorgang fort.
SERVICE_ERROR_NORMAL
0x00000001
Das Startprogramm protokolliert den Fehler im Ereignisprotokoll, setzt den Startvorgang jedoch fort.
SERVICE_ERROR_SEVERE
0x00000002
Das Startprogramm protokolliert den Fehler im Ereignisprotokoll. Wenn die letzte zweifelsfrei funktionierende Konfiguration gestartet wird, wird der Startvorgang fortgesetzt. Andernfalls wird das System mit der letzten zweifelsfrei funktionierenden Konfiguration neu gestartet.

[in, optional] lpBinaryPathName

Der vollqualifizierte Pfad zur Binärdatei des Diensts. Geben Sie NULL an, wenn Sie den vorhandenen Pfad nicht ändern. Wenn der Pfad ein Leerzeichen enthält, muss er in Anführungszeichen gesetzt werden, damit er ordnungsgemäß interpretiert wird. Beispielsweise sollte "d:\my share\myservice.exe" als "d:\my share\myservice.exe" angegeben werden.

Der Pfad kann auch Argumente für einen Dienst mit automatischem Start enthalten. Beispiel: "d:\myshare\myservice.exe arg1 arg2". Diese Argumente werden an den Diensteinstiegspunkt (in der Regel die Standard-Funktion) übergeben.

Wenn Sie einen Pfad auf einem anderen Computer angeben, muss für das Computerkonto des lokalen Computers auf die Freigabe zugegriffen werden, da dies der Sicherheitskontext ist, der im Remoteaufruf verwendet wird. Diese Anforderung ermöglicht jedoch, dass sich potenzielle Sicherheitsrisiken auf dem Remotecomputer auf den lokalen Computer auswirken. Daher ist es am besten, eine lokale Datei zu verwenden.

[in, optional] lpLoadOrderGroup

Der Name der Ladereihenfolgegruppe, der dieser Dienst angehört. Geben Sie NULL an, wenn Sie die vorhandene Gruppe nicht ändern. Geben Sie eine leere Zeichenfolge an, wenn der Dienst nicht zu einer Gruppe gehört.

Das Startprogramm verwendet Ladereihenfolgegruppen, um Gruppen von Diensten in einer angegebenen Reihenfolge in Bezug auf die anderen Gruppen zu laden. Die Liste der Lastreihenfolgegruppen ist im ServiceGroupOrder-Wert des folgenden Registrierungsschlüssels enthalten:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control

[out, optional] lpdwTagId

Ein Zeiger auf eine Variable, die einen Tagwert empfängt, der in der gruppe eindeutig ist, die im parameter lpLoadOrderGroup angegeben ist. Geben Sie NULL an, wenn Sie das vorhandene Tag nicht ändern.

Sie können ein Tag zum Bestellvorgang des Dienststarts innerhalb einer Ladereihenfolgegruppe verwenden, indem Sie einen Tagreihenfolgevektor im GroupOrderList-Wert des folgenden Registrierungsschlüssels angeben:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control

Tags werden nur für Treiberdienste ausgewertet, die über SERVICE_BOOT_START - oder SERVICE_SYSTEM_START Starttypen verfügen.

[in, optional] lpDependencies

Ein Zeiger auf ein doppeltes NULL-beendetes Array mit null getrennten Namen von Diensten oder Lastenreihenfolgegruppen, die das System starten muss, bevor dieser Dienst gestartet werden kann. (Abhängigkeit von einer Gruppe bedeutet, dass dieser Dienst ausgeführt werden kann, wenn nach dem Versuch, alle Mitglieder der Gruppe zu starten, mindestens ein Mitglied der Gruppe ausgeführt wird.) Geben Sie NULL an, wenn Sie die vorhandenen Abhängigkeiten nicht ändern. Geben Sie eine leere Zeichenfolge an, wenn der Dienst keine Abhängigkeiten aufweist.

Sie müssen Gruppennamen SC_GROUP_IDENTIFIER voranstellen, damit sie von einem Dienstnamen unterschieden werden können, da Dienste und Dienstgruppen denselben Namensraum gemeinsam nutzen.

[in, optional] lpServiceStartName

Der Name des Kontos, unter dem der Dienst ausgeführt werden soll. Geben Sie NULL an, wenn Sie den vorhandenen Kontonamen nicht ändern. Wenn der Diensttyp SERVICE_WIN32_OWN_PROCESS ist, verwenden Sie einen Kontonamen im Format Domänenname\Benutzername. Der Dienstprozess wird als dieser Benutzer angemeldet. Wenn das Konto zur integrierten Domäne gehört, können Sie .\UserName angeben (beachten Sie, dass die entsprechende C/C++-Zeichenfolge ".\\UserName" lautet). Weitere Informationen finden Sie unter Dienstbenutzerkonten und die Warnung im Abschnitt Hinweise.

Ein freigegebener Prozess kann wie ein beliebiger Benutzer ausgeführt werden.

Wenn der Diensttyp SERVICE_KERNEL_DRIVER oder SERVICE_FILE_SYSTEM_DRIVER ist, ist der Name der Treiberobjektname, den das System zum Laden des Gerätetreibers verwendet. Geben Sie NULL an, wenn der Treiber einen Standardobjektnamen verwenden soll, der vom E/A-System erstellt wurde.

Ein Dienst kann für die Verwendung eines verwalteten Kontos oder eines virtuellen Kontos konfiguriert werden. Wenn der Dienst für die Verwendung eines verwalteten Dienstkontos konfiguriert ist, entspricht der Name dem Namen des verwalteten Dienstkontos. Wenn der Dienst für die Verwendung eines virtuellen Kontos konfiguriert ist, geben Sie den Namen als NT SERVICE\ServiceName an. Weitere Informationen zu verwalteten Dienstkonten und virtuellen Konten finden Sie in der Schrittweisen Anleitung zu Dienstkonten.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Verwaltete Dienstkonten und virtuelle Konten werden erst unter Windows 7 und Windows Server 2008 R2 unterstützt.

[in, optional] lpPassword

Das Kennwort für den Kontonamen, der durch den lpServiceStartName-Parameter angegeben wird. Geben Sie NULL an, wenn Sie das vorhandene Kennwort nicht ändern. Geben Sie eine leere Zeichenfolge an, wenn das Konto über kein Kennwort verfügt oder der Dienst im LocalService-, NetworkService- oder LocalSystem-Konto ausgeführt wird. Weitere Informationen finden Sie unter Diensteintragsliste.

Wenn der durch den lpServiceStartName-Parameter angegebene Kontoname der Name eines verwalteten Dienstkontos oder virtuellen Kontonamens ist, muss der lpPassword-ParameterNULL sein.

Kennwörter werden für Treiberdienste ignoriert.

[in, optional] lpDisplayName

Der Anzeigename, der von Anwendungen verwendet werden soll, um den Dienst für seine Benutzer zu identifizieren. Geben Sie NULL an, wenn Sie den vorhandenen Anzeigenamen nicht ändern. Andernfalls hat diese Zeichenfolge eine maximale Länge von 256 Zeichen. Der Name wird im Dienststeuerungs-Manager in Groß-/Kleinschreibung beibehalten. Bei Anzeigenamenvergleichen wird immer zwischen Groß- und Kleinschreibung unterschieden.

Dieser Parameter kann eine lokalisierte Zeichenfolge im folgenden Format angeben:

@[Path]dllname,-strID

Die Zeichenfolge mit dem Bezeichner strID wird aus dllname geladen. der Pfad ist optional. Weitere Informationen finden Sie unter RegLoadMUIString.

Windows Server 2003 und Windows XP: Lokalisierte Zeichenfolgen werden erst unter Windows Vista unterstützt.

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.

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

Rückgabecode Beschreibung
ERROR_ACCESS_DENIED
Das Handle verfügt nicht über das Zugriffsrecht SERVICE_CHANGE_CONFIG .
ERROR_CIRCULAR_DEPENDENCY
Es wurde eine Zirkeldienstabhängigkeit angegeben.
ERROR_DUPLICATE_SERVICE_NAME
Der Anzeigename ist bereits in der Service Controller Manager-Datenbank vorhanden, entweder als Dienstname oder als anderer Anzeigename.
ERROR_INVALID_HANDLE
Das angegebene Handle ist ungültig.
ERROR_INVALID_PARAMETER
Ein parameter, der angegeben wurde, ist ungültig.
ERROR_INVALID_SERVICE_ACCOUNT
Der Kontoname ist nicht vorhanden, oder es wird ein Dienst angegeben, der dieselbe Binärdatei wie ein bereits installierter Dienst verwendet, jedoch mit einem Kontonamen, der nicht mit dem installierten Dienst identisch ist.
ERROR_SERVICE_MARKED_FOR_DELETE
Der Dienst wurde zum Löschen markiert.

Hinweise

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

Wenn die Konfiguration für einen Dienst geändert wird, der ausgeführt wird( mit Ausnahme von lpDisplayName), werden die Änderungen erst wirksam, wenn der Dienst beendet wird. Verwenden Sie die LsaCallAuthenticationPackage-Funktion , um die Anmeldeinformationen zu aktualisieren, ohne den Dienst neu starten zu müssen.

Sicherheitsbemerkungen

Durch Festlegen des lpServiceStartName-Parameters wird das Anmeldekonto des Diensts geändert. Dies kann zu Problemen führen. Wenn Sie einen Dienstprinzipalnamen (Service Principal Name, SPN) registriert haben, wird dieser jetzt im falschen Konto registriert. Wenn Sie einen ACE verwendet haben, um Zugriff auf einen Dienst zu gewähren, würde dieser jetzt Zugriff auf das falsche Konto gewähren.

Beispiele

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

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

Weitere Informationen

ChangeServiceConfig2

CreateService

Openservice

QueryServiceConfig

QueryServiceConfig2

QueryServiceDynamicInformation

Schrittweise Anleitung zu Dienstkonten

Dienstkonfiguration:

Dienstfunktionen

Startservice