Fonction EnumServicesStatusA (winsvc.h)

Article
11/20/2024

Énumère les services dans la base de données du gestionnaire de contrôle de service spécifiée. Le nom et l’état de chaque service sont fournis.

Cette fonction a été remplacée par la fonction EnumServicesStatusEx. Elle retourne les mêmes informations EnumServicesStatus retourne, ainsi que l’identificateur de processus et des informations supplémentaires pour le service. En outre, EnumServicesStatusEx vous permet d’énumérer les services appartenant à un groupe spécifié.

Syntaxe

BOOL EnumServicesStatusA(
  [in]                SC_HANDLE              hSCManager,
  [in]                DWORD                  dwServiceType,
  [in]                DWORD                  dwServiceState,
  [out, optional]     LPENUM_SERVICE_STATUSA lpServices,
  [in]                DWORD                  cbBufSize,
  [out]               LPDWORD                pcbBytesNeeded,
  [out]               LPDWORD                lpServicesReturned,
  [in, out, optional] LPDWORD                lpResumeHandle
);

Paramètres

[in] hSCManager

Handle de la base de données du gestionnaire de contrôle de service. Ce handle est retourné par la fonction OpenSCManager et doit disposer du droit d’accès SC_MANAGER_ENUMERATE_SERVICE. Pour plus d’informations, consultez Sécurité des services et droits d’accès.

[in] dwServiceType

Type de services à énumérer. Ce paramètre peut être une ou plusieurs des valeurs suivantes.

Valeur	Signification
SERVICE_DRIVER 0x0000000B	Services de type SERVICE_KERNEL_DRIVER et SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Services de pilotes de système de fichiers.
SERVICE_KERNEL_DRIVER 0x00000001	Services de pilotes.
SERVICE_WIN32 0x00000030	Services de type SERVICE_WIN32_OWN_PROCESS et SERVICE_WIN32_SHARE_PROCESS.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Services qui s’exécutent dans leurs propres processus.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Services qui partagent un processus avec un ou plusieurs autres services. Pour plus d’informations, consultez Programmes de service.

[in] dwServiceState

État des services à énumérer. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
SERVICE_ACTIVE 0x00000001	Énumère les services qui se trouvent dans les états suivants : SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING et SERVICE_PAUSED.
SERVICE_INACTIVE 0x00000002	Énumère les services qui sont dans l’état SERVICE_STOPPED.
SERVICE_STATE_ALL 0x00000003	Combine les états suivants : SERVICE_ACTIVE et SERVICE_INACTIVE.

[out, optional] lpServices

Pointeur vers une mémoire tampon qui contient un tableau de structures ENUM_SERVICE_STATUS qui reçoivent les informations d’état du nom et du service pour chaque service de la base de données. La mémoire tampon doit être suffisamment grande pour contenir les structures, ainsi que les chaînes auxquelles leurs membres pointent.

La taille maximale de ce tableau est de 256 000 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 de octetsoctets reçoit la taille requise.

Windows Server 2003 et Windows XP : La taille maximale de ce tableau est de 64 000 octets. Cette limite a été augmentée à compter de Windows Server 2003 avec SP1 et Windows XP avec SP2.

[in] cbBufSize

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

[out] pcbBytesNeeded

Pointeur vers une variable qui reçoit le nombre d’octets nécessaires pour retourner les entrées de service restantes, si la mémoire tampon est trop petite.

[out] lpServicesReturned

Pointeur vers une variable qui reçoit le nombre d’entrées de service retournées.

[in, out, optional] lpResumeHandle

Pointeur vers une variable qui, lors de l’entrée, spécifie le point de départ de l’énumération. Vous devez définir cette valeur sur zéro la première fois que cette fonction est appelée. En sortie, cette valeur est égale à zéro si la fonction réussit. Toutefois, si la fonction retourne zéro et que la fonction GetLastError retourne ERROR_MORE_DATA, cette valeur est utilisée pour indiquer la prochaine entrée de service à lire lorsque la fonction est appelée pour récupérer les données supplémentaires.

Valeur de retour

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’erreur étendues, appelez GetLastError.

Les codes d’erreur suivants peuvent être définis par le gestionnaire de contrôle de service. D’autres codes d’erreur peuvent être définis par les fonctions de Registre appelées par le gestionnaire de contrôle de service.

Retourner le code	Description
ERROR_ACCESS_DENIED	Le handle n’a pas le droit d’accès SC_MANAGER_ENUMERATE_SERVICE.
ERROR_INVALID_HANDLE	Le handle spécifié n’est pas valide.
ERROR_INVALID_PARAMETER	Un paramètre spécifié n’est pas valide.
ERROR_MORE_DATA	Il existe plus d’entrées de service que ce qui correspondrait à la mémoire tampon lpServices . Le nombre réel d’entrées de service écrites dans lpServices est retourné dans le paramètre lpServicesReturned. Le nombre d’octets requis pour obtenir les entrées restantes est retourné dans le paramètre octetsoctets. Les services restants peuvent être énumérés par des appels supplémentaires à EnumServicesStatus avec le paramètre lpResumeHandle indiquant le service suivant à lire.

Remarques

Note

L’en-tête winsvc.h définit EnumServicesStatus 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 XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winsvc.h (inclure Windows.h)
bibliothèque	Advapi32.lib
DLL	Advapi32.dll