LPHANDLER_FUNCTION_EX Rückruffunktion (winsvc.h)

Artikel
08/27/2023

Eine anwendungsdefinierte Rückruffunktion, die mit der Funktion RegisterServiceCtrlHandlerEx verwendet wird. Ein Dienstprogramm kann es als Steuerelementhandlerfunktion eines bestimmten Diensts verwenden.

Der LPHANDLER_FUNCTION_EX Typ definiert einen Zeiger auf diese Funktion. HandlerEx ist ein Platzhalter für den von der Anwendung definierten Namen.

Diese Funktion ersetzt die Handler-Steuerelementhandlerfunktion, die mit der Funktion RegisterServiceCtrlHandler verwendet wird. Ein Dienst kann beide Steuerelementhandler verwenden, aber der neue Steuerelementhandler unterstützt benutzerdefinierte Kontextdaten und zusätzliche erweiterte Steuerelementcodes.

Syntax

LPHANDLER_FUNCTION_EX LphandlerFunctionEx;

DWORD LphandlerFunctionEx(
  [in] DWORD dwControl,
  [in] DWORD dwEventType,
  [in] LPVOID lpEventData,
  [in] LPVOID lpContext
)
{...}

Parameter

[in] dwControl

Der Steuerelementcode. Dieser Parameter kann einen der folgenden Werte annehmen.

Steuerungscode	Bedeutung
SERVICE_CONTROL_CONTINUE 0x00000003	Benachrichtigt einen angehaltenen Dienst, dass er fortgesetzt werden soll.
SERVICE_CONTROL_INTERROGATE 0x00000004	Benachrichtigt einen Dienst, seine aktuellen status Informationen an den Dienststeuerungs-Manager zu melden. Der Handler sollte einfach NO_ERROR zurückgeben. der SCM den aktuellen Status des Diensts kennt.
SERVICE_CONTROL_NETBINDADD 0x00000007	Benachrichtigt einen Netzwerkdienst, dass eine neue Komponente für die Bindung vorhanden ist. Der Dienst sollte an die neue Komponente gebunden werden. Anwendungen sollten stattdessen Plug & Play Funktionalität verwenden.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Benachrichtigt einen Netzwerkdienst, dass eine seiner Bindungen deaktiviert wurde. Der Dienst sollte seine Bindungsinformationen erneut lesen und die Bindung entfernen. Anwendungen sollten stattdessen Plug & Play Funktionalität verwenden.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Benachrichtigt einen Netzwerkdienst, dass eine deaktivierte Bindung aktiviert wurde. Der Dienst sollte seine Bindungsinformationen erneut lesen und die neue Bindung hinzufügen. Anwendungen sollten stattdessen Plug & Play Funktionalität verwenden.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Benachrichtigt einen Netzwerkdienst, dass eine Komponente für die Bindung entfernt wurde. Der Dienst sollte seine Bindungsinformationen erneut lesen und die Bindung an die entfernte Komponente aufheben. Anwendungen sollten stattdessen Plug & Play Funktionalität verwenden.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Benachrichtigt einen Dienst, dass dienstspezifische Startparameter geändert wurden. Der Dienst sollte seine Startparameter erneut lesen.
SERVICE_CONTROL_PAUSE 0x00000002	Benachrichtigt einen Dienst, dass er angehalten werden soll.
SERVICE_CONTROL_PRESHUTDOWN 0x0000000F	Benachrichtigt einen Dienst, dass das System heruntergefahren wird. Dienste, die zusätzliche Zeit benötigen, um Bereinigungsaufgaben über die enge Zeitbeschränkung beim Herunterfahren des Systems hinaus auszuführen, können diese Benachrichtigung verwenden. Der Dienststeuerungs-Manager sendet diese Benachrichtigung an Anwendungen, die sich dafür registriert haben, bevor eine SERVICE_CONTROL_SHUTDOWN Benachrichtigung an Anwendungen gesendet wird, die sich für diese Benachrichtigung registriert haben. Ein Dienst, der diese Benachrichtigung verarbeitet, blockiert das Herunterfahren des Systems, bis der Dienst beendet wird oder das durch SERVICE_PRESHUTDOWN_INFO angegebene Timeoutintervall vor dem Herunterfahren abläuft. Da sich dies auf die Benutzererfahrung auswirkt, sollten Dienste dieses Feature nur verwenden, wenn es unbedingt erforderlich ist, um Datenverluste oder eine erhebliche Wiederherstellungszeit beim nächsten Systemstart zu vermeiden. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
SERVICE_CONTROL_SHUTDOWN 0x00000005	Benachrichtigt einen Dienst, dass das System heruntergefahren wird, damit der Dienst Bereinigungsaufgaben ausführen kann. Beachten Sie, dass Dienste, die sich für SERVICE_CONTROL_PRESHUTDOWN Benachrichtigungen registrieren, diese Benachrichtigung nicht empfangen können, da sie bereits beendet wurden. Wenn ein Dienst diesen Steuerungscode akzeptiert, muss er beendet werden, nachdem er seine Bereinigungsaufgaben ausgeführt hat und NO_ERROR zurückgibt. Nachdem der SCM diesen Steuerungscode gesendet hat, werden keine anderen Steuercodes an den Dienst gesendet. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.
SERVICE_CONTROL_STOP 0x00000001	Benachrichtigt einen Dienst, dass er beendet werden soll. Wenn ein Dienst diesen Kontrollcode akzeptiert, muss er nach Erhalt beendet werden und NO_ERROR zurückgeben. Nachdem der SCM diesen Steuerungscode gesendet hat, werden keine anderen Steuercodes an den Dienst gesendet. Windows XP: Wenn der Dienst NO_ERROR zurückgibt und weiterhin ausgeführt wird, empfängt er weiterhin Kontrollcodes. Dieses Verhalten hat sich ab Windows Server 2003 und Windows XP mit SP2 geändert.

