RegisterServiceCtrlHandlerA-Funktion (winsvc.h)

Artikel
03/13/2024

Registriert eine Funktion zum Verarbeiten von Dienststeuerungsanforderungen.

Diese Funktion wurde durch die Funktion RegisterServiceCtrlHandlerEx abgelöst. Ein Dienst kann beide 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 Dienststeuerungsprogramm in der CreateService-Funktion beim Erstellen des Diensts angegeben hat.

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 Dienst status Handle.

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.

Rückgabecode	Beschreibung
ERROR_NOT_ENOUGH_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um einen ANSI-Zeichenfolgenparameter in Unicode zu konvertieren. Dieser Fehler tritt bei Unicode-Zeichenfolgenparametern nicht auf.
ERROR_SERVICE_NOT_IN_EXE	Der Diensteintrag wurde falsch angegeben, als der Prozess die Funktion StartServiceCtrlDispatcher aufgerufen hat .

Hinweise

Die ServiceMain-Funktion eines neuen Diensts sollte sofort die RegisterServiceCtrlHandler-Funktion aufrufen, um eine Steuerelementhandlerfunktion beim Steuerelementverteiler zu registrieren. Dadurch kann der Steuerelementverteiler die angegebene Funktion aufrufen, wenn er Steuerungsanforderungen 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 Status-Handle 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 einen Dienst status Handle zurückgibt, damit der Aufrufer verwenden kann, damit kein anderer Dienst versehentlich diesen Dienst status festlegen kann. Darüber hinaus muss der Steuerelementhandler vorhanden sein, um Steuerelementanforderungen zu empfangen, bis 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 status nur dann an den Dienststeuerungs-Manager zu melden, wenn sich der Dienst status geändert hat, z. B. wenn der Dienst Stopp- oder Herunterfahren-Steuerelemente verarbeitet. Wenn sich der Dienst status nicht geändert hat, sollte der Dienst status nicht an den Dienststeuerungs-Manager melden.

Der Dienst status Handle muss nicht geschlossen werden.

Beispiele

Ein Beispiel finden Sie unter Schreiben einer ServiceMain-Funktion.

Hinweis

Der winsvc.h-Header definiert RegisterServiceCtrlHandler als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

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)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll