ITaskFolder::RegisterTask-Methode (taskschd.h)

  • Artikel

Registriert (erstellt) eine neue Aufgabe im Ordner mithilfe von XML, um die Aufgabe zu definieren.

Syntax

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
);

Parameter

[in] path

Aufgabenname Wenn dieser Wert NULL ist, wird der Task im Stammaufgabenordner registriert, und der Vorgangsname ist ein GUID-Wert, der vom Taskplaner-Dienst erstellt wird.

Ein Aufgabenname kann nicht mit einem Leerzeichen beginnen oder enden. Das Zeichen "." kann nicht verwendet werden, um den aktuellen Aufgabenordner und den Wert "." anzugeben. Zeichen können nicht verwendet werden, um den übergeordneten Aufgabenordner im Pfad anzugeben.

[in] xmlText

Eine XML-formatierte Definition der Aufgabe.

Die folgenden Themen enthalten Aufgaben, die mithilfe von XML definiert wurden.

[in] flags

Eine TASK_CREATION Konstante.

Wert Bedeutung
TASK_VALIDATE_ONLY
0x1
 Der Taskplaner überprüft die Syntax des XML-Codes, der die Aufgabe beschreibt, registriert den Vorgang jedoch nicht. Diese Konstante kann nicht mit den werten TASK_CREATE, TASK_UPDATE oder TASK_CREATE_OR_UPDATE kombiniert werden.
TASK_CREATE
0x2
 Der Taskplaner registriert den Vorgang als neuen Vorgang.
TASK_UPDATE
0x4
 Der Taskplaner registriert den Vorgang als aktualisierte Version eines vorhandenen Vorgangs. Wenn eine Aufgabe mit einem Registrierungstrigger aktualisiert wird, wird der Task nach dem Update ausgeführt.
TASK_CREATE_OR_UPDATE
0x6
 Der Taskplaner registriert den Vorgang entweder als neue Aufgabe oder als aktualisierte Version, wenn der Vorgang bereits vorhanden ist. Entspricht TASK_CREATE | TASK_UPDATE.
TASK_DISABLE
0x8
 Der Taskplaner deaktiviert die vorhandene Aufgabe.
TASK_DONT_ADD_PRINCIPAL_ACE
0x10
 Der Taskplaner wird daran gehindert, den Zugriffssteuerungseintrag zulassen (ACE) für den Kontextprinzipal hinzuzufügen. Wenn die ITaskFolder::RegisterTask-Funktion mit diesem Flag aufgerufen wird, um eine Aufgabe zu aktualisieren, fügt der Aufgabenplanungsdienst den ACE für den neuen Kontextprinzipal nicht hinzu und entfernt den ACE nicht aus dem alten Kontextprinzipal.
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 Der Taskplaner erstellt die Aufgabe, ignoriert jedoch die Registrierungstrigger in der Aufgabe. Durch Ignorieren der Registrierungstrigger wird der Task nicht ausgeführt, wenn er registriert wird, es sei denn, ein zeitbasierter Trigger bewirkt, dass er bei der Registrierung ausgeführt wird.

[in] userId

Die Benutzeranmeldeinformationen, die zum Registrieren der Aufgabe verwendet werden.

Hinweis Wenn die Aufgabe als Taskplaner 1.0-Aufgabe definiert ist, verwenden Sie keinen Gruppennamen (anstelle eines bestimmten Benutzernamens) in diesem userId-Parameter. Ein Task wird als Task Scheduler 1.0-Aufgabe definiert, wenn das Versionsattribute des Task-Elements im XML-Code des Vorgangs auf 1.1 festgelegt ist.
 

[in] password

Das Kennwort für die userId, die zum Registrieren der Aufgabe verwendet wird. Wenn der TASK_LOGON_SERVICE_ACCOUNT Anmeldetyp verwendet wird, muss das Kennwort ein leerer VARIANT-Wert sein, z. B. VT_NULL oder VT_EMPTY.

[in] logonType

Ein -Wert, der definiert, welche Anmeldetechnik zum Ausführen der registrierten Aufgabe verwendet wird.

Wert Bedeutung
TASK_LOGON_NONE
0
 Die Anmeldemethode ist nicht angegeben. Wird für Nicht-NT-Anmeldeinformationen verwendet.
TASK_LOGON_PASSWORD
1
 Verwenden Sie ein Kennwort für die Anmeldung beim Benutzer. Das Kennwort muss zum Zeitpunkt der Registrierung angegeben werden.
TASK_LOGON_S4U
2
 Verwenden Sie ein vorhandenes interaktives Token, um eine Aufgabe auszuführen. Der Benutzer muss sich mit einem Dienst für die Benutzeranmeldung (S4U) anmelden. Wenn eine S4U-Anmeldung verwendet wird, wird kein Kennwort vom System gespeichert, und es gibt keinen Zugriff auf das Netzwerk oder auf verschlüsselte Dateien.
