ITaskFolder ::RegisterTask, méthode (taskschd.h)

  • Article

Inscrit (crée) une tâche dans le dossier à l’aide de XML pour définir la tâche.

Syntaxe

HRESULT RegisterTask(
  [in]           BSTR            path,
  [in]           BSTR            xmlText,
  [in]           LONG            flags,
  [in]           VARIANT         userId,
  [in]           VARIANT         password,
  [in]           TASK_LOGON_TYPE logonType,
  [in, optional] VARIANT         sddl,
  [out]          IRegisteredTask **ppTask
);

Paramètres

[in] path

Nom de la tâche. Si cette valeur est NULL, la tâche sera inscrite dans le dossier de tâches racine et le nom de la tâche sera une valeur GUID créée par le service Planificateur de tâches.

Un nom de tâche ne peut pas commencer ou se terminer par un caractère d’espace. Le caractère « . » ne peut pas être utilisé pour spécifier le dossier de tâches actuel et le « .. » les caractères ne peuvent pas être utilisés pour spécifier le dossier de tâches parent dans le chemin d’accès.

[in] xmlText

Définition au format XML de la tâche.

Les rubriques suivantes contiennent des tâches définies à l’aide de XML.

[in] flags

Constante TASK_CREATION .

Valeur Signification
TASK_VALIDATE_ONLY
0x1
 Le planificateur de tâches vérifie la syntaxe du code XML qui décrit la tâche, mais n’inscrit pas la tâche. Cette constante ne peut pas être combinée avec les valeurs TASK_CREATE, TASK_UPDATE ou TASK_CREATE_OR_UPDATE .
TASK_CREATE
0x2
 Le planificateur de tâches inscrit la tâche en tant que nouvelle tâche.
TASK_UPDATE
0x4
 Le planificateur de tâches inscrit la tâche en tant que version mise à jour d’une tâche existante. Lorsqu’une tâche avec un déclencheur d’inscription est mise à jour, la tâche s’exécute une fois la mise à jour effectuée.
TASK_CREATE_OR_UPDATE
0x6
 Le planificateur de tâches inscrit la tâche en tant que nouvelle tâche ou en tant que version mise à jour si la tâche existe déjà. Équivalent à TASK_CREATE | TASK_UPDATE.
TASK_DISABLE
0x8
 Le planificateur de tâches désactive la tâche existante.
TASK_DONT_ADD_PRINCIPAL_ACE
0x10
 Le planificateur de tâches ne peut pas ajouter l’entrée de contrôle d’accès (ACE) d’autorisation pour le principal de contexte. Lorsque la fonction ITaskFolder ::RegisterTask est appelée avec cet indicateur pour mettre à jour une tâche, le service Planificateur de tâches n’ajoute pas l’ACE pour le nouveau principal de contexte et ne supprime pas l’ACE de l’ancien principal de contexte.
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 Le planificateur de tâches crée la tâche, mais ignore les déclencheurs d’inscription dans la tâche. En ignorant les déclencheurs d’inscription, la tâche ne s’exécute pas lorsqu’elle est inscrite, sauf si un déclencheur basé sur le temps l’oblige à s’exécuter lors de l’inscription.

[in] userId

Informations d’identification utilisateur utilisées pour inscrire la tâche.

Note Si la tâche est définie comme une tâche Task Scheduler 1.0, n’utilisez pas de nom de groupe (plutôt qu’un nom d’utilisateur spécifique) dans ce paramètre userId. Une tâche est définie en tant que tâche Planificateur de tâches 1.0 lorsque l’attribut de version de l’élément Task dans le XML de la tâche est défini sur 1.1.
 

[in] password

Mot de passe du userId utilisé pour inscrire la tâche. Lorsque le type d’ouverture de session TASK_LOGON_SERVICE_ACCOUNT est utilisé, le mot de passe doit être une valeur VARIANT vide telle que VT_NULL ou VT_EMPTY.

[in] logonType

Valeur qui définit la technique d’ouverture de session utilisée pour exécuter la tâche inscrite.

Valeur Signification
TASK_LOGON_NONE
0
 La méthode d’ouverture de session n’est pas spécifiée. Utilisé pour les informations d’identification non NT.
TASK_LOGON_PASSWORD
1
 Utilisez un mot de passe pour la journalisation sur l’utilisateur. Le mot de passe doit être fourni au moment de l’inscription.
