Fonction QueryServiceStatusEx (winsvc.h)

Article
08/27/2023

Récupère la status actuelle du service spécifié en fonction du niveau d’informations spécifié.

Syntaxe

BOOL QueryServiceStatusEx(
  [in]            SC_HANDLE      hService,
  [in]            SC_STATUS_TYPE InfoLevel,
  [out, optional] LPBYTE         lpBuffer,
  [in]            DWORD          cbBufSize,
  [out]           LPDWORD        pcbBytesNeeded
);

Paramètres

[in] hService

Handle pour le service. Ce handle est retourné par la fonction CreateService ou OpenService et doit avoir le droit d’accès SERVICE_QUERY_STATUS. Pour plus d’informations, consultez Sécurité du service et droits d’accès.

[in] InfoLevel

Attributs de service à retourner. Utilisez SC_STATUS_PROCESS_INFO pour récupérer les informations de status du service. Le paramètre lpBuffer est un pointeur vers une structure SERVICE_STATUS_PROCESS .

Actuellement, aucun autre niveau d’information n’est défini.

[out, optional] lpBuffer

Pointeur vers la mémoire tampon qui reçoit les informations status. Le format de ces données dépend de la valeur du paramètre InfoLevel .

La taille maximale de ce tableau est de 8 Ko octets. Pour déterminer la taille requise, spécifiez NULL pour ce paramètre et 0 pour le paramètre cbBufSize . La fonction échoue et GetLastError retourne ERROR_INSUFFICIENT_BUFFER. Le paramètre pcbBytesNeeded reçoit la taille requise.

[in] cbBufSize

Taille de la mémoire tampon pointée vers par le paramètre lpBuffer , en octets.

[out] pcbBytesNeeded

Pointeur vers une variable qui reçoit le nombre d’octets nécessaires pour stocker toutes les informations status, si la fonction échoue avec ERROR_INSUFFICIENT_BUFFER.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Les erreurs suivantes peuvent être retournées.

Code de retour	Description
ERROR_INVALID_HANDLE	Le handle n'est pas valide.
ERROR_ACCESS_DENIED	Le handle n’a pas le droit d’accès SERVICE_QUERY_STATUS.
ERROR_INSUFFICIENT_BUFFER	La mémoire tampon est trop petite pour la structure SERVICE_STATUS_PROCESS . Rien n’a été écrit dans la structure.
ERROR_INVALID_PARAMETER	Le membre cbSize de SERVICE_STATUS_PROCESS n’est pas valide.
ERROR_INVALID_LEVEL	Le paramètre InfoLevel contient une valeur non prise en charge.
ERROR_SHUTDOWN_IN_PROGRESS	Le système s’arrête ; cette fonction ne peut pas être appelée.

Remarques

La fonction QueryServiceStatusEx retourne les informations de status de service les plus récentes signalées au gestionnaire de contrôle de service. Si le service vient de modifier son status, il n’a peut-être pas encore mis à jour le gestionnaire de contrôle de service.

L’identificateur de processus retourné dans la structure SERVICE_STATUS_PROCESS est valide, à condition que l’état du service soit SERVICE_RUNNING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED ou SERVICE_CONTINUE_PENDING. Toutefois, si le service est dans un état SERVICE_START_PENDING ou SERVICE_STOP_PENDING, l’identificateur de processus peut ne pas être valide et, si le service est dans l’état SERVICE_STOPPED, il n’est jamais valide.

Exemples

Pour obtenir un exemple, consultez Démarrage d’un service ou Arrêt d’un service.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winsvc.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll

Voir aussi

SERVICE_STATUS_PROCESS

Fonctions de service

Démarrage du service

Partager via