RegisterServiceCtrlHandlerExA-Funktion (winsvc.h)

Artikel
08/27/2023

Registriert eine Funktion zum Verarbeiten erweiterter Dienststeuerungsanforderungen.

Syntax

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

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.

[in] lpHandlerProc

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

[in, optional] lpContext

Alle benutzerdefinierten Daten. Dieser Parameter, der an die Handlerfunktion übergeben wird, kann helfen, den Dienst zu identifizieren, wenn mehrere Dienste einen Prozess gemeinsam nutzen.

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 RegisterServiceCtrlHandlerEx-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 Steuerungscodes finden Sie unter HandlerEx. 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 RegisterServiceCtrlHandlerEx-Funktion muss vor dem ersten SetServiceStatus-Aufruf aufgerufen werden, da RegisterServiceCtrlHandlerEx 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.

Hinweis

Der winsvc.h-Header definiert RegisterServiceCtrlHandlerEx 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