TASK_LOGON_S4U
2
 Utilisez un jeton interactif existant pour exécuter une tâche. L’utilisateur doit se connecter à l’aide d’un service pour l’ouverture de session utilisateur (S4U). Lorsqu’une ouverture de session S4U est utilisée, aucun mot de passe n’est stocké par le système et il n’y a pas d’accès au réseau ou aux fichiers chiffrés.
TASK_LOGON_INTERACTIVE_TOKEN
3
 L’utilisateur doit déjà être connecté. La tâche sera exécutée uniquement dans une session interactive existante.
TASK_LOGON_GROUP
4
 Activation de groupe. Le champ groupId spécifie le groupe.
TASK_LOGON_SERVICE_ACCOUNT
5
 Indique qu’un compte système local, service local ou service réseau est utilisé comme contexte de sécurité pour exécuter la tâche.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD
6
 Commencez par utiliser le jeton interactif. Si l’utilisateur n’est pas connecté (aucun jeton interactif n’est disponible), le mot de passe est utilisé. Le mot de passe doit être spécifié lorsqu’une tâche est inscrite. Cet indicateur n’est pas recommandé pour les nouvelles tâches, car il est moins fiable que TASK_LOGON_PASSWORD.

[in, optional] sddl

Descripteur de sécurité associé à la tâche inscrite. Vous pouvez spécifier la liste de contrôle d’accès (ACL) dans le descripteur de sécurité d’une tâche afin d’autoriser ou de refuser l’accès à une tâche à certains utilisateurs et groupes.

Note Si le compte système local se voit refuser l’accès à une tâche, le service Planificateur de tâches peut produire des résultats inattendus.
 

[out] ppTask

Interface IRegisteredTask qui représente la nouvelle tâche.

Transmettez une référence à un pointeur d’interface NULLIRegisteredTask . Le référencement d’un pointeur non NULL peut provoquer une fuite de mémoire, car le pointeur sera remplacé.

Valeur retournée

Cette méthode peut retourner l’une de ces valeurs.

Code/valeur de retour Description
S_OK
0x0
 L’opération s’est terminée avec succès.
E_ACCESS_DENIED
0x80070005
 L’accès est refusé pour se connecter au service Planificateur de tâches.
E_OUTOFMEMORY
0x8007000e
 L’application ne dispose pas de suffisamment de mémoire pour terminer l’opération ou l’utilisateur ou le mot de passe a au moins une valeur null et une valeur non null.
SCHED_S_BATCH_LOGON_PROBLEM
0x0004131C
 La tâche est inscrite, mais peut ne pas démarrer. Le privilège d’ouverture de session batch doit être activé pour le principal de tâche.
SCHED_S_SOME_TRIGGERS_FAILED
0x0004131B
 La tâche est inscrite, mais tous les déclencheurs spécifiés ne démarrent pas la tâche.

Remarques

Pour une tâche, qui contient une action de boîte de message, la zone de message s’affiche si la tâche est activée et si la tâche a un type d’ouverture de session interactif. Pour définir le type d’ouverture de session de la tâche de manière interactive, spécifiez TASK_LOGON_INTERACTIVE_TOKEN ou TASK_LOGON_GROUP dans la propriété LogonType du principal de la tâche, ou dans le paramètre logonType de ITaskFolder ::RegisterTask ou ITaskFolder ::RegisterTaskDefinition.

Seul un membre du groupe Administrateurs peut créer une tâche avec un déclencheur de démarrage.

Vous pouvez inscrire une tâche avec succès avec un groupe spécifié dans le paramètre userId et TASK_LOGON_INTERACTIVE_TOKEN spécifié dans le paramètre logonType de ITaskFolder ::RegisterTask ou ITaskFolder ::RegisterTaskDefinition, mais la tâche ne s’exécutera pas.

Le passage des valeurs TASK_VALIDATE_ONLY et TASK_IGNORE_REGISTRATION_TRIGGERS au paramètre flags n’est pas un argument non valide.

Si une tâche définit un réseau qui n’existe pas dans les paramètres NetworkSettings de la tâche, la méthode ITaskFolder ::RegisterTask retourne l’erreur 0x8000ffff lorsque la tâche est inscrite.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête taskschd.h
Bibliothèque Taskschd.lib
DLL Taskschd.dll

Voir aussi

IRegisteredTask

ITaskFolder

Planificateur de tâches