StartServiceW, fonction (winsvc.h)

Article
08/27/2023

Démarre un service.

Syntaxe

BOOL StartServiceW(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwNumServiceArgs,
  [in, optional] LPCWSTR   *lpServiceArgVectors
);

Paramètres

[in] hService

Handle pour 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é du service et droits d’accès.

[in] dwNumServiceArgs

Nombre de chaînes dans le tableau lpServiceArgVectors . 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’y a pas d’arguments, ce paramètre peut être NULL. Sinon, le premier argument (lpServiceArgVectors[0]) est le nom du service, suivi des arguments supplémentaires (lpServiceArgVectors[1] via lpServiceArgVectors[dwNumServiceArgs-1]).

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

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 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.

Code de retour	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	Le fichier binaire de service est introuvable.
ERROR_SERVICE_ALREADY_RUNNING	Une instance du service est 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 erreur d'ouverture de session. Cette erreur se produit si le service est configuré pour s’exécuter sous un compte qui n’a pas le 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 du 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ôle.

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 des services (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 status à partir du nouveau service, car cela peut prendre un certain temps. Au lieu de cela, elle retourne lorsque le SCM reçoit une notification du répartiteur de contrôle de service indiquant que le thread ServiceMain pour ce service a été créé avec succès.

Le SCM définit les valeurs de status par défaut suivantes avant de retourner à partir de StartService :

L’état actuel du service est défini sur SERVICE_START_PENDING.
Contrôles acceptés est défini sur none (zéro).
La valeur CheckPoint est définie sur zéro.
L’heure WaitHint est définie sur 2 secondes.

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

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

Comme avec ControlService, StartService se bloque pendant 30 secondes si un service est occupé à gérer un code de contrôle. Si le service occupé n’est toujours pas retourné par sa fonction de gestionnaire à l’expiration du délai d’expiration, StartService échoue avec ERROR_SERVICE_REQUEST_TIMEOUT. En effet, le SCM ne traite qu’une seule notification de contrôle de service à la fois.

Exemples

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

Notes

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