RegisterServiceCtrlHandlerA-Funktion (winsvc.h)

Registriert eine Funktion zum Verarbeiten von Dienststeuerungsanforderungen.

Diese Funktion wurde durch die funktion RegisterServiceCtrlHandlerEx ersetzt. Ein Dienst kann eine der beiden Funktionen verwenden, aber die neue Funktion unterstützt benutzerdefinierte Kontextdaten, und die neue Handlerfunktion unterstützt zusätzliche erweiterte Steuerelementcodes.

Syntax

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

Parameter

[in] lpServiceName

Der Name des Diensts, der vom aufrufenden Thread ausgeführt wird. Dies ist der Dienstname, den das im CreateService--Funktion angegebene Dienststeuerungsprogramm beim Erstellen des Diensts angibt.

Wenn der Diensttyp SERVICE_WIN32_OWN_PROCESS ist, überprüft die Funktion nicht, ob der angegebene Name gültig ist, da nur ein registrierter Dienst im Prozess vorhanden ist.

[in] lpHandlerProc

Ein Zeiger auf die zu registrierende Handlerfunktion. Weitere Informationen finden Sie unter Handler.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Dienststatushandle.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Die folgenden Fehlercodes können vom Dienststeuerungs-Manager festgelegt werden.

Bemerkungen

Die ServiceMain--Funktion eines neuen Diensts sollte sofort die RegisterServiceCtrlHandler--Funktion aufrufen, um eine Steuerelementhandlerfunktion beim Steuerelementverteiler zu registrieren. Dadurch kann der Steuerelementverteilungsdienst die angegebene Funktion aufrufen, wenn sie Steuerelementanforderungen für diesen Dienst empfängt. Eine Liste der möglichen Steuerelementcodes finden Sie unter Handler. Die Threads des aufrufenden Prozesses können das von dieser Funktion zurückgegebene Dienststatushandle verwenden, um den Dienst in nachfolgenden Aufrufen der SetServiceStatus--Funktion zu identifizieren.

Die RegisterServiceCtrlHandler--Funktion muss vor dem ersten SetServiceStatus- Aufruf aufgerufen werden, da RegisterServiceCtrlHandler ein Dienststatushandle für den Aufrufer zurückgibt, damit kein anderer Dienst versehentlich diesen Dienststatusstatus festlegen kann. Darüber hinaus muss der Steuerelementhandler eingerichtet sein, um Steueranforderungen nach dem Zeitpunkt zu empfangen, an dem der Dienst die Steuerelemente angibt, die er über die SetServiceStatus--Funktion akzeptiert.

Wenn die Steuerelementhandlerfunktion mit einer Steuerelementanforderung aufgerufen wird, muss der Dienst SetServiceStatus- aufrufen, um den Status nur dann an den Dienststeuerungs-Manager zu melden, wenn sich der Dienststatus geändert hat, z. B. wenn der Dienst beendete oder herunterfahrende Steuerelemente verarbeitet. Wenn sich der Dienststatus nicht geändert hat, sollte der Dienst den Status nicht an den Dienststeuerungs-Manager melden.

Das Dienststatushandle muss nicht geschlossen werden.

Beispiele

Ein Beispiel finden Sie unter Schreiben einer ServiceMain-Funktion.

Anforderungen

Siehe auch

CreateService-

Handler-

RegisterServiceCtrlHandlerEx

Service Control Handler Function

Dienstfunktionen

ServiceMain-

SetServiceStatus-