Lire en anglais

Partager via


NotifyServiceStatusChangeW, 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 NotifyServiceStatusChangeW(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYW 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
SERVICE_NOTIFY_CREATED
0x00000080
Signaler quand le service a été créé.

Le paramètre hService doit être un handle pour le SCM.

SERVICE_NOTIFY_CONTINUE_PENDING
0x00000010
Signalez quand le service est sur le point de continuer.

Le paramètre hService doit être un handle pour le service.

SERVICE_NOTIFY_DELETE_PENDING
0x00000200
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.

SERVICE_NOTIFY_DELETED
0x00000100
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 doit être un handle pour le SCM.

SERVICE_NOTIFY_PAUSE_PENDING
0x00000020
Signaler le moment où le service s’interrompt.

Le paramètre hService doit être un handle pour le service.

SERVICE_NOTIFY_PAUSED
0x00000040
Signaler le moment où le service a suspendu.

Le paramètre hService doit être un handle pour le service.

SERVICE_NOTIFY_RUNNING
0x00000008
Signaler le moment où le service est en cours d’exécution.

Le paramètre hService doit être un handle pour le service.

SERVICE_NOTIFY_START_PENDING
0x00000002
Signaler le démarrage du service.

Le paramètre hService doit être un handle pour le service.

SERVICE_NOTIFY_STOP_PENDING
0x00000004
Signalez quand le service s’arrête.

Le paramètre hService doit être un handle pour le service.

SERVICE_NOTIFY_STOPPED
0x00000001
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.

important Si le thread appelant se trouve dans une DLL et que la DLL est déchargée avant que le thread ne reçoive la notification ou les appels CloseServiceHandle, la notification entraîne des résultats imprévisibles et peut entraîner l’arrêt du processus de réponse.
 

Notes

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

Voir aussi

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Fonctions de service