Fonction StartServiceCtrlDispatcherA (winsvc.h)

Article
03/04/2024

Connecte le thread main d’un processus de service au gestionnaire de contrôle de service, ce qui fait que le thread est le thread de répartiteur de contrôle de service pour le processus appelant.

Syntaxe

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);

Paramètres

[in] lpServiceStartTable

Pointeur vers un tableau de structures SERVICE_TABLE_ENTRY contenant une entrée pour chaque service qui peut s’exécuter dans le processus appelant. Les membres de la dernière entrée de la table doivent avoir des valeurs NULL pour désigner la fin de la table.

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.

Le code d’erreur suivant peut être défini 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.

Code de retour	Description
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT	Cette erreur est retournée si le programme est exécuté en tant qu’application console plutôt qu’en tant que service. Si le programme est exécuté en tant qu’application console à des fins de débogage, structurez-le de telle sorte que le code spécifique au service ne soit pas appelé lorsque cette erreur est retournée.
ERROR_INVALID_DATA	La table de répartition spécifiée contient des entrées qui ne sont pas au format approprié.
ERROR_SERVICE_ALREADY_RUNNING	Le processus a déjà appelé StartServiceCtrlDispatcher. Chaque processus ne peut appeler StartServiceCtrlDispatcher qu’une seule fois.

Remarques

Lorsque le gestionnaire de contrôle de service démarre un processus de service, il attend que le processus appelle la fonction StartServiceCtrlDispatcher . Le main thread d’un processus de service doit effectuer cet appel dès que possible après son démarrage (dans les 30 secondes). Si StartServiceCtrlDispatcher réussit, il connecte le thread appelant au gestionnaire de contrôle de service et ne retourne pas tant que tous les services en cours d’exécution dans le processus n’ont pas entré l’état SERVICE_STOPPED. Le gestionnaire de contrôle de service utilise cette connexion pour envoyer des demandes de contrôle et de démarrage de service au thread main du processus de service. Le thread main fait office de répartiteur en appelant la fonction HandlerEx appropriée pour gérer les demandes de contrôle ou en créant un thread pour exécuter la fonction ServiceMain appropriée lorsqu’un nouveau service est démarré.

Le paramètre lpServiceTable contient une entrée pour chaque service qui peut s’exécuter dans le processus d’appel. Chaque entrée spécifie la fonction ServiceMain pour ce service. Pour SERVICE_WIN32_SHARE_PROCESS services, chaque entrée doit contenir le nom d’un service. Ce nom est le nom du service qui a été spécifié par la fonction CreateService lors de l’installation du service. Pour SERVICE_WIN32_OWN_PROCESS services, le nom du service dans l’entrée de table est ignoré.

Si un service s’exécute dans son propre processus, le thread main du processus de service doit immédiatement appeler StartServiceCtrlDispatcher. Toutes les tâches d’initialisation sont effectuées dans la fonction ServiceMain du service au démarrage du service.

Si plusieurs services partagent un processus et qu’une initialisation courante à l’échelle du processus doit être effectuée avant qu’une fonction ServiceMain soit appelée, le thread main peut effectuer le travail avant d’appeler StartServiceCtrlDispatcher, tant qu’il faut moins de 30 secondes. Sinon, un autre thread doit être créé pour effectuer l’initialisation à l’échelle du processus, tandis que le thread main appelle StartServiceCtrlDispatcher et devient le répartiteur de contrôle de service. Toute initialisation spécifique au service doit toujours être effectuée dans les fonctions main de service individuelles.

Les services ne doivent pas essayer d’afficher une interface utilisateur directement. Pour plus d’informations, consultez Services interactifs.

Exemples

Pour obtenir un exemple, consultez Écriture de la fonction principale d’un programme de service.

Notes

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

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