StartServiceA, fonction (winsvc.h)

Article
11/20/2024

Démarre un service.

Syntaxe

BOOL StartServiceA(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwNumServiceArgs,
  [in, optional] LPCSTR    *lpServiceArgVectors
);

Paramètres

[in] hService

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

[in] dwNumServiceArgs

Nombre de chaînes dans le tableau lpServiceArgVector s. Si lpServiceArgVectors a la valeur NULL, ce paramètre peut être égal à zéro.

[in, optional] lpServiceArgVectors

Chaînes terminées par null à passer à la fonction ServiceMain pour le service en tant qu’arguments. S’il n’existe aucun argument, ce paramètre peut être NULL. Sinon, le premier argument (lpServiceArgVectors[0]) est le nom du service, suivi de tous les arguments supplémentaires (lpServiceArgVectors[1] via lpServiceArgVectors[dwNumServiceArgs-1]).

Les services de pilote ne reçoivent pas ces arguments.

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 peuvent être définies 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 SERVICE_START.
ERROR_INVALID_HANDLE	Le handle n’est pas valide.
ERROR_PATH_NOT_FOUND	Impossible de trouver le fichier binaire du service.
ERROR_SERVICE_ALREADY_RUNNING	Une instance du service est déjà en cours d’exécution.
ERROR_SERVICE_DATABASE_LOCKED	La base de données est verrouillée.
ERROR_SERVICE_DEPENDENCY_DELETED	Le service dépend d’un service qui n’existe pas ou qui a été marqué pour suppression.
ERROR_SERVICE_DEPENDENCY_FAIL	Le service dépend d’un autre service qui n’a pas pu démarrer.
ERROR_SERVICE_DISABLED	Le service a été désactivé.
ERROR_SERVICE_LOGON_FAILED	Le service n’a pas démarré en raison d’une défaillance d’ouverture de session. Cette erreur se produit si le service est configuré pour s’exécuter sous un compte qui ne dispose pas du droit « Se connecter en tant que service ».
ERROR_SERVICE_MARKED_FOR_DELETE	Le service a été marqué pour suppression.
ERROR_SERVICE_NO_THREAD	Impossible de créer un thread pour le service.
ERROR_SERVICE_REQUEST_TIMEOUT	Le processus pour le service a été démarré, mais il n’a pas appelé StartServiceCtrlDispatcher, ou le thread qui a appelé StartServiceCtrlDispatcher peut être bloqué dans une fonction de gestionnaire de contrôles.

Remarques

Lorsqu’un service de pilote est démarré, la fonction StartService ne retourne pas tant que le pilote de périphérique n’a pas terminé l’initialisation.

Lorsqu’un service est démarré, le Gestionnaire de contrôle de service (SCM) génère le processus de service, si nécessaire. Si le service spécifié partage un processus avec d’autres services, le processus requis peut déjà exister. La fonction StartService n’attend pas la première mise à jour d’état du nouveau service, car elle peut prendre un certain temps. Au lieu de cela, elle retourne lorsque le SCM reçoit la notification du répartiteur de contrôle de service que le thread ServiceMain pour ce service a été créé avec succès.

Le SCM définit les valeurs d’état par défaut suivantes avant de revenir de StartService:

L’état actuel du service est défini sur SERVICE_START_PENDING.
Les contrôles acceptés sont définis sur aucun (zéro).
La valeur CheckPoint est définie sur zéro.
Le temps WaitHint est défini sur 2 secondes.

Le processus appelant peut déterminer si le nouveau service a terminé son initialisation en appelant la fonction QueryServiceStatus régulièrement pour interroger l’état du service.

Un service ne peut pas appeler StartService pendant l’initialisation. La raison est que le SCM verrouille la base de données de contrôle de service pendant l’initialisation. Par conséquent, un appel à StartService bloquera. Une fois le service signalé au SCM qu’il a démarré, il peut appeler StartService.

Comme avec ControlService, StartService bloquera pendant 30 secondes si un service est occupé à gérer un code de contrôle. Si le service occupé n’a toujours pas retourné de sa fonction de gestionnaire lorsque le délai d’expiration expire, StartService échoue avec ERROR_SERVICE_REQUEST_TIMEOUT. Cela est dû au fait que le SCM traite une seule notification de contrôle de service à la fois.

Exemples

Pour obtenir un exemple, consultez Démarrage d’un service.

Note

L’en-tête winsvc.h définit StartService 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