Dieser Parameter kann auch einer der folgenden erweiterten Steuercodes sein. Beachten Sie, dass diese Steuerelementcodes von der Handlerfunktion nicht unterstützt werden.

Steuerungscode	Bedeutung
SERVICE_CONTROL_DEVICEEVENT 0x0000000B	Benachrichtigt einen Dienst über Geräteereignisse. (Der Dienst muss registriert sein, um diese Benachrichtigungen mithilfe der RegisterDeviceNotification-Funktion zu empfangen.) Die Parameter dwEventType und lpEventData enthalten zusätzliche Informationen.
SERVICE_CONTROL_HARDWAREPROFILECHANGE 0x0000000C	Benachrichtigt einen Dienst, dass das Hardwareprofil des Computers geändert wurde. Der dwEventType-Parameter enthält zusätzliche Informationen.
SERVICE_CONTROL_POWEREVENT 0x0000000D	Benachrichtigt einen Dienst über Systemleistungsereignisse. Der dwEventType-Parameter enthält zusätzliche Informationen. Wenn dwEventTypePBT_POWERSETTINGCHANGE ist, enthält der lpEventData-Parameter auch zusätzliche Informationen.
SERVICE_CONTROL_SESSIONCHANGE 0x0000000E	Benachrichtigt einen Dienst über Sitzungsänderungsereignisse. Beachten Sie, dass ein Dienst nur über eine Benutzeranmeldung benachrichtigt wird, wenn er vollständig geladen ist, bevor der Anmeldeversuch durchgeführt wird. Die Parameter dwEventType und lpEventData enthalten zusätzliche Informationen.
SERVICE_CONTROL_TIMECHANGE 0x00000010	Benachrichtigt einen Dienst, dass sich die Systemzeit geändert hat. Der lpEventData-Parameter enthält zusätzliche Informationen. Der dwEventType-Parameter wird nicht verwendet. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Steuerelementcode wird nicht unterstützt.
SERVICE_CONTROL_TRIGGEREVENT 0x00000020	Benachrichtigt einen Dienst, der für ein Diensttriggerereignis registriert ist, dass das Ereignis aufgetreten ist. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Steuerelementcode wird nicht unterstützt.
SERVICE_CONTROL_USERMODEREBOOT 0x00000040	Benachrichtigt einen Dienst, dass der Benutzer einen Neustart initiiert hat. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Steuerelementcode wird nicht unterstützt.

Dieser Parameter kann auch ein benutzerdefinierter Steuerelementcode sein, wie in der folgenden Tabelle beschrieben.

Steuerungscode	Bedeutung
Bereich 128 bis 255.	Der Dienst definiert die Aktion, die dem Steuerelementcode zugeordnet ist.

[in] dwEventType