TASK_LOGON_INTERACTIVE_TOKEN
3
 Der Benutzer muss bereits angemeldet sein. Die Aufgabe wird nur in einer vorhandenen interaktiven Sitzung ausgeführt.
TASK_LOGON_GROUP
4
 Gruppenaktivierung. Das Feld groupId gibt die Gruppe an.
TASK_LOGON_SERVICE_ACCOUNT
5
 Gibt an, dass ein Konto des lokalen Systems, eines lokalen Diensts oder eines Netzwerkdiensts als Sicherheitskontext zum Ausführen der Aufgabe verwendet wird.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD
6
 Verwenden Sie zunächst das interaktive Token. Wenn der Benutzer nicht angemeldet ist (kein interaktives Token verfügbar), wird das Kennwort verwendet. Das Kennwort muss angegeben werden, wenn eine Aufgabe registriert wird. Dieses Flag wird für neue Aufgaben nicht empfohlen, da es weniger zuverlässig ist als TASK_LOGON_PASSWORD.

[in, optional] sddl

Der Sicherheitsdeskriptor, der der registrierten Aufgabe zugeordnet ist. Sie können die Zugriffssteuerungsliste (Access Control List, ACL) im Sicherheitsdeskriptor für eine Aufgabe angeben, um bestimmten Benutzern und Gruppen den Zugriff auf eine Aufgabe zu gestatten oder zu verweigern.

Hinweis Wenn dem Lokalen Systemkonto der Zugriff auf eine Aufgabe verweigert wird, kann der Aufgabenplanungsdienst unerwartete Ergebnisse erzeugen.
 

[out] ppTask

Eine IRegisteredTask-Schnittstelle , die die neue Aufgabe darstellt.

Übergeben Sie einen Verweis auf einen NULL-IRegisteredTask-Schnittstellenzeiger. Das Verweisen auf einen Zeiger ohne NULL kann zu einem Speicherverlust führen, da der Zeiger überschrieben wird.

Rückgabewert

Diese Methode kann einen dieser Werte zurückgeben.

Rückgabecode/-wert BESCHREIBUNG
S_OK
0x0
 Der Vorgang wurde erfolgreich abgeschlossen.
E_ACCESS_DENIED
0x80070005
 Der Zugriff zum Herstellen einer Verbindung mit dem Aufgabenplanungsdienst wird verweigert.
E_OUTOFMEMORY
0x8007000e
 Die Anwendung verfügt nicht über genügend Arbeitsspeicher, um den Vorgang abzuschließen, oder der Benutzer oder das Kennwort verfügt über mindestens einen NULL- und einen Ungleich-NULL-Wert.
SCHED_S_BATCH_LOGON_PROBLEM
0x0004131C
 Der Task ist registriert, kann aber möglicherweise nicht gestartet werden. Die Batch-Anmeldeberechtigung muss für den Aufgabenprinzipal aktiviert werden.
SCHED_S_SOME_TRIGGERS_FAILED
0x0004131B
 Der Task ist registriert, aber nicht alle angegebenen Trigger starten den Task.

Hinweise

Bei einer Aufgabe, die eine Meldungsfeldaktion enthält, wird das Meldungsfeld angezeigt, wenn die Aufgabe aktiviert ist und die Aufgabe über einen interaktiven Anmeldetyp verfügt. Um den Aufgabenanmeldungstyp als interaktiv festzulegen, geben Sie TASK_LOGON_INTERACTIVE_TOKEN oder TASK_LOGON_GROUP in der LogonType-Eigenschaft des Aufgabenprinzipals oder im logonType-Parameter von ITaskFolder::RegisterTask oder ITaskFolder::RegisterTaskDefinition an.

Nur ein Mitglied der Gruppe Administratoren kann eine Aufgabe mit einem Starttrigger erstellen.

Sie können eine Aufgabe erfolgreich mit einer Gruppe registrieren, die im parameter userId und TASK_LOGON_INTERACTIVE_TOKEN im logonType-Parameter von ITaskFolder::RegisterTask oder ITaskFolder::RegisterTaskDefinition angegeben ist, aber der Task wird nicht ausgeführt.

Das gemeinsame Übergeben der werte TASK_VALIDATE_ONLY und TASK_IGNORE_REGISTRATION_TRIGGERS an den flags-Parameter ist ein ungültiges Argument.

Wenn ein Task ein Netzwerk definiert, das in den NetworkSettings-Einstellungen der Aufgabe nicht vorhanden ist, gibt die ITaskFolder::RegisterTask-Methode beim Registrieren der Aufgabe einen Fehler 0x8000ffff zurück.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile taskschd.h
Bibliothek Taskschd.lib
DLL Taskschd.dll

Weitere Informationen

IRegisteredTask

ITaskFolder

Aufgabenplanung