RegisterServiceCtrlHandlerExA-Funktion (winsvc.h)
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 |
|---|---|
|
Es ist nicht genügend Arbeitsspeicher verfügbar, um einen ANSI-Zeichenfolgenparameter in Unicode zu konvertieren. Dieser Fehler tritt bei Unicode-Zeichenfolgenparametern nicht auf. |
|
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 |