Método ITaskFolder::RegisterTaskDefinition (taskschd.h)

Registra (cria) uma tarefa em um local especificado usando a interface ITaskDefinition para definir uma tarefa.

Sintaxe

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

Parâmetros

[in] path

O nome da tarefa. Se esse valor for NULL, a tarefa será registrada na pasta da tarefa raiz e o nome da tarefa será um valor GUID criado pelo serviço Agendador de Tarefas.

Um nome de tarefa não pode começar ou terminar com um caractere de espaço. O caractere '.' não pode ser usado para especificar a pasta de tarefas atual e o '.'. os caracteres não podem ser usados para especificar a pasta de tarefas pai no caminho.

[in] pDefinition

A definição da tarefa registrada.

[in] flags

Uma constante TASK_CREATION .

Valor	Significado
TASK_VALIDATE_ONLY 0x1	O Agendador de Tarefas verifica a sintaxe do XML que descreve a tarefa, mas não registra a tarefa. Essa constante não pode ser combinada com os valores TASK_CREATE, TASK_UPDATE ou TASK_CREATE_OR_UPDATE .
TASK_CREATE 0x2	O Agendador de Tarefas registra a tarefa como uma nova tarefa.
TASK_UPDATE 0x4	O Agendador de Tarefas registra a tarefa como uma versão atualizada de uma tarefa existente. Quando uma tarefa com um gatilho de registro for atualizada, a tarefa será executada após a atualização ocorrer.
TASK_CREATE_OR_UPDATE 0x6	O Agendador de Tarefas registra a tarefa como uma nova tarefa ou como uma versão atualizada se a tarefa já existir. Equivalente a TASK_CREATE | TASK_UPDATE.
TASK_DISABLE 0x8	O Agendador de Tarefas desabilita a tarefa existente.
TASK_DONT_ADD_PRINCIPAL_ACE 0x10	O Agendador de Tarefas é impedido de adicionar a ACE (entrada de controle de acesso) para a entidade de contexto. Quando a função ITaskFolder::RegisterTaskDefinition é chamada com esse sinalizador para atualizar uma tarefa, o serviço Agendador de Tarefas não adiciona o ACE para a nova entidade de contexto e não remove o ACE da entidade de contexto antiga.
TASK_IGNORE_REGISTRATION_TRIGGERS 0x20	O Agendador de Tarefas cria a tarefa, mas ignora os gatilhos de registro na tarefa. Ignorando os gatilhos de registro, a tarefa não será executada quando for registrada, a menos que um gatilho baseado em tempo faça com que ela seja executada no registro.

[in] userId

As credenciais do usuário usadas para registrar a tarefa. Se presentes, essas credenciais têm prioridade sobre as credenciais especificadas no objeto de definição de tarefa apontado pelo parâmetro pDefinition .

Nota Se a tarefa for definida como uma tarefa do Agendador de Tarefas 1.0, não use um nome de grupo (em vez de um nome de usuário específico) nesse parâmetro userId. Uma tarefa é definida como uma tarefa do Agendador de Tarefas 1.0 quando a propriedade Compatibilidade é definida como TASK_COMPATIBILITY_V1 nas configurações da tarefa.

 

[in] password

A senha da userId usada para registrar a tarefa. Quando o tipo de logon TASK_LOGON_SERVICE_ACCOUNT é usado, a senha deve ser um valor VARIANT vazio, como VT_NULL ou VT_EMPTY.

[in] logonType

Define qual técnica de logon é usada para executar a tarefa registrada.

Valor	Significado
TASK_LOGON_NONE 0	O método de logon não é especificado. Usado para credenciais não NT.
TASK_LOGON_PASSWORD 1	Use uma senha para fazer logon no usuário. A senha deve ser fornecida no momento do registro.
TASK_LOGON_S4U 2	Use um token interativo existente para executar uma tarefa. O usuário deve fazer logon usando um serviço para logon de usuário (S4U). Quando um logon S4U é usado, nenhuma senha é armazenada pelo sistema e não há acesso à rede ou a arquivos criptografados.
TASK_LOGON_INTERACTIVE_TOKEN 3	O usuário já deve estar conectado. A tarefa será executada somente em uma sessão interativa existente.
TASK_LOGON_GROUP 4	Ativação de grupo. O campo groupId especifica o grupo.
TASK_LOGON_SERVICE_ACCOUNT 5	Indica que uma conta de Sistema Local, Serviço Local ou Serviço de Rede está sendo usada como um contexto de segurança para executar a tarefa.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD 6	Primeiro, use o token interativo. Se o usuário não estiver conectado (nenhum token interativo está disponível), a senha será usada. A senha deve ser especificada quando uma tarefa é registrada. Esse sinalizador não é recomendado para novas tarefas porque é menos confiável do que TASK_LOGON_PASSWORD.

[in, optional] sddl

O descritor de segurança associado à tarefa registrada. Você pode especificar a ACL (lista de controle de acesso) no descritor de segurança de uma tarefa para permitir ou negar acesso a determinados usuários e grupos a uma tarefa.

Nota Se a conta Sistema Local tiver acesso negado a uma tarefa, o serviço Agendador de Tarefas poderá produzir resultados inesperados.

 

[out] ppTask

Uma interface IRegisteredTask que representa a nova tarefa.

Passe uma referência para um ponteiro de interface IRegisteredTaskNULL. Fazer referência a um ponteiro não NULL pode causar um vazamento de memória porque o ponteiro será substituído.

Retornar valor

Esse método pode retornar um desses valores.

Valor/código retornado	Descrição
S_OK 0x0	A operação foi concluída com sucesso.
E_ACCESS_DENIED 0x80070005	O acesso foi negado para se conectar ao serviço agendador de tarefas.
E_OUTOFMEMORY 0x8007000e	O aplicativo não tem memória suficiente para concluir a operação ou o usuário ou senha tem pelo menos um valor nulo e um valor não nulo .
SCHED_S_BATCH_LOGON_PROBLEM 0x0004131C	A tarefa está registrada, mas pode não ser iniciada. O privilégio de logon em lote precisa ser habilitado para a entidade de tarefa.
SCHED_S_SOME_TRIGGERS_FAILED 0x0004131B	A tarefa é registrada, mas nem todos os gatilhos especificados iniciarão a tarefa.

Comentários

Para uma tarefa, que contém uma ação de caixa de mensagem, a caixa de mensagem será exibida se a tarefa for ativada e a tarefa tiver um tipo de logon interativo. Para definir o tipo de logon da tarefa como interativo, especifique TASK_LOGON_INTERACTIVE_TOKEN ou TASK_LOGON_GROUP na propriedade LogonType da entidade de tarefa ou no parâmetro logonType de ITaskFolder::RegisterTask ou ITaskFolder::RegisterTaskDefinition.

Somente um membro do grupo Administradores pode criar uma tarefa com um gatilho de inicialização.

Você pode registrar com êxito uma tarefa com um grupo especificado no parâmetro userId e TASK_LOGON_INTERACTIVE_TOKEN especificado no parâmetro logonType de ITaskFolder::RegisterTask ou ITaskFolder::RegisterTaskDefinition, mas a tarefa não será executada.

Passar os valores TASK_VALIDATE_ONLY e TASK_IGNORE_REGISTRATION_TRIGGERS juntos para o parâmetro flags é um argumento inválido.

O método ITaskFolder::RegisterTaskDefinition retorna o erro 80070534 quando chamado pela conta do Sistema com o parâmetro de usuário igual a NULL, o parâmetro de senha igual a NULL e o parâmetro logonType igual a TASK_LOGON_SERVICE_ACCOUNT.

Se uma tarefa definir uma rede que não existe nas configurações networkSettings da tarefa, o método ITaskFolder::RegisterTaskDefinition retornará o erro 0x8000ffff quando a tarefa for registrada.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	taskschd.h
Biblioteca	Taskschd.lib
DLL	Taskschd.dll

Confira também

IRegisteredTask

ITaskFolder

Agendador de Tarefas