ITaskFolder::RegisterTaskDefinition-Methode (taskschd.h)

  • Artikel

Registriert (erstellt) eine Aufgabe an einer angegebenen Position mithilfe der ITaskDefinition Schnittstelle zum Definieren einer Aufgabe.

Syntax

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

Parameter

[in] path

Der Name des Vorgangs. Wenn dieser Wert NULL-ist, wird die Aufgabe im Stammaufgabenordner registriert, und der Vorgangsname ist ein GUID-Wert, der vom Taskplanerdienst erstellt wird.

Ein Vorgangsname kann nicht mit einem Leerzeichen beginnen oder enden. Das Zeichen '.' kann nicht zum Angeben des aktuellen Aufgabenordners und des '.' verwendet werden. Zeichen können nicht verwendet werden, um den übergeordneten Aufgabenordner im Pfad anzugeben.

[in] pDefinition

Die Definition der registrierten Aufgabe.

[in] flags

Eine TASK_CREATION Konstante.

Wert Bedeutung
TASK_VALIDATE_ONLY
0x1
 Der Taskplaner überprüft die Syntax des XML-Codes, der den Vorgang beschreibt, registriert den Vorgang jedoch nicht. Diese Konstante kann nicht mit den Werten TASK_CREATE, TASK_UPDATEoder TASK_CREATE_OR_UPDATE kombiniert werden.
TASK_CREATE
0x2
 Der Vorgangsplaner 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 die Aufgabe nach dem Update ausgeführt.
TASK_CREATE_OR_UPDATE
0x6
 Der Taskplaner registriert den Vorgang entweder als neuen Vorgang oder als aktualisierte Version, wenn der Vorgang bereits vorhanden ist. Entspricht TASK_CREATE | TASK_UPDATE.
TASK_DISABLE
0x8
 Der Taskplaner deaktiviert den vorhandenen Vorgang.
TASK_DONT_ADD_PRINCIPAL_ACE
0x10
 Der Taskplaner wird daran gehindert, den Zugriffssteuerungseintrag (Access Control Entry, ACE) für den Kontextprinzipal hinzuzufügen. Wenn die ITaskFolder::RegisterTaskDefinition-Funktion aufgerufen wird, um einen Vorgang zu aktualisieren, fügt der Aufgabenplanerdienst die ACE für den neuen Kontextprinzipal nicht hinzu und entfernt die ACE nicht aus dem alten Kontextprinzipal.
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 Der Taskplaner erstellt den Vorgang, ignoriert jedoch die Registrierungstrigger im Vorgang. Durch Ignorieren der Registrierungstrigger wird die Aufgabe nicht ausgeführt, wenn sie registriert wird, es sei denn, ein zeitbasierter Trigger bewirkt, dass sie bei der Registrierung ausgeführt wird.

[in] userId

Die Zum Registrieren der Aufgabe verwendeten Benutzeranmeldeinformationen. Wenn vorhanden, haben diese Anmeldeinformationen Vorrang vor den im Aufgabendefinitionsobjekt angegebenen Anmeldeinformationen, auf die durch den pDefinition Parameter verwiesen wird.

Hinweis Wenn der Vorgang als Task Scheduler 1.0-Vorgang definiert ist, verwenden Sie keinen Gruppennamen (anstelle eines bestimmten Benutzernamens) in diesem UserId-Parameter. Ein Vorgang wird als Task Scheduler 1.0-Vorgang definiert, wenn die Compatibility-Eigenschaft in den Einstellungen des Vorgangs auf TASK_COMPATIBILITY_V1 festgelegt ist.
 

[in] password

Das Kennwort für die userId, die zum Registrieren der Aufgabe verwendet wurde. Wenn der TASK_LOGON_SERVICE_ACCOUNT Anmeldetyp verwendet wird, muss das Kennwort ein leerer VARIANT Wert wie VT_NULL oder VT_EMPTYsein.

[in] logonType

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 zur Registrierungszeit 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 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 groupId- Feld gibt die Gruppe an.
TASK_LOGON_SERVICE_ACCOUNT
5
 Gibt an, dass ein lokales System-, lokales Dienst- oder Netzwerkdienstkonto als Sicherheitskontext zum Ausführen der Aufgabe verwendet wird.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD
6
 Verwenden Sie zuerst 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 Kennzeichen wird für neue Vorgänge 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) in der Sicherheitsbeschreibung für eine Aufgabe angeben, um bestimmte Benutzer und Gruppen den Zugriff auf eine Aufgabe zuzulassen oder zu verweigern.

Hinweis Wenn das lokale Systemkonto den Zugriff auf eine Aufgabe verweigert, kann der Taskplanerdienst unerwartete Ergebnisse erzielen.
 

[out] ppTask

Eine IRegisteredTask- Schnittstelle, die die neue Aufgabe darstellt.

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

Rückgabewert

Diese Methode kann einen dieser Werte zurückgeben.

Zurückgeben von Code/Wert Beschreibung
S_OK
0x0
 Der Vorgang wurde erfolgreich abgeschlossen.
E_ACCESS_DENIED
0x80070005
 Der Zugriff wird verweigert, um eine Verbindung mit dem Aufgabenplanerdienst herzustellen.
E_OUTOFMEMORY
0x8007000e
 Die Anwendung verfügt nicht über genügend Arbeitsspeicher, um den Vorgang abzuschließen, oder der Benutzer hat oder Kennwort mindestens einen NULL- und einen nicht-Null- Wert.
SCHED_S_BATCH_LOGON_PROBLEM
0x0004131C
 Die Aufgabe ist registriert, kann jedoch nicht gestartet werden. Batchanmeldungsberechtigungen müssen für den Aufgabenprinzipal aktiviert werden.
SCHED_S_SOME_TRIGGERS_FAILED
0x0004131B
 Der Vorgang wird registriert, aber nicht alle angegebenen Trigger starten den Vorgang.

Bemerkungen

Bei einer Aufgabe, die eine Meldungsfeldaktion enthält, wird das Meldungsfeld angezeigt, wenn die Aufgabe aktiviert ist und die Aufgabe einen interaktiven Anmeldetyp aufweist. Wenn Sie den Aufgabenanmeldungstyp als interaktiv festlegen möchten, 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::RegisterTaskDefinitionan.

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

Sie können eine Aufgabe erfolgreich bei einer gruppe registrieren, die im parameter userId angegeben ist und TASK_LOGON_INTERACTIVE_TOKEN im logonType Parameter von ITaskFolder::RegisterTask oder ITaskFolder::RegisterTaskDefinitionangegeben, aber die Aufgabe wird nicht ausgeführt.

Das Übergeben der werte TASK_VALIDATE_ONLY und TASK_IGNORE_REGISTRATION_TRIGGERS an die Flags Parameter ist ein ungültiges Argument.

Die ITaskFolder::RegisterTaskDefinition-Methode gibt fehler 80070534 zurück, wenn vom Systemkonto mit dem parameter Benutzer dem Parameter NULL NULL, dem Kennwort Parameter gleich NULL, und der parameter logonType gleich TASK_LOGON_SERVICE_ACCOUNT.

Wenn eine Aufgabe ein Netzwerk definiert, das in den NetworkSettings- Einstellungen des Vorgangs nicht vorhanden ist, gibt die ITaskFolder::RegisterTaskDefinition--Methode fehler 0x8000ffff zurück, wenn die Aufgabe registriert ist.

Anforderungen

Anforderung Wert
mindestens unterstützte Client- Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server- Windows Server 2008 [Nur Desktop-Apps]
Zielplattform- Fenster
Header- taskschd.h
Library Taskschd.lib
DLL- Taskschd.dll

Siehe auch

IRegisteredTask-

ITaskFolder-

Aufgabenplaner-