NotifyServiceStatusChangeA-Funktion (winsvc.h)
Ermöglicht es einer Anwendung, Benachrichtigungen zu erhalten, wenn der angegebene Dienst erstellt oder gelöscht wird oder wenn sich seine status ändert.
Syntax
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
Parameter
[in] hService
Ein Handle für den Dienst oder den Dienststeuerungs-Manager. Handles für Dienste werden von der OpenService - oder CreateService-Funktion zurückgegeben und müssen über das zugriffsrecht SERVICE_QUERY_STATUS verfügen. Handles an den Dienststeuerungs-Manager werden von der OpenSCManager-Funktion zurückgegeben und müssen über das zugriffsrecht SC_MANAGER_ENUMERATE_SERVICE verfügen. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.
Pro Dienst kann nur eine ausstehende Benachrichtigungsanforderung vorhanden sein.
[in] dwNotifyMask
Der Typ der status Änderungen, die gemeldet werden sollen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.
| Wert | Bedeutung |
|---|---|
|
Melden, wenn der Dienst erstellt wurde.
Der hService-Parameter muss ein Handle für das SCM sein. |
|
Melden Sie, wenn der Dienst fortgesetzt wird.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, wenn eine Anwendung den Dienst in einem Aufruf der DeleteService-Funktion angegeben hat. Ihre Anwendung sollte alle Handles für den Dienst schließen, damit er gelöscht werden kann.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden, wenn der Dienst gelöscht wurde. Eine Anwendung kann diese Benachrichtigung nicht empfangen, wenn sie über ein offenes Handle für den Dienst verfügt.
Der hService-Parameter muss ein Handle für das SCM sein. |
|
Melden, wenn der Dienst angehalten wird.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, wenn der Dienst angehalten wurde.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden, wenn der Dienst ausgeführt wird.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, wenn der Dienst gestartet wird.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden, wenn der Dienst beendet wird.
Der hService-Parameter muss ein Handle für den Dienst sein. |
|
Melden, wenn der Dienst beendet wurde.
Der hService-Parameter muss ein Handle für den Dienst sein. |
[in] pNotifyBuffer
Ein Zeiger auf eine SERVICE_NOTIFY Struktur, die Benachrichtigungsinformationen enthält, z. B. einen Zeiger auf die Rückruffunktion. Diese Struktur muss gültig bleiben, bis die Rückruffunktion aufgerufen wird oder der aufrufende Thread die Benachrichtigungsanforderung abbricht.
Führen Sie nicht mehrere Aufrufe von NotifyServiceStatusChange mit demselben Pufferparameter aus, bis die Rückruffunktion des ersten Aufrufs mit dem Puffer abgeschlossen ist oder die erste Benachrichtigungsanforderung abgebrochen wurde. Andernfalls gibt es keine Garantie, welche Version des Puffers die Rückruffunktion empfängt.
Windows Vista: Die Adresse der Rückruffunktion muss sich innerhalb des Adressbereichs eines geladenen Moduls befinden. Daher kann die Rückruffunktion nicht Code sein, der zur Laufzeit generiert wird (z. B. verwalteter Code, der vom JIT-Compiler generiert wird) oder nativer Code, der zur Laufzeit dekomprimiert wird. Diese Einschränkung wurde in Windows Server 2008 und Windows Vista mit SP1 entfernt.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS. Wenn der Dienst zum Löschen markiert wurde, wird der Rückgabewert ERROR_SERVICE_MARKED_FOR_DELETE, und das Handle für den Dienst muss geschlossen werden. Wenn die Dienstbenachrichtigung zu weit hinter dem Systemzustand zurückbleibt, gibt die Funktion ERROR_SERVICE_NOTIFY_CLIENT_LAGGING zurück. In diesem Fall sollte der Client das Handle für das SCM schließen, ein neues Handle öffnen und diese Funktion erneut aufrufen.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes.
Hinweise
Die NotifyServiceStatusChange-Funktion kann verwendet werden, um Benachrichtigungen zu Dienstanwendungen zu empfangen. Es kann nicht verwendet werden, um Benachrichtigungen zu Treiberdiensten zu empfangen.
Wenn sich der Dienst status ändert, ruft das System die angegebene Rückruffunktion als asynchronen Prozeduraufruf (APC) auf, der im aufrufenden Thread in die Warteschlange eingereiht wird. Der aufrufende Thread muss eine warnungsfähige Wartezeit (z. B. durch Aufrufen der SleepEx-Funktion ) eingeben, um eine Benachrichtigung zu erhalten. Weitere Informationen finden Sie unter Asynchrone Prozeduraufrufe.
Wenn sich der Dienst bereits in einem der angeforderten Zustände befindet, wenn NotifyServiceStatusChange aufgerufen wird, wird die Rückruffunktion sofort in die Warteschlange gestellt. Wenn sich der Dienststatus beim nächsten Aufruf der Funktion mit demselben Dienst und Zustand nicht geändert hat, wird die Rückruffunktion nicht sofort in die Warteschlange eingereiht. die Rückruffunktion wird in die Warteschlange gestellt, wenn der Dienst das nächste Mal in den angeforderten Zustand wechselt.
Die NotifyServiceStatusChange-Funktion ruft die OpenThread-Funktion im aufrufenden Thread mit dem zugriffsrecht THREAD_SET_CONTEXT auf. Wenn der aufrufende Thread nicht über dieses Zugriffsrecht verfügt, schlägt NotifyServiceStatusChange fehl. Wenn der aufrufende Thread die Identität eines anderen Benutzers angibt, verfügt er möglicherweise nicht über ausreichende Berechtigungen zum Festlegen des Kontexts.
Es ist effizienter, NotifyServiceStatusChange aus einem Thread aufzurufen, der eine Wartezeit ausführt, als einen zusätzlichen Thread zu erstellen.
Nachdem die Rückruffunktion aufgerufen wurde, muss der Aufrufer NotifyServiceStatusChange aufrufen, um zusätzliche Benachrichtigungen zu erhalten. Beachten Sie, dass bestimmte Funktionen in der Windows-API, einschließlich NotifyServiceStatusChange und anderer SCM-Funktionen, Remoteprozeduraufrufe (RPC) verwenden. Diese Funktionen können einen warnbaren Wartevorgang ausführen, sodass sie nicht sicher sind, von der Rückruffunktion aus aufzurufen. Stattdessen sollte die Rückruffunktion die Benachrichtigungsparameter speichern und zusätzliche Aufgaben außerhalb des Rückrufs ausführen.
Um ausstehende Benachrichtigungen abzubrechen, schließen Sie das Diensthandle mithilfe der CloseServiceHandle-Funktion . Nachdem CloseServiceHandle erfolgreich war, werden keine Benachrichtigungs-APCs mehr in die Warteschlange eingereiht. Wenn der aufrufende Thread beendet wird, ohne das Diensthandle zu schließen oder zu warten, bis der APC generiert wird, kann es zu einem Speicherverlust kommen.
Hinweis
Der winsvc.h-Header definiert NotifyServiceStatusChange 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 Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsvc.h (windows.h einschließen) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |