LPHANDLER_FUNCTION Rückruffunktion (winsvc.h)

Artikel
08/27/2023

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

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

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

Syntax

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

Parameter

dwControl

Rückgabewert

Keine

Bemerkungen

Wenn ein Dienst gestartet wird, sollte seine ServiceMain-Funktion sofort die RegisterServiceCtrlHandler-Funktion aufrufen, um eine Handlerfunktion zum Verarbeiten von Steuerelementanforderungen anzugeben.

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

Die Steuerelementhandlerfunktion soll Benachrichtigungen empfangen und sofort zurückgeben. Die Rückruffunktion sollte ihre 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 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 Steuerungscode an einen Dienst sendet, wartet er, bis die Handlerfunktion zurückgegeben wird, bevor er zusätzliche Steuerungscodes an andere Dienste sendet. Der Steuerelementhandler sollte so schnell wie möglich zurückgegeben werden. wenn es nicht innerhalb von 30 Sekunden zurückgegeben wird, gibt der SCM einen Fehler zurück. Wenn ein Dienst eine langwierige 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ückgegeben wird. Dadurch wird verhindert, dass der Dienst den Kontrollverteiler bindet und andere Dienste daran hindert, Kontrollcodes zu empfangen.

Der SERVICE_CONTROL_SHUTDOWN-Steuerungscode 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 rechtzeitig beenden. Andernfalls kann der Dienst die zum Herunterfahren des Systems erforderliche Zeit verlängern, da das System die gesamte Zeit warten muss, die für das Herunterfahren des Diensts zulässig ist, bevor das Herunterfahren des Systems fortgesetzt 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 er warten muss, 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 eine Beschränkung für die Wartezeit des Dienstcontrollers. Wenn der Dienst über das Dienste-Snap-In heruntergefahren wird, beträgt der Grenzwert 125 Sekunden. Wenn das Betriebssystem neu gestartet wird, wird das Zeitlimit im Wert WaitToKillServiceTimeout des folgenden Registrierungsschlüssels angegeben:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

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

Beispiele

Ein Beispiel finden Sie unter Schreiben einer Steuerelementhandlerfunktion.

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)