Метод ITaskFolder::RegisterTaskDefinition (taskschd.h)

Статья
08/26/2023

Регистрирует (создает) задачу в указанном расположении с помощью интерфейса 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. Задача определяется как задача Планировщика задач версии 1.0, если свойству Compatibility присвоено значение TASK_COMPATIBILITY_V1 в параметрах задачи.

[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) в дескрипторе безопасности для задачи, чтобы разрешить или запретить определенным пользователям и группам доступ к задаче.

Примечание Если учетной записи Local System отказано в доступе к задаче, служба планировщика задач может привести к непредвиденным результатам.

[out] ppTask

Интерфейс IRegisteredTask , представляющий новую задачу.

Передайте ссылку на указатель интерфейса IRegisteredTaskNULL. Ссылка на указатель, отличный от 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	Задача зарегистрирована, но не все указанные триггеры запускают ее.

Для задачи, содержащей действие окна сообщения, окно сообщения будет отображаться, если задача активирована и задача имеет тип интерактивного входа. Чтобы задать интерактивный тип входа в задачу, укажите TASK_LOGON_INTERACTIVE_TOKEN или TASK_LOGON_GROUP в свойстве LogonType субъекта задачи или в параметре logonTypeобъекта ITaskFolder::RegisterTask или ITaskFolder::RegisterTaskDefinition.

Только член группы "Администраторы" может создать задачу с триггером загрузки.

Вы можете успешно зарегистрировать задачу с группой, указанной в параметре userId и TASK_LOGON_INTERACTIVE_TOKEN указанной в параметре logonTypeITaskFolder::RegisterTask или ITaskFolder::RegisterTaskDefinition, но задача не будет выполняться.

Передача значений TASK_VALIDATE_ONLY и TASK_IGNORE_REGISTRATION_TRIGGERS в параметр flags является недопустимым аргументом.

Метод ITaskFolder::RegisterTaskDefinition возвращает ошибку 80070534 при вызове системной учетной записью с параметром пользователя , равным NULL, параметром passwordравным NULL и параметром logonType , равным TASK_LOGON_SERVICE_ACCOUNT.

Если задача определяет сеть, которая не существует в параметрах NetworkSettings задачи, метод ITaskFolder::RegisterTaskDefinition возвращает ошибку 0x8000ffff при регистрации задачи.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	taskschd.h
Библиотека	Taskschd.lib
DLL	Taskschd.dll

См. также раздел

IRegisteredTask

ITaskFolder

Планировщик заданий

Share via