Der Ereignistyp, der aufgetreten ist. Dieser Parameter wird verwendet, wenn dwControlSERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT oder SERVICE_CONTROL_SESSIONCHANGE ist. Andernfalls ist er null.

Wenn dwControlSERVICE_CONTROL_DEVICEEVENT ist, kann dieser Parameter einer der folgenden Werte sein:

Wenn dwControlSERVICE_CONTROL_HARDWAREPROFILECHANGE ist, kann dieser Parameter einer der folgenden Werte sein:

Wenn dwControlSERVICE_CONTROL_POWEREVENT ist, kann dieser Parameter einer der Werte sein, die im wParam-Parameter der WM_POWERBROADCAST Meldung angegeben sind.

Wenn dwControlSERVICE_CONTROL_SESSIONCHANGE ist, kann dieser Parameter einer der Werte sein, die im wParam-Parameter der WM_WTSSESSION_CHANGE Meldung angegeben sind.

[in] lpEventData

Zusätzliche Geräteinformationen, falls erforderlich. Das Format dieser Daten hängt vom Wert der Parameter dwControl und dwEventType ab.

Wenn dwControlSERVICE_CONTROL_DEVICEEVENT ist, entsprechen diese Daten dem lParam-Parameter , den Anwendungen im Rahmen einer WM_DEVICECHANGE-Nachricht empfangen.

Wenn dwControlSERVICE_CONTROL_POWEREVENT und dwEventType PBT_POWERSETTINGCHANGE ist, sind diese Daten ein Zeiger auf eine POWERBROADCAST_SETTING-Struktur .

Wenn dwControlSERVICE_CONTROL_SESSIONCHANGE ist, ist dieser Parameter ein Zeiger auf eine WTSSESSION_NOTIFICATION-Struktur .

Wenn dwControlSERVICE_CONTROL_TIMECHANGE ist, sind diese Daten ein Zeiger auf eine SERVICE_TIMECHANGE_INFO-Struktur .

[in] lpContext

Von RegisterServiceCtrlHandlerEx übergebene benutzerdefinierte Daten. Wenn mehrere Dienste einen Prozess gemeinsam nutzen, kann der lpContext-Parameter den Dienst identifizieren.

Rückgabewert

Der Rückgabewert für diese Funktion hängt vom empfangenen Steuerungscode ab.

In der folgenden Liste werden die Regeln für diesen Rückgabewert angegeben:

Wenn Ihr Dienst das Steuerelement nicht verarbeitet, geben Sie im Allgemeinen ERROR_CALL_NOT_IMPLEMENTED zurück. Ihr Dienst sollte jedoch NO_ERROR für SERVICE_CONTROL_INTERROGATE zurückgeben, auch wenn ihr Dienst dies nicht verarbeitet.
Wenn Ihr Dienst SERVICE_CONTROL_STOP oder SERVICE_CONTROL_SHUTDOWN verarbeitet, geben Sie NO_ERROR zurück.
Wenn Ihr Dienst SERVICE_CONTROL_DEVICEEVENT verarbeitet, geben Sie NO_ERROR zurück, um der Anforderung und einen Fehlercode zum Ablehnen der Anforderung zu gewähren.
Wenn Ihr Dienst SERVICE_CONTROL_HARDWAREPROFILECHANGE verarbeitet, geben Sie NO_ERROR zurück, um die Anforderung zu gewähren, und einen Fehlercode, um die Anforderung zu verweigern.
Wenn Ihr Dienst SERVICE_CONTROL_POWEREVENT verarbeitet, geben Sie NO_ERROR zurück, um der Anforderung und einen Fehlercode zum Ablehnen der Anforderung zu gewähren.
Geben Sie für alle anderen Steuerelementcodes, die Ihr Dienst verarbeitet, NO_ERROR zurück.

Hinweise

Wenn ein Dienst gestartet wird, sollte seine ServiceMain-Funktion sofort die RegisterServiceCtrlHandlerEx-Funktion aufrufen, um eine HandlerEx-Funktion zum Verarbeiten von Steuerungsanforderungen anzugeben. Um die zu akzeptierenden Steuercodes anzugeben, verwenden Sie die Funktionen SetServiceStatus und RegisterDeviceNotification .

Der Steuerelementverteiler im Standard Thread eines Diensts ruft die Steuerelementhandlerfunktion für den angegebenen Dienst auf, wenn er eine Steuerungsanforderung vom Dienststeuerungs-Manager empfängt. Nach der Verarbeitung der Steuerelementanforderung muss der Steuerelementhandler SetServiceStatus aufrufen, wenn sich der Dienststatus ändert, um seine neue status an den Dienststeuerungs-Manager zu melden.

Die Steuerelementhandlerfunktion soll Benachrichtigungen empfangen und sofort zurückgegeben werden. Die Rückruffunktion sollte ihre Parameter speichern und weitere Threads erstellen, um zusätzliche Aufgaben auszuführen. (Ihre Anwendung muss sicherstellen, dass solche Threads beendet wurden, bevor sie den Dienst beendet.) Insbesondere sollte ein Steuerelementhandler Vorgänge vermeiden, die blockiert werden könnten, z. B. eine Sperre, da dies zu einem Deadlock führen oder dazu führen kann, dass das System nicht mehr reagiert.

Wenn der Dienststeuerungs-Manager einen Steuercode an einen Dienst sendet, wartet er, bis die Handlerfunktion zurückgegeben wird, bevor zusätzliche Steuercodes an andere Dienste gesendet werden. Der Steuerelementhandler sollte so schnell wie möglich zurückgegeben werden. Wenn es nicht innerhalb von 30 Sekunden zurückgibt, gibt der SCM einen Fehler zurück. Wenn ein Dienst eine lange Verarbeitung durchführen muss, wenn der Dienst den Steuerelementhandler ausführt, sollte er einen sekundären Thread erstellen, um die langwierige Verarbeitung auszuführen, und dann vom Steuerelementhandler zurückgeben. Dadurch wird verhindert, dass der Dienst den Kontrollverteiler bindet und andere Dienste daran hindert, Kontrollcodes zu empfangen.

Der SERVICE_CONTROL_SHUTDOWN Steuercode sollte nur von Diensten verarbeitet werden, die während des Herunterfahrens unbedingt sauber müssen, da für das Herunterfahren des Diensts eine begrenzte Zeit (ca. 20 Sekunden) verfügbar ist. Nach Ablauf dieser Zeit wird das Herunterfahren des Systems unabhängig davon fortgesetzt, ob das Herunterfahren des Diensts abgeschlossen ist. Beachten Sie, dass der Dienst weiterhin ausgeführt wird, wenn sich das System im Zustand "Herunterfahren" befindet (nicht neu gestartet oder heruntergefahren). Wenn ihr Dienst registriert wird, um SERVICE_CONTROL_SHUTDOWN zu akzeptieren, muss er den Steuerungscode verarbeiten und NO_ERROR zurückgeben. Das Zurückgeben eines Fehlers für diesen Steuerungscode und das nicht rechtzeitige Beenden kann die zum Herunterfahren des Systems erforderliche Zeit erhöhen, da das System die gesamte Zeit warten muss, die für das Herunterfahren des Diensts zulässig ist, bevor das System beendet werden kann.

Wenn der Dienst mehr Zeit zum sauber benötigt, sollte er STOP_PENDING status Nachrichten zusammen mit einem Wartehinweis senden, damit der Dienstcontroller weiß, wie lange gewartet werden muss, bevor er dem System meldet, dass der Dienst beendet ist. Um jedoch zu verhindern, dass ein Dienst das Herunterfahren beendet, gibt es eine Beschränkung für die Wartezeit des Dienstcontrollers. Wenn der Dienst über das Snap-In Dienste heruntergefahren wird, beträgt der Grenzwert 125 Sekunden. Wenn das Betriebssystem neu gestartet wird, wird das Zeitlimit im WaitToKillServiceTimeout-Wert des folgenden Registrierungsschlüssels angegeben:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

Achten Sie darauf, Plug & Play Geräteereignisse so schnell wie möglich zu behandeln. Andernfalls reagiert das System möglicherweise nicht mehr. Wenn Ihr Ereignishandler einen Vorgang ausführt, der die Ausführung möglicherweise blockiert (z. B. E/A), empfiehlt es sich, einen anderen Thread zu starten, um den Vorgang asynchron auszuführen.

Dienste können auch die SetConsoleCtrlHandler-Funktion verwenden, um eine Benachrichtigung zum Herunterfahren zu erhalten. Diese Benachrichtigung wird empfangen, wenn die ausgeführten Anwendungen heruntergefahren werden. Dies geschieht, bevor Dienste heruntergefahren werden.

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)