Поделиться через

Метод 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. Задача определяется как задача Планировщика задач 1.0, когда атрибут версии элемента Task в XML-коде задачи имеет значение 1.1.
 

[in] password

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

Замечания

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

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

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

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

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

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows Vista [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2008 [только классические приложения]
целевая платформа Виндоус
заголовка taskschd.h
библиотеки Taskschd.lib
DLL Taskschd.dll

См. также

IRegisteredTask

ITaskFolder

планировщик задач