ITaskFolder：：RegisterTask 方法 (taskschd.h)

  • 项目

注册 (使用 XML 在文件夹中创建) 一个新任务来定义任务。

语法

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

参数

[in] path

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

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

[in] xmlText

任务的 XML 格式定义。

以下主题包含使用 XML 定义的任务。

[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：：RegisterTask 函数以更新任务时，任务计划程序服务不会为新上下文主体添加 ACE，也不会从旧上下文主体中删除 ACE。
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 任务计划程序创建任务，但忽略任务中的注册触发器。 通过忽略注册触发器，任务在注册时不会执行，除非基于时间的触发器导致它在注册时执行。

[in] userId

用于注册任务的用户凭据。

注意 如果任务定义为任务计划程序 1.0 任务，则不要使用此 userId 参数中的组名 (而不是特定用户名) 。 当任务 XML 中 Task 元素的版本属性设置为 1.1 时，任务定义为任务计划程序 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 参数中指定的组成功注册任务，并在ITaskFolder：：RegisterTask 或 ITaskFolder：：RegisterTaskDefinition 的 logonType 参数中指定的TASK_LOGON_INTERACTIVE_TOKEN，但该任务不会运行。

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

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

要求

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

另请参阅

IRegisteredTask

ITaskFolder

任务计划程序