NotifyServiceStatusChangeA-Funktion (winsvc.h)
Ermöglicht es einer Anwendung, Benachrichtigungen zu erhalten, wenn der angegebene Dienst erstellt oder gelöscht wird oder wenn sich der 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 to services are returned by the OpenService or CreateService function and must have the SERVICE_QUERY_STATUS access right. Handles an den Dienststeuerungs-Manager werden von der OpenSCManager--Funktion zurückgegeben und müssen über das SC_MANAGER_ENUMERATE_SERVICE Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Service Security and Access Rights.
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 sein.
| Wert | Bedeutung |
|---|---|
|
Melden Sie, wann der Dienst erstellt wurde.
Der hService--Parameter muss ein Handle für das SCM sein. |
|
Melden Sie, wann der Dienst fortgesetzt werden soll.
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 sie gelöscht werden kann.
Der hService--Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, wann 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 Sie, wenn der Dienst anzuhalten ist.
Der hService--Parameter muss ein Handle für den Dienst sein. |
|
Melden, wenn der Dienst angehalten wurde.
Der hService--Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, wann der Dienst ausgeführt wird.
Der hService--Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, wann der Dienst gestartet wird.
Der hService--Parameter muss ein Handle für den Dienst sein. |
|
Melden Sie, 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 bricht die Benachrichtigungsanforderung ab.
Führen Sie nicht mehrere Aufrufe an NotifyServiceStatusChange mit demselben Pufferparameter aus, bis die Rückruffunktion aus dem ersten Aufruf 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 es sich bei der Rückruffunktion nicht um Code handelt, der zur Laufzeit generiert wird (z. B. verwalteter Code, der vom JIT-Compiler generiert wird) oder systemeigener 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 der Handle für den Dienst muss geschlossen werden. Wenn die Dienstbenachrichtigung zu weit hinter dem Systemzustand liegt, gibt die Funktion ERROR_SERVICE_NOTIFY_CLIENT_LAGGING zurück. In diesem Fall sollte der Client das Handle mit dem SCM schließen, ein neues Handle öffnen und diese Funktion erneut aufrufen.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes.
Bemerkungen
Die NotifyServiceStatusChange--Funktion kann verwendet werden, um Benachrichtigungen über Dienstanwendungen zu erhalten. Es kann nicht verwendet werden, um Benachrichtigungen über Treiberdienste zu erhalten.
Wenn sich der Dienststatus ändert, ruft das System die angegebene Rückruffunktion als asynchronen Prozeduraufruf (APC) in die Warteschlange des aufrufenden Threads auf. Der aufrufende Thread muss eine warnbare Wartezeit eingeben (z. B. durch Aufrufen der SleepEx--Funktion), um Benachrichtigungen zu empfangen. Weitere Informationen finden Sie unter asynchronen 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 nicht geändert hat, wenn die Funktion das nächste Mal mit demselben Dienst und Zustand aufgerufen wird, wird die Rückruffunktion nicht sofort in die Warteschlange gestellt. Die Rückruffunktion wird bei der nächsten Eingabe des Diensts in die Warteschlange gestellt.
Die funktion NotifyServiceStatusChange ruft die OpenThread- funktion im aufrufenden Thread mit dem THREAD_SET_CONTEXT Zugriffsrecht 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 andere 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 den Diensthandle mithilfe der CloseServiceHandle--Funktion. Nachdem CloseServiceHandle erfolgreich ist, werden keine Benachrichtigungs-APCs mehr in die Warteschlange gestellt. Wenn der aufrufende Thread beendet wird, ohne das Diensthandle zu schließen oder zu warten, bis das APC generiert wird, kann ein Speicherverlust auftreten.
Anmerkung
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 |
|---|---|
| mindestens unterstützte Client- | Windows Vista [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winsvc.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |