Fonction CreateServiceW (winsvc.h)
Crée un objet de service et l’ajoute à la base de données du gestionnaire de contrôle de service spécifiée.
Syntaxe
SC_HANDLE CreateServiceW(
[in] SC_HANDLE hSCManager,
[in] LPCWSTR lpServiceName,
[in, optional] LPCWSTR lpDisplayName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwServiceType,
[in] DWORD dwStartType,
[in] DWORD dwErrorControl,
[in, optional] LPCWSTR lpBinaryPathName,
[in, optional] LPCWSTR lpLoadOrderGroup,
[out, optional] LPDWORD lpdwTagId,
[in, optional] LPCWSTR lpDependencies,
[in, optional] LPCWSTR lpServiceStartName,
[in, optional] LPCWSTR lpPassword
);
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 avoir le droit d’accès SC_MANAGER_CREATE_SERVICE . Pour plus d’informations, consultez Sécurité du service et droits d’accès.
[in] lpServiceName
Nom du service à installer. La longueur de chaîne maximale est de 256 caractères. La base de données du gestionnaire de contrôle de service conserve la casse des caractères, mais les comparaisons de noms de service ne respectent toujours pas la casse. Barre oblique (/) et barre oblique inverse (\) ne sont pas des caractères de nom de service valides.
[in, optional] lpDisplayName
Nom complet à utiliser par les programmes d’interface utilisateur pour identifier le service. Cette chaîne a une longueur maximale de 256 caractères. Le nom est conservé à la casse dans le gestionnaire de contrôle de service. Les comparaisons de noms d’affichage ne respectent toujours pas la casse.
[in] dwDesiredAccess
Accès au service. Avant d’accorder l’accès demandé, le système vérifie le jeton d’accès du processus appelant. Pour obtenir la liste des valeurs, consultez Sécurité des services et droits d’accès.
[in] dwServiceType
Type de service. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Réservé. |
|
Service de pilote de système de fichiers. |
|
Service de pilote. |
|
Réservé. |
|
Service qui s’exécute dans son propre processus. |
|
Service qui partage un processus avec un ou plusieurs autres services. Pour plus d’informations, consultez Programmes de service. |
Si vous spécifiez SERVICE_WIN32_OWN_PROCESS ou SERVICE_WIN32_SHARE_PROCESS, et que le service s’exécute dans le contexte du compte LocalSystem, vous pouvez également spécifier la valeur suivante.
| Valeur | Signification |
|---|---|
|
Le service peut interagir avec le bureau.
Pour plus d’informations, consultez Services interactifs. |
[in] dwStartType
Options de démarrage du service. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Service démarré automatiquement par le gestionnaire de contrôle de service lors du démarrage du système. Pour plus d’informations, consultez Démarrage automatique des services. |
|
Un pilote de périphérique démarré par le chargeur système. Cette valeur est uniquement valide pour les services de pilote. |
|
Service démarré par le gestionnaire de contrôle de service lorsqu’un processus appelle la fonction StartService . Pour plus d’informations, consultez Démarrage des services à la demande. |
|
Service qui ne peut pas être démarré. Les tentatives de démarrage du service entraînent le code d’erreur ERROR_SERVICE_DISABLED. |
|
Un pilote de périphérique démarré par la fonction IoInitSystem . Cette valeur est uniquement valide pour les services de pilote. |
[in] dwErrorControl
Gravité de l’erreur et action entreprise si ce service ne parvient pas à démarrer. Ce paramètre peut prendre les valeurs suivantes.
[in, optional] lpBinaryPathName
Chemin d’accès complet au fichier binaire de service. Si le chemin contient un espace, il doit être entre guillemets pour qu’il soit correctement interprété. Par exemple, « d :\my share\myservice.exe » doit être spécifié comme « "d :\my share\myservice.exe" ».
Le chemin d’accès peut également inclure des arguments pour un service de démarrage automatique. Par exemple, « d:\myshare\myservice.exe arg1 arg2 ». Ces arguments sont passés au point d’entrée du service (généralement la fonction main).
Si vous spécifiez un chemin d’accès sur un autre ordinateur, le partage doit être accessible par le compte d’ordinateur de l’ordinateur local, car il s’agit du contexte de sécurité utilisé dans l’appel distant. Toutefois, cette exigence permet à toutes les vulnérabilités potentielles de l’ordinateur distant d’affecter l’ordinateur local. Par conséquent, il est préférable d’utiliser un fichier local.
[in, optional] lpLoadOrderGroup
Noms du groupe d’ordre de charge dont ce service est membre. Spécifiez NULL ou une chaîne vide si le service n’appartient pas à un groupe.
Le programme de démarrage utilise des groupes d’ordre de charge pour charger des groupes de services dans un ordre spécifié par rapport aux autres groupes. La liste des groupes d’ordre de chargement se trouve dans la valeur de Registre suivante : HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
[out, optional] lpdwTagId
Pointeur vers une variable qui reçoit une valeur de balise unique dans le groupe spécifié dans le paramètre lpLoadOrderGroup . Spécifiez NULL si vous ne modifiez pas la balise existante.
Vous pouvez utiliser une balise pour classer le démarrage du service au sein d’un groupe d’ordre de charge en spécifiant un vecteur d’ordre de balise dans la valeur de Registre suivante :HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList
Les balises sont évaluées uniquement pour les services de pilotes qui ont SERVICE_BOOT_START ou SERVICE_SYSTEM_START types de démarrage.
[in, optional] lpDependencies
Pointeur vers un tableau null double de noms de services séparés par null ou de groupes d’ordre de charge que le système doit démarrer avant ce service. Spécifiez NULL ou une chaîne vide si le service n’a aucune dépendance. La dépendance à un groupe signifie que ce service peut s’exécuter si au moins un membre du groupe s’exécute après une tentative de démarrage de tous les membres du groupe.
Vous devez préfixer les noms de groupes avec SC_GROUP_IDENTIFIER afin qu’ils puissent être distingués d’un nom de service, car les services et les groupes de services partagent le même espace de noms.
[in, optional] lpServiceStartName
Nom du compte sous lequel le service doit s’exécuter. Si le type de service est SERVICE_WIN32_OWN_PROCESS, utilisez un nom de compte sous la forme DomainName\UserName. Le processus de service sera connecté en tant qu’utilisateur. Si le compte appartient au domaine intégré, vous pouvez spécifier .\UserName.
Si ce paramètre a la valeur NULL, CreateService utilise le compte LocalSystem. Si le type de service spécifie SERVICE_INTERACTIVE_PROCESS, le service doit s’exécuter dans le compte LocalSystem.
Si ce paramètre est NT AUTHORITY\LocalService, CreateService utilise le compte LocalService. Si le paramètre est NT AUTHORITY\NetworkService, CreateService utilise le compte NetworkService.
Un processus partagé peut s’exécuter comme n’importe quel utilisateur.
Si le type de service est SERVICE_KERNEL_DRIVER ou SERVICE_FILE_SYSTEM_DRIVER, le nom est le nom de l’objet de pilote que le système utilise pour charger le pilote de périphérique. Spécifiez NULL si le pilote doit utiliser un nom d’objet par défaut créé par le système d’E/S.
Un service peut être configuré pour utiliser un compte managé ou un compte virtuel. Si le service est configuré pour utiliser un compte de service managé, le nom est le nom du compte de service managé. Si le service est configuré pour utiliser un compte virtuel, spécifiez le nom NT SERVICE\ServiceName. Pour plus d’informations sur les comptes de service managés et les comptes virtuels, consultez le Guide pas à pas des comptes de service.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Les comptes de service managés et les comptes virtuels ne sont pas pris en charge tant que Windows 7 et Windows Server 2008 R2.
[in, optional] lpPassword
Mot de passe du nom de compte spécifié par le paramètre lpServiceStartName . Spécifiez une chaîne vide si le compte n’a pas de mot de passe ou si le service s’exécute dans le compte LocalService, NetworkService ou LocalSystem. Pour plus d’informations, consultez Liste des enregistrements de service.
Si le nom du compte spécifié par le paramètre lpServiceStartName est le nom d’un compte de service managé ou d’un nom de compte virtuel, le paramètre lpPassword doit avoir la valeur NULL.
Les mots de passe sont ignorés pour les services de pilotes.
Valeur retournée
Si la fonction réussit, la valeur de retour est un handle pour le service.
Si la fonction échoue, la valeur de retour est NULL. 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 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 |
|---|---|
|
Le handle de la base de données SCM n’a pas le droit d’accès SC_MANAGER_CREATE_SERVICE . |
|
Une dépendance de service circulaire a été spécifiée. |
|
Le nom d’affichage existe déjà dans la base de données du gestionnaire de contrôle de service sous la forme d’un nom de service ou d’un autre nom d’affichage. |
|
Le handle de la base de données du gestionnaire de contrôle de service spécifié n’est pas valide. |
|
Le nom de service spécifié n’est pas valide. |
|
Un paramètre spécifié n’est pas valide. |
|
Le nom de compte d’utilisateur spécifié dans le paramètre lpServiceStartName n’existe pas. |
|
Le service spécifié existe déjà dans cette base de données. |
|
Le service spécifié existe déjà dans cette base de données et a été marqué pour suppression. |
Remarques
La fonction CreateService crée un objet de service et l’installe dans la base de données du gestionnaire de contrôle de service en créant une clé portant le même nom que le service sous la clé de Registre suivante :HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
Les informations spécifiées par CreateService, ChangeServiceConfig et ChangeServiceConfig2 sont enregistrées en tant que valeurs sous cette clé. Voici des exemples de valeurs stockées pour un service.
| Valeur | Description |
|---|---|
| DependOnGroup | Groupes d’ordre de charge dont dépend ce service, comme spécifié par lpDependencies. |
| DependOnService | Services dont ce service dépend, comme spécifié par lpDependencies. |
| Description | Description spécifiée par ChangeServiceConfig2. |
| DisplayName | Nom d’affichage spécifié par lpDisplayName. |
| ErrorControl | Contrôle d’erreur spécifié par dwErrorControl. |
| FailureActions | Actions d’échec spécifiées par ChangeServiceConfig2. |
| Groupe | Groupe de classement de charge spécifié par lpLoadOrderGroup. Notez que la définition de cette valeur peut remplacer le paramètre de la valeur DependOnService . |
| Imagepath | Nom du fichier binaire, tel que spécifié par lpBinaryPathName. |
| ObjectName | Nom du compte spécifié par lpServiceStartName. |
| Start | Quand démarrer le service, comme spécifié par dwStartType. |
| Tag | Identificateur de balise spécifié par lpdwTagId. |
| Type | Type de service spécifié par dwServiceType. |
Les programmes d’installation et le service lui-même peuvent créer des sous-clés supplémentaires pour obtenir des informations spécifiques au service.
Le handle retourné est valide uniquement pour le processus qui a appelé CreateService. Il peut être fermé en appelant la fonction CloseServiceHandle .
Si vous créez des services qui partagent un processus, évitez d’appeler des fonctions avec des effets à l’échelle du processus, comme ExitProcess. En outre, ne déchargez pas votre DLL de service.
Exemples
Pour obtenir un exemple, consultez Installation d’un service.
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 |
Voir aussi
QueryServiceDynamicInformation
Guide pas à pas des comptes de service (éventuellement en anglais)