ITaskFolder：：RegisterTaskDefinition 方法 (taskschd.h)

  • 项目

注册 (使用 ITaskDefinition 接口在指定位置创建) 任务来定义任务。

语法

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

参数

[in] path

任务的名称。 如果此值为 NULL，则任务将在根任务文件夹中注册，任务名称将是由任务计划程序服务创建的 GUID 值。

任务名称不能以空格字符开头或结尾。 “.”字符不能用于指定当前任务文件夹和“..”。 字符不能用于指定路径中的父任务文件夹。

[in] pDefinition

已注册任务的定义。

[in] flags

TASK_CREATION常量。

值 含义
TASK_VALIDATE_ONLY
0x1
 任务计划程序验证描述任务但不注册任务的 XML 的语法。 此常量不能与 TASK_CREATE、 TASK_UPDATE或 TASK_CREATE_OR_UPDATE 值组合使用。
TASK_CREATE
0x2
 任务计划程序将任务注册为新任务。
TASK_UPDATE
0x4
 任务计划程序将任务注册为现有任务的更新版本。 更新具有注册触发器的任务时，将在更新发生后执行该任务。
TASK_CREATE_OR_UPDATE
0x6
 任务计划程序将任务注册为新任务或更新版本（如果该任务已存在）。 等效于 TASK_CREATE |TASK_UPDATE。
TASK_DISABLE
0x8
 任务计划程序禁用现有任务。
TASK_DONT_ADD_PRINCIPAL_ACE
0x10
 阻止任务计划程序为上下文主体添加允许访问控制项 (ACE) 。 使用此标志调用 ITaskFolder：：RegisterTaskDefinition 函数以更新任务时，任务计划程序服务不会为新的上下文主体添加 ACE，也不会从旧上下文主体中删除 ACE。
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 任务计划程序创建任务，但忽略任务中的注册触发器。 通过忽略注册触发器，任务在注册时不会执行，除非基于时间的触发器导致它在注册时执行。

[in] userId

用于注册任务的用户凭据。 如果存在，这些凭据优先于 pDefinition 参数指向的任务定义对象中指定的凭据。

注意 如果任务定义为任务计划程序 1.0 任务，则不要在此 userId 参数中使用组名称 (而不是特定用户名) 。 当 Compatibility 属性设置为任务设置中的TASK_COMPATIBILITY_V1时，任务定义为任务计划程序 1.0 任务。
 

[in] password

用于注册任务的 userId 的密码。 使用TASK_LOGON_SERVICE_ACCOUNT登录类型时，密码必须为空 VARIANT 值，例如 VT_NULL 或 VT_EMPTY。

[in] logonType

定义用于运行已注册任务的登录技术。

值 含义
TASK_LOGON_NONE
0
 未指定登录方法。 用于非 NT 凭据。
TASK_LOGON_PASSWORD
1
 使用密码登录用户。 必须在注册时提供密码。
TASK_LOGON_S4U
2
 使用现有交互式令牌运行任务。 用户必须使用服务登录才能 (S4U) 登录。 使用 S4U 登录时，系统不会存储任何密码，并且无法访问网络或加密文件。
TASK_LOGON_INTERACTIVE_TOKEN
3
 用户必须已登录。 该任务将仅在现有交互式会话中运行。
TASK_LOGON_GROUP
4
 组激活。 groupId 字段指定组。
TASK_LOGON_SERVICE_ACCOUNT
5
 指示使用本地系统、本地服务或网络服务帐户作为安全上下文来运行任务。
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD
6
 首先使用交互式令牌。 如果用户未登录 () 没有可用的交互式令牌，则使用密码。 注册任务时必须指定密码。 不建议将此标志用于新任务，因为它不如TASK_LOGON_PASSWORD可靠。

[in, optional] sddl

与已注册的任务关联的安全描述符。 可以在任务的安全描述符中指定访问控制列表 (ACL) ，以便允许或拒绝某些用户和组对任务的访问权限。

注意 如果拒绝本地系统帐户访问任务，则任务计划程序服务可能会产生意外结果。
 

[out] ppTask

表示新任务的 IRegisteredTask 接口。

传入对 NULLIRegisteredTask 接口指针的引用。 引用非 NULL 指针可能会导致内存泄漏，因为指针将被覆盖。

返回值

此方法可以返回其中一个值。

返回代码/值 说明
S_OK
0x0
 操作已成功完成。
E_ACCESS_DENIED
0x80070005
 访问被拒绝以连接到任务计划程序服务。
E_OUTOFMEMORY
0x8007000e
 应用程序没有足够的内存来完成操作，或者 用户 或 密码 至少有一个 null 值和一个非 null 值。
SCHED_S_BATCH_LOGON_PROBLEM
0x0004131C
 任务已注册，但可能无法启动。 需要为任务主体启用批量登录权限。
SCHED_S_SOME_TRIGGERS_FAILED
0x0004131B
 任务已注册，但并非所有指定的触发器都将启动任务。

注解

对于包含消息框操作的任务，如果激活任务并且任务具有交互式登录类型，将显示消息框。 若要将任务登录类型设置为交互式，请在任务主体的 LogonType 属性或 ITaskFolder：：RegisterTask 或 ITaskFolder：：RegisterTaskDefinition 的 logonType 参数中指定TASK_LOGON_INTERACTIVE_TOKEN或TASK_LOGON_GROUP。

只有管理员组的成员才能使用启动触发器创建任务。

可以使用 userId 参数中指定的组成功注册任务，TASK_LOGON_INTERACTIVE_TOKENITaskFolder：：RegisterTask 或 ITaskFolder：：RegisterTaskDefinition 的 logonType 参数中指定的组，但任务将不会运行。

将TASK_VALIDATE_ONLY和TASK_IGNORE_REGISTRATION_TRIGGERS值一起传递给 flags 参数是无效的参数。

ITaskFolder：：RegisterTaskDefinition 方法在由用户参数等于 NULL、password 参数等于 NULL 且 logonType 参数等于 TASK_LOGON_SERVICE_ACCOUNT 的系统帐户调用时返回错误80070534。

如果任务定义的网络不存在于任务的 NetworkSettings 设置中，则在注册任务时， ITaskFolder：：RegisterTaskDefinition 方法将返回错误0x8000ffff。

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 taskschd.h
Library Taskschd.lib
DLL Taskschd.dll

另请参阅

IRegisteredTask

ITaskFolder

任务计划程序