ITaskFolder::RegisterTaskDefinition method (taskschd.h)

Registers (creates) a task in a specified location using the ITaskDefinition interface to define a task.

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

Parameters

[in] path

The name of the task. If this value is NULL, the task will be registered in the root task folder and the task name will be a GUID value created by the Task Scheduler service.

A task name cannot begin or end with a space character. The '.' character cannot be used to specify the current task folder and the '..' characters cannot be used to specify the parent task folder in the path.

[in] pDefinition

The definition of the registered task.

[in] flags

A TASK_CREATION constant.

Value	Meaning
TASK_VALIDATE_ONLY 0x1	Task Scheduler verifies the syntax of the XML that describes the task, but does not register the task. This constant cannot be combined with the TASK_CREATE, TASK_UPDATE, or TASK_CREATE_OR_UPDATE values.
TASK_CREATE 0x2	Task Scheduler registers the task as a new task.
TASK_UPDATE 0x4	Task Scheduler registers the task as an updated version of an existing task. When a task with a registration trigger is updated, the task will execute after the update occurs.
TASK_CREATE_OR_UPDATE 0x6	Task Scheduler either registers the task as a new task or as an updated version if the task already exists. Equivalent to TASK_CREATE | TASK_UPDATE.
TASK_DISABLE 0x8	Task Scheduler disables the existing task.
TASK_DONT_ADD_PRINCIPAL_ACE 0x10	Task Scheduler is prevented from adding the allow access-control entry (ACE) for the context principal. When the ITaskFolder::RegisterTaskDefinition function is called with this flag to update a task, the Task Scheduler service does not add the ACE for the new context principal and does not remove the ACE from the old context principal.
TASK_IGNORE_REGISTRATION_TRIGGERS 0x20	The Task Scheduler creates the task, but ignores the registration triggers in the task. By ignoring the registration triggers, the task will not execute when it is registered unless a time-based trigger causes it to execute on registration.

[in] userId

The user credentials used to register the task. If present, these credentials take priority over the credentials specified in the task definition object pointed to by the pDefinition parameter.

Note  If the task is defined as a Task Scheduler 1.0 task, then do not use a group name (rather than a specific user name) in this userId parameter. A task is defined as a Task Scheduler 1.0 task when the Compatibility property is set to TASK_COMPATIBILITY_V1 in the task's settings.

 

[in] password

The password for the userId used to register the task. When the TASK_LOGON_SERVICE_ACCOUNT logon type is used, the password must be an empty VARIANT value such as VT_NULL or VT_EMPTY.

[in] logonType

Defines what logon technique is used to run the registered task.

Value	Meaning
TASK_LOGON_NONE 0	The logon method is not specified. Used for non-NT credentials.
TASK_LOGON_PASSWORD 1	Use a password for logging on the user. The password must be supplied at registration time.
TASK_LOGON_S4U 2	Use an existing interactive token to run a task. The user must log on using a service for user (S4U) logon. When an S4U logon is used, no password is stored by the system and there is no access to either the network or to encrypted files.
TASK_LOGON_INTERACTIVE_TOKEN 3	User must already be logged on. The task will be run only in an existing interactive session.
TASK_LOGON_GROUP 4	Group activation. The groupId field specifies the group.
TASK_LOGON_SERVICE_ACCOUNT 5	Indicates that a Local System, Local Service, or Network Service account is being used as a security context to run the task.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD 6	First use the interactive token. If the user is not logged on (no interactive token is available), then the password is used. The password must be specified when a task is registered. This flag is not recommended for new tasks because it is less reliable than TASK_LOGON_PASSWORD.

[in, optional] sddl

The security descriptor that is associated with the registered task. You can specify the access control list (ACL) in the security descriptor for a task in order to allow or deny certain users and groups access to a task.

Note   If the Local System account is denied access to a task, then the Task Scheduler service can produce unexpected results.

 

[out] ppTask

An IRegisteredTask interface that represents the new task.

Pass in a reference to a NULL IRegisteredTask interface pointer. Referencing a non-NULL pointer can cause a memory leak because the pointer will be overwritten.

Return value

This method can return one of these values.

Return code/value	Description
S_OK 0x0	The operation completed successfully.
E_ACCESS_DENIED 0x80070005	Access is denied to connect to the Task Scheduler service.
E_OUTOFMEMORY 0x8007000e	The application does not have enough memory to complete the operation or the user or password has at least one null and one non-null value.
SCHED_S_BATCH_LOGON_PROBLEM 0x0004131C	The task is registered, but may fail to start. Batch logon privilege needs to be enabled for the task principal.
SCHED_S_SOME_TRIGGERS_FAILED 0x0004131B	The task is registered, but not all specified triggers will start the task.

Remarks

For a task, that contains a message box action, the message box will be displayed if the task is activated and the task has an interactive logon type. To set the task logon type to be interactive, specify TASK_LOGON_INTERACTIVE_TOKEN or TASK_LOGON_GROUP in the LogonType property of the task principal, or in the logonType parameter of ITaskFolder::RegisterTask or ITaskFolder::RegisterTaskDefinition.

Only a member of the Administrators group can create a task with a boot trigger.

You can successfully register a task with a group specified in the userId parameter and TASK_LOGON_INTERACTIVE_TOKEN specified in the logonType parameter of ITaskFolder::RegisterTask or ITaskFolder::RegisterTaskDefinition, but the task will not run.

Passing the TASK_VALIDATE_ONLY and TASK_IGNORE_REGISTRATION_TRIGGERS values together to the flags parameter is an invalid argument.

The ITaskFolder::RegisterTaskDefinition method returns error 80070534 when called by the System account with the user parameter equal to NULL, the password parameter equal to NULL, and the logonType parameter equal to TASK_LOGON_SERVICE_ACCOUNT.

If a task defines a network that does not exist in the NetworkSettings settings of the task, the ITaskFolder::RegisterTaskDefinition method will return error 0x8000ffff when the task is registered.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	taskschd.h
Library	Taskschd.lib
DLL	Taskschd.dll

See also

IRegisteredTask

ITaskFolder

Task Scheduler