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

Article
07/16/2024

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 est inscrite dans le dossier de tâches racine et le nom de la tâche est 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.

exemple de déclencheur de temps (XML)
exemple de déclencheur d’événement (XML)
exemple de déclencheur quotidien (XML)
exemple de déclencheur d’inscription (XML)
exemple de déclencheur hebdomadaire (XML)
exemple de déclencheur d’ouverture de session (XML)
exemple de déclencheur de démarrage (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_UPDATEou 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 n’est pas autorisé à ajouter l’entrée de contrôle d’accès (ACE) autorisée 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’entraîne à s’exécuter sur l’inscription.

[in] userId

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

Remarque Si la tâche est définie en tant que tâche planificateur de tâches 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 du Planificateur de tâches 1.0 lorsque l’attribut de version de l’élément Task dans le code XML de la tâche est défini sur 1.1.

[in] password

Mot de passe de l’id utilisateur 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 vous connecter à 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 de l’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 est 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 de service local, de service local ou de service réseau est utilisé comme contexte de sécurité pour exécuter la tâche.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD 6	Tout d’abord, utilisez 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 certains utilisateurs et groupes d’accès à une tâche.

Remarque Si le compte système local n’a pas 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.

Passez une référence à un pointeur d’interface NULLIRegisteredTa sk. Le référencement d’un pointeur NULL nonpeut provoquer une fuite de mémoire, car le pointeur sera remplacé.

Valeur de retour

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

Retourner le code/la valeur	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 n’a pas suffisamment de mémoire pour terminer l’opération ou l’utilisateur ou 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 pas tous les déclencheurs spécifiés démarrent 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 que la tâche a un type d’ouverture de session interactif. Pour définir le type d’ouverture de session de tâche de manière interactive, spécifiez TASK_LOGON_INTERACTIVE_TOKEN ou TASK_LOGON_GROUP dans la propriété LogonType du principal de 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 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écute pas.

La transmission des valeurs TASK_VALIDATE_ONLY et TASK_IGNORE_REGISTRATION_TRIGGERS aux indicateurs est 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 une erreur 0x8000ffff lorsque la tâche est inscrite.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	taskschd.h
bibliothèque	Taskschd.lib
DLL	Taskschd.dll

Voir aussi

IRegisteredTask

ITaskFolder

planificateur de tâches

Partager via