NotifyServiceStatusChangeA, fonction (winsvc.h)
Permet à une application de recevoir une notification lorsque le service spécifié est créé ou supprimé ou lorsque son état change.
Syntaxe
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
Paramètres
[in] hService
Handle vers le service ou le gestionnaire de contrôle de service. Les handles vers les services sont retournés par la fonction OpenService ou CreateService et doivent disposer du droit d’accès SERVICE_QUERY_STATUS. Les handles du gestionnaire de contrôle de service sont retournés par la fonction OpenSCManager et doivent disposer du droit d’accès SC_MANAGER_ENUMERATE_SERVICE. Pour plus d’informations, consultez Sécurité des services et droits d’accès.
Il ne peut y avoir qu’une seule demande de notification en attente par service.
[in] dwNotifyMask
Type de modifications d’état qui doivent être signalées. Ce paramètre peut être une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Signaler quand le service a été créé.
Le paramètre hService |
|
Signalez quand le service est sur le point de continuer.
Le paramètre hService doit être un handle pour le service. |
|
Signaler lorsqu’une application a spécifié le service dans un appel à la fonction DeleteService. Votre application doit fermer tous les handles du service afin qu’elle puisse être supprimée.
Le paramètre hService doit être un handle pour le service. |
|
Signaler quand le service a été supprimé. Une application ne peut pas recevoir cette notification si elle a un handle ouvert au service.
Le paramètre hService |
|
Signaler le moment où le service s’interrompt.
Le paramètre hService doit être un handle pour le service. |
|
Signaler le moment où le service a suspendu.
Le paramètre hService doit être un handle pour le service. |
|
Signaler le moment où le service est en cours d’exécution.
Le paramètre hService doit être un handle pour le service. |
|
Signaler le démarrage du service.
Le paramètre hService doit être un handle pour le service. |
|
Signalez quand le service s’arrête.
Le paramètre hService doit être un handle pour le service. |
|
Signaler le moment où le service s’est arrêté.
Le paramètre hService doit être un handle pour le service. |
[in] pNotifyBuffer
Pointeur vers une structure SERVICE_NOTIFY qui contient des informations de notification, telles qu’un pointeur vers la fonction de rappel. Cette structure doit rester valide jusqu’à ce que la fonction de rappel soit appelée ou que le thread appelant annule la demande de notification.
N’effectuez pas plusieurs appels à NotifyServiceStatusChange avec le même paramètre de mémoire tampon tant que la fonction de rappel du premier appel n’a pas terminé avec la mémoire tampon ou que la première demande de notification n’a pas été annulée. Sinon, il n’existe aucune garantie quant à la version de la mémoire tampon que la fonction de rappel recevra.
Windows Vista : L’adresse de la fonction de rappel doit se trouver dans la plage d’adresses d’un module chargé. Par conséquent, la fonction de rappel ne peut pas être du code généré au moment de l’exécution (par exemple, du code managé généré par le compilateur JIT) ou du code natif qui est décompressé au moment de l’exécution. Cette restriction a été supprimée dans Windows Server 2008 et Windows Vista avec SP1.
Valeur de retour
Si la fonction réussit, la valeur de retour est ERROR_SUCCESS. Si le service a été marqué pour suppression, la valeur de retour est ERROR_SERVICE_MARKED_FOR_DELETE et le handle au service doit être fermé. Si la notification de service est trop en retard derrière l’état du système, la fonction retourne ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. Dans ce cas, le client doit fermer le handle au SCM, ouvrir un nouveau handle et appeler à nouveau cette fonction.
Si la fonction échoue, la valeur de retour est l’un des codes d’erreur système .
Remarques
La fonction NotifyServiceStatusChange peut être utilisée pour recevoir des notifications sur les applications de service. Il ne peut pas être utilisé pour recevoir des notifications sur les services de pilotes.
Lorsque l’état du service change, le système appelle la fonction de rappel spécifiée en tant qu’appel de procédure asynchrone (APC) mis en file d’attente vers le thread appelant. Le thread appelant doit entrer une attente alertable (par exemple, en appelant la fonction SleepEx) pour recevoir une notification. Pour plus d’informations, consultez appels de procédure asynchrone.
Si le service se trouve déjà dans l’un des états demandés lorsque NotifyServiceStatusChange est appelé, la fonction de rappel est mise en file d’attente immédiatement. Si l’état du service n’a pas changé par la prochaine fois que la fonction est appelée avec le même service et l’état, la fonction de rappel n’est pas mise en file d’attente immédiatement ; la fonction de rappel est mise en file d’attente la prochaine fois que le service entre dans l’état demandé.
La fonction NotifyServiceStatusChange appelle la fonction OpenThread sur le thread appelant avec le droit d’accès THREAD_SET_CONTEXT. Si le thread appelant n’a pas ce droit d’accès, NotifyServiceStatusChange échoue. Si le thread appelant emprunte l’identité d’un autre utilisateur, il se peut qu’il ne dispose pas de l’autorisation suffisante pour définir le contexte.
Il est plus efficace d’appeler NotifyServiceStatusChange à partir d’un thread qui effectue une attente plutôt que de créer un thread supplémentaire.
Une fois la fonction de rappel appelée, l’appelant doit appeler NotifyServiceStatusChange pour recevoir des notifications supplémentaires. Notez que certaines fonctions de l’API Windows, notamment NotifyServiceStatusChange et d’autres fonctions SCM, utilisent des appels de procédure distante (RPC) ; ces fonctions peuvent effectuer une opération d’attente pouvant être alertable, de sorte qu’elles ne sont pas sécurisées pour appeler à partir de la fonction de rappel. Au lieu de cela, la fonction de rappel doit enregistrer les paramètres de notification et effectuer tout travail supplémentaire en dehors du rappel.
Pour annuler les notifications en attente, fermez le handle de service à l’aide de la fonction CloseServiceHandle. Une fois CloseServiceHandle réussit, aucune autre API de notification ne sera mise en file d’attente. Si le thread appelant se termine sans fermer le handle de service ou attendre que l’APC soit généré, une fuite de mémoire peut se produire.
Note
L’en-tête winsvc.h définit NotifyServiceStatusChange comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows Vista [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winsvc.h (inclure Windows.h) |
| bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |