通过

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 参数中使用组名称（而不是特定用户名）。 当 兼容性 属性设置为任务设置中的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 属性中指定 TASK_LOGON_INTERACTIVE_TOKEN 或 TASK_LOGON_GROUP，或在 ITaskFolder：：RegisterTaskFolder：：RegisterTas kDefinition的 logonType 参数中指定 TASK_LOGON_INTERACTIVE_TOKEN 或 TASK_LOGON_GROUP。

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

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

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

ITaskFolder：：RegisterTaskDefinition 方法在系统帐户调用时返回错误80070534，用户 参数等于 NULL，密码 参数等于 NULL，logonType 参数等于 TASK_LOGON_SERVICE_ACCOUNT。

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

要求

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

另请参阅

IRegisteredTask

ITaskFolder

任务计划程序