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.

[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.

Anforderungen

Weitere Informationen

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Dienstfunktionen