SetServiceStatus-Funktion (winsvc.h)

Artikel
08/27/2023

Updates die status Informationen des Dienststeuerungs-Managers für den aufrufenden Dienst.

Syntax

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Parameter

[in] hServiceStatus

Ein Handle für die status Informationsstruktur für den aktuellen Dienst. Dieses Handle wird von der Funktion RegisterServiceCtrlHandlerEx zurückgegeben.

[in] lpServiceStatus

Ein Zeiger auf die SERVICE_STATUS-Struktur enthält die neuesten status Informationen für den aufrufenden Dienst.

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_INVALID_DATA	Die angegebene Dienst-status-Struktur ist ungültig.
ERROR_INVALID_HANDLE	Das angegebene Handle ist ungültig.

Hinweise

Eine ServiceMain-Funktion ruft zuerst die Funktion RegisterServiceCtrlHandlerEx auf, um die SERVICE_STATUS_HANDLE des Diensts abzurufen. Anschließend ruft er sofort die SetServiceStatus-Funktion auf, um den Dienststeuerungs-Manager zu benachrichtigen, dass sein status SERVICE_START_PENDING ist. Während der Initialisierung kann der Dienst aktualisierte status bereitstellen, um anzugeben, dass er Fortschritte macht, aber mehr Zeit benötigt. Ein häufiger Fehler besteht darin, dass der Standard Thread die Initialisierung des Diensts ausführt, während ein separater Thread Weiterhin SetServiceStatus aufruft, um zu verhindern, dass der Dienststeuerungs-Manager ihn als hängend markiert. Wenn der Standard Threads jedoch anhält, endet der Dienststart in einer Endlosschleife, da der Workerthread weiterhin meldet, dass der Standard Thread Fortschritte macht.

Nach der Verarbeitung einer Steuerelementanforderung muss die Handlerfunktion des Diensts SetServiceStatus aufrufen, wenn der Dienst Änderungen status, um seine neue status dem Dienststeuerungs-Manager zu melden. Dies ist nur erforderlich, wenn der Dienst den Status ändert, z. B. wenn er Steuerelemente zum Beenden oder Herunterfahren verarbeitet. Ein Dienst kann diese Funktion auch jederzeit aus einem beliebigen Thread des Diensts verwenden, um den Dienststeuerungs-Manager über Zustandsänderungen zu benachrichtigen, z. B. wenn der Dienst aufgrund eines wiederherstellbaren Fehlers beendet werden muss.

Ein Dienst kann diese Funktion erst aufrufen, nachdem er RegisterServiceCtrlHandlerEx aufgerufen hat, um einen Dienst status Handle abzurufen.

Wenn ein Dienst SetServiceStatus aufruft, wobei das dwCurrentState-Member auf SERVICE_STOPPED festgelegt ist und das dwWin32ExitCode-Member auf einen nonzero-Wert festgelegt ist, wird der folgende Eintrag in das Systemereignisprotokoll geschrieben:

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Die folgenden bewährten Methoden sind beim Aufrufen dieser Funktion:

Initialisieren Sie alle Felder in der SERVICE_STATUS-Struktur , und stellen Sie sicher, dass gültige Prüfpunkt- und Wartehinweiswerte für ausstehende Zustände vorhanden sind. Verwenden Sie vernünftige Wartehinweise.
Registrieren Sie sich nicht, um Steuerelemente zu akzeptieren, während die status SERVICE_START_PENDING ist oder der Dienst abstürzen kann. Übernehmen Sie nach Abschluss der Initialisierung den SERVICE_CONTROL_STOP Code.
Rufen Sie diese Funktion nur mit Prüfpunkt- und Wartehinweiswerten auf, wenn der Dienst Fortschritte bei den Aufgaben im Zusammenhang mit dem ausstehenden Start-, Stopp-, Anhalten- oder Fortsetzungsvorgang macht. Andernfalls kann SCM nicht erkennen, ob Ihr Dienst hängen geblieben ist.
Geben Sie den Status beendet mit einem entsprechenden Exitcode ein, wenn ServiceMain fehlschlägt.
Wenn die status SERVICE_STOPPED ist, führen Sie alle erforderlichen Bereinigungen aus, und rufen Sie SetServiceStatus nur einmal auf. Diese Funktion führt einen LRPC-Aufruf an den SCM aus. Der erste Aufruf der Funktion im SERVICE_STOPPED Zustand schließt das RPC-Kontexthandle, und alle nachfolgenden Aufrufe können zum Absturz des Prozesses führen.
Versuchen Sie nicht, nach dem Aufruf von SetServiceStatus mit SERVICE_STOPPED zusätzliche Arbeit auszuführen, da der Dienstprozess jederzeit beendet werden kann.

Beispiele

Ein Beispiel finden Sie unter Schreiben einer ServiceMain-Funktion.

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 (einschließen von Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll