StartServiceCtrlDispatcherA, fonction (winsvc.h)
Connecte le thread principal d’un processus de service au gestionnaire de contrôle de service, ce qui entraîne le thread comme 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 pouvant 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 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.
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.
| Retourner le code | Description |
|---|---|
|
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 sera exécuté en tant qu’application console à des fins de débogage, structurez-le de sorte que le code spécifique au service n’est pas appelé lorsque cette erreur est retournée. |
|
La table de répartition spécifiée contient des entrées qui ne sont pas au format approprié. |
|
Le processus a déjà appelé StartServiceCtrlDispatcher. Chaque processus peut appeler StartServiceCtrlDispatcher 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 thread principal 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 principal du processus de service. Le thread principal agit comme 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 au démarrage d’un nouveau service.
Le paramètre lpServiceTable contient une entrée pour chaque service pouvant s’exécuter dans le processus appelant. 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 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 principal 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 que l’initialisation à l’échelle du processus doit être effectuée avant que n’importe quelle fonction ServiceMain soit appelée, le thread principal 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 principal 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 principales de service individuelles.
Les services ne doivent pas tenter d’afficher directement une interface utilisateur. Pour plus d’informations, consultez interactive Services.
Exemples
Pour obtenir un exemple, consultez Écriture de la fonction principale d’un programme de service.
Note
L’en-tête winsvc.h définit StartServiceCtrlDispatcher 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 |