LPHANDLER_FUNCTION_EX Rückruffunktion (winsvc.h)

  • Artikel

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

Der typ LPHANDLER_FUNCTION_EX definiert einen Zeiger auf diese Funktion. HandlerEx ist ein Platzhalter für den anwendungsdefinierten Namen.

Diese Funktion ersetzt die Handler-Steuerelementhandlerfunktion, die mit der Funktion RegisterServiceCtrlHandler verwendet wird. Ein Dienst kann entweder 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.

Steuerelementcode Bedeutung
SERVICE_CONTROL_CONTINUE
0x00000003
 Benachrichtigt einen angehaltenen Dienst, dass er fortgesetzt werden soll.
SERVICE_CONTROL_INTERROGATE
0x00000004
 Benachrichtigt einen Dienst, um seine aktuellen Statusinformationen an den Dienststeuerungs-Manager zu melden.

Der Handler sollte einfach NO_ERROR zurückgeben; der SCM ist über den aktuellen Status des Diensts informiert.
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 aus der entfernten Komponente aufgehoben werden.

Anwendungen sollten stattdessen Plug & Play Funktionalität verwenden.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
 Benachrichtigt einen Dienst, der dienstspezifische Startparameter geändert hat. Der Dienst sollte seine Startparameter erneut lesen.
SERVICE_CONTROL_PAUSE
0x00000002
 benachrichtigt einen Dienst, der angehalten werden soll.
SERVICE_CONTROL_PRESHUTDOWN
0x0000000F
 Benachrichtigt einen Dienst, dass das System heruntergefahren wird. Dienste, die zusätzliche Zeit benötigen, um Bereinigungsaufgaben außerhalb der engen Zeiteinschränkung beim Herunterfahren des Systems auszuführen, können diese Benachrichtigung verwenden. Der Dienststeuerungs-Manager sendet diese Benachrichtigung an Anwendungen, die sich für diese Benachrichtigung registriert haben, bevor eine SERVICE_CONTROL_SHUTDOWN Benachrichtigung an Anwendungen gesendet wird, die sich für diese Benachrichtigung registriert haben.

Ein Dienst, der das Herunterfahren des Systems blockiert, bis der Dienst beendet wird, oder das über SERVICE_PRESHUTDOWN_INFO angegebene Timeoutintervall vor dem Auslaufen. Da sich dies auf die Benutzererfahrung auswirkt, sollten Dienste dieses Feature nur verwenden, wenn es unbedingt erforderlich ist, Datenverluste oder 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 erhalten können, da sie bereits beendet wurden.

Wenn ein Dienst diesen Steuerelementcode akzeptiert, muss er beendet werden, nachdem er seine Bereinigungsaufgaben ausführt und NO_ERROR zurückgibt. Nachdem der SCM diesen Steuerelementcode gesendet hat, sendet er keine anderen Steuerelementcodes an den Dienst.

Weitere Informationen finden Sie im Abschnitt "Hinweise" dieses Themas.
SERVICE_CONTROL_STOP
0x00000001
 benachrichtigt einen Dienst, der beendet werden soll.

Wenn ein Dienst diesen Steuerelementcode akzeptiert, muss er nach Erhalt beenden und NO_ERROR zurückgeben. Nachdem der SCM diesen Steuerelementcode gesendet hat, sendet er keine anderen Steuerelementcodes an den Dienst. Windows XP: Wenn der Dienst NO_ERROR zurückgibt und weiterhin ausgeführt wird, empfängt er weiterhin Steuerelementcodes. Dieses Verhalten wurde ab Windows Server 2003 und Windows XP mit SP2 geändert.
 

Dieser Parameter kann auch eine der folgenden erweiterten Steuerelementcodes sein. Beachten Sie, dass diese Steuerelementcodes von der Handler-Funktion nicht unterstützt werden.

Steuerungscode Bedeutung
SERVICE_CONTROL_DEVICEEVENT
0x0000000B
 Benachrichtigt einen Dienst von Geräteereignissen. (Der Dienst muss registriert sein, um diese Benachrichtigungen mithilfe der Funktion RegisterDeviceNotification zu erhalten.) Die Parameter dwEventType und lpEventData enthalten zusätzliche Informationen.
SERVICE_CONTROL_HARDWAREPROFILECHANGE
0x0000000C
 Benachrichtigt einen Dienst, den das Hardwareprofil des Computers geändert hat. Der dwEventType-Parameter enthält zusätzliche Informationen.
SERVICE_CONTROL_POWEREVENT
0x0000000D
 Benachrichtigt einen Dienst von Systemleistungsereignissen. Der dwEventType-Parameter enthält zusätzliche Informationen. Wenn dwEventTypePBT_POWERSETTINGCHANGE ist, enthält der parameter lpEventData auch zusätzliche Informationen.
SERVICE_CONTROL_SESSIONCHANGE
0x0000000E
 Benachrichtigt einen Dienst der Sitzungsänderungsereignisse. Beachten Sie, dass ein Dienst nur über die Anmeldung eines Benutzers benachrichtigt wird, wenn er vollständig geladen wird, 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 parameter lpEventData 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 Dienstauslöserereignis registriert ist, das 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, den der Benutzer ein 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.

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

[in] dwEventType

Der Typ des Ereignisses, das aufgetreten ist. Dieser Parameter wird verwendet, wenn dwControlSERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT oder SERVICE_CONTROL_SESSIONCHANGE ist. Andernfalls ist es null.

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

Wenn dwControlSERVICE_CONTROL_HARDWAREPROFILECHANGE ist, kann dieser Parameter eine der folgenden Werte sein: Wenn dwControlSERVICE_CONTROL_POWEREVENT ist, kann dieser Parameter eine der werte sein, die im wParam-Parameter der WM_POWERBROADCAST-Nachricht angegeben sind.

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

[in] lpEventData

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

Wenn dwControlSERVICE_CONTROL_DEVICEEVENT ist, entspricht diese Daten dem lParam-Parameter , den Anwendungen als Teil einer WM_DEVICECHANGE Nachricht empfangen.

Wenn dwControl SERVICE_CONTROL_POWEREVENT ist und dwEventTypePBT_POWERSETTINGCHANGE ist, ist 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, ist diese Daten ein Zeiger auf eine SERVICE_TIMECHANGE_INFO Struktur.

[in] lpContext

Benutzerdefinierte Daten, die von RegisterServiceCtrlHandlerEx übergeben wurden. Wenn mehrere Dienste einen Prozess freigeben, kann der lpContext-Parameter den Dienst identifizieren.

Rückgabewert

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

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

  • Wenn Ihr Dienst das Steuerelement nicht behandelt, geben Sie ERROR_CALL_NOT_IMPLEMENTED zurück. Ihr Dienst sollte jedoch NO_ERROR für SERVICE_CONTROL_INTERROGATE zurückgeben, auch wenn Ihr Dienst sie nicht behandelt.
  • Wenn Ihr Dienst SERVICE_CONTROL_STOP oder SERVICE_CONTROL_SHUTDOWN behandelt, geben Sie NO_ERROR zurück.
  • Wenn Ihr Dienst SERVICE_CONTROL_DEVICEEVENT behandelt, geben Sie NO_ERROR zurück, um die Anforderung und einen Fehlercode zu gewähren, um die Anforderung zu verweigern.
  • Wenn Ihr Dienst SERVICE_CONTROL_HARDWAREPROFILECHANGE behandelt, geben Sie NO_ERROR zurück, um die Anforderung und einen Fehlercode zu gewähren, um die Anforderung zu verweigern.
  • Wenn Ihr Dienst SERVICE_CONTROL_POWEREVENT behandelt, geben Sie NO_ERROR zurück, um die Anforderung und einen Fehlercode zu erteilen, um die Anforderung zu verweigern.
  • Geben Sie für alle anderen Steuerelementcodes, die Ihre Diensthandpunkte behandeln, 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 Steuerelementanforderungen anzugeben. Um die zu akzeptierenden Steuerelementcodes anzugeben, verwenden Sie die Funktionen "SetServiceStatus " und "RegisterDeviceNotification ".

Der Steuerelement-Dispatcher im Hauptthread eines Diensts ruft die Steuerelementhandlerfunktion für den angegebenen Dienst auf, wenn er eine Steuerelementanforderung vom Dienststeuerelement-Manager empfängt. Nach der Verarbeitung der Steuerelementanforderung muss der Steuerelementhandler SetServiceStatus aufrufen, wenn sich der Dienststatus ändert, um seinen neuen Status dem Dienststeuerungs-Manager zu melden.

Die Steuerelementhandlerfunktion soll Benachrichtigungen empfangen und sofort zurückgeben. Die Rückruffunktion sollte die Parameter speichern und andere Threads erstellen, um zusätzliche Arbeit auszuführen. (Ihre Anwendung muss sicherstellen, dass solche Threads beendet wurden, bevor Sie den Dienst beenden.) Insbesondere sollte ein Steuerelementhandler Vorgänge vermeiden, die blockiert werden könnten, z. B. das Ausführen einer Sperrung, da dies zu einem Deadlock führen könnte oder dazu führt, dass das System nicht mehr reagiert.

Wenn der Dienststeuerungs-Manager einen Steuerelementcode an einen Dienst sendet, wartet er darauf, dass die Handlerfunktion zurückgegeben wird, bevor zusätzliche Steuerelementcodes an andere Dienste gesendet werden. Der Steuerelementhandler sollte so schnell wie möglich zurückgegeben werden; wenn es innerhalb von 30 Sekunden nicht zurückgegeben wird, gibt der SCM einen Fehler zurück. Wenn ein Dienst eine lange Verarbeitung durchführen muss, wenn der Dienst den Steuerelementhandler ausführt, sollte ein sekundärer Thread erstellt werden, um die lange Verarbeitung auszuführen und dann aus dem Steuerelementhandler zurückzugeben. Dadurch wird verhindert, dass der Dienst den Kontrollverteiler verbindet und andere Dienste vor dem Empfang von Kontrollcodes blockiert.

Der SERVICE_CONTROL_SHUTDOWN-Steuerelementcode sollte nur von Diensten verarbeitet werden, die während des Herunterfahrens absolut bereinigen müssen, da es eine begrenzte Zeit (etwa 20 Sekunden) für das Herunterfahren des Diensts verfügbar ist. Nach Ablauf dieser Zeit wird das Systemabfahren unabhängig davon fortgesetzt, ob das Herunterfahren des Diensts abgeschlossen ist. Beachten Sie, dass das System im herunterfahrenden Zustand (nicht neu gestartet oder heruntergefahren) bleibt, dass der Dienst weiterhin ausgeführt wird. Wenn ihr Dienst SERVICE_CONTROL_SHUTDOWN akzeptiert, muss er den Steuerelementcode behandeln und NO_ERROR zurückgeben. Wenn Sie einen Fehler für diesen Steuerelementcode zurückgeben und nicht rechtzeitig beenden können, kann die Zeit erhöht werden, die erforderlich ist, um das System herunterzufahren, da das System auf die vollständige Zeit warten muss, die für das Herunterfahren des Diensts zulässig ist, bevor das System herunterfahren kann.

Wenn der Dienst mehr Zeit zum Bereinigen benötigt, sollte es STOP_PENDING Statusnachrichten zusammen mit einem Wartenhinweis senden, sodass der Dienstcontroller weiß, wie lange gewartet werden soll, bevor er an das System meldet, dass das Herunterfahren des Diensts abgeschlossen ist. Um jedoch zu verhindern, dass ein Dienst das Herunterfahren beendet, gibt es einen Grenzwert, wie lange der Dienstcontroller wartet. Wenn der Dienst über das Services-Snap-In heruntergefahren wird, beträgt der Grenzwert 125 Sekunden. Wenn das Betriebssystem neu gestartet wird, wird der 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 wird das System möglicherweise nicht mehr verfügbar. Wenn der Ereignishandler einen Vorgang ausführen soll, der die Ausführung blockieren kann (z. B. I/O), empfiehlt es sich, einen anderen Thread zu starten, um den Vorgang asynchron auszuführen.

Dienste können auch die Funktion "SetConsoleCtrlHandler " verwenden, um herunterfahrende Benachrichtigungen zu erhalten. Diese Benachrichtigung wird empfangen, wenn die ausgeführten Anwendungen heruntergefahren werden, was auftritt, bevor Dienste heruntergefahren werden.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winsvc.h (enthalten Windows.h)

Weitere Informationen

POWERBROADCAST_SETTING

RegisterDeviceNotification

RegisterServiceCtrlHandlerEx

Dienststeuerungshandler-Funktion

Dienstfunktionen

ServiceMain

SetServiceStatus

WM_DEVICECHANGE

WM_POWERBROADCAST

WM_WTSSESSION_CHANGE

WTSSESSION_NOTIFICATION