Fonction NotifyServiceStatusChangeA (winsvc.h)
Permet à une application de recevoir une notification lorsque le service spécifié est créé ou supprimé ou lorsque son status change.
Syntaxe
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
Paramètres
[in] hService
Handle du service ou du gestionnaire de contrôle de service. Les handles aux services sont retournés par la fonction OpenService ou CreateService et doivent avoir le droit d’accès SERVICE_QUERY_STATUS. Les handles au gestionnaire de contrôle de service sont retournés par la fonction OpenSCManager et doivent avoir le 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 status qui doivent être signalées. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Signaler quand le service a été créé.
Le paramètre hService doit être un handle du SCM. |
|
Signalez quand le service est sur le point de continuer.
Le paramètre hService doit être un handle pour le service. |
|
Signalez quand une application a spécifié le service dans un appel à la fonction DeleteService . Votre application doit fermer tous les handles du service afin qu’il puisse être supprimé.
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 dispose d’un handle ouvert pour le service.
Le paramètre hService doit être un handle du SCM. |
|
Signaler quand le service est en pause.
Le paramètre hService doit être un handle pour le service. |
|
Signalez que le service a été suspendu.
Le paramètre hService doit être un handle pour le service. |
|
Signalez quand 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. |
|
Signaler le moment où le service s’arrête.
Le paramètre hService doit être un handle pour le service. |
|
Signaler quand le service s’est arrêté.
Le paramètre hService doit être un handle pour le service. |
[in] pNotifyBuffer
Pointeur vers une structure de SERVICE_NOTIFY qui contient des informations de notification, comme 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’est pas terminée 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 de 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 retournée
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 du service doit être fermé. Si la notification de service est trop en retard par rapport à l’état 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 pilote.
Lorsque le service status 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 est 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é à la prochaine fois que la fonction est appelée avec le même service et le même é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 ne dispose peut-être pas des autorisations suffisantes pour définir le contexte.
Il est plus efficace d’appeler NotifyServiceStatusChange à partir d’un thread qui effectue une attente 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 peuvent pas être appelées à 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éussi, plus aucun APC de notification ne sera mis en file d’attente. Si le thread appelant se ferme sans fermer le handle de service ou attendre que l’APC soit généré, une fuite de mémoire peut se produire.
Notes
L’en-tête winsvc.h définit NotifyServiceStatusChange comme un 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winsvc.h (inclure Windows.h) |
| Bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |