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

Registra (cria) uma nova tarefa na pasta usando XML para definir a tarefa.

Sintaxe

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

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 tarefa atual e o '.'. os caracteres não podem ser usados para especificar a pasta de tarefa pai no caminho.

[in] xmlText

Uma definição formatada em XML da tarefa.

Os tópicos a seguir contêm tarefas definidas usando XML.

• exemplo de gatilho de tempo (XML)
• exemplo de gatilho de evento (XML)
• exemplo de gatilho diário (XML)
• exemplo de gatilho de registro (XML)
• de exemplo de gatilho semanal (XML)
• exemplo de gatilho de logon (XML)
• exemplo de gatilho de inicialização (XML)

[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_UPDATEou 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 registrará 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::RegisterTask é 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.

Observação 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) neste parâmetro userId. Uma tarefa é definida como uma tarefa do Agendador de Tarefas 1.0 quando o atributo de versão do elemento Task no XML da tarefa é definido como 1.1.

 

[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 de VARIANT vazio, como VT_NULL ou VT_EMPTY.

[in] logonType

Um valor que 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 logon S4U (serviço para usuário). 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 do Sistema Local, do Serviço Local ou do Serviço de Rede é 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 para uma tarefa, a fim de permitir ou negar acesso a determinados usuários e grupos a uma tarefa.

Observação 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 a uma ponteiro de interfaceNULLIRegisteredTask. Fazer referência a um ponteiro NULL nãopode causar um vazamento de memória porque o ponteiro será substituído.

Valor de retorno

Esse método pode retornar um desses valores.

Código/valor de retorno	Descrição
S_OK 0x0	A operação foi concluída com êxito.
E_ACCESS_DENIED 0x80070005	O acesso é 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 segurança da tarefa.
SCHED_S_SOME_TRIGGERS_FAILED 0x0004131B	A tarefa é registrada, mas nem todos os gatilhos especificados iniciarão a tarefa.

Observações

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 os sinalizadores parâmetro é um argumento inválido.

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	taskschd.h
biblioteca	Taskschd.lib
de DLL	Taskschd.dll

Consulte também

IRegisteredTask

ITaskFolder

do Agendador de Tarefas