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

Registra (crea) una tarea en una ubicación especificada mediante la interfaz ITaskDefinition para definir una tarea.

Sintaxis

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

Nombre de la tarea. Si este valor es NULL, la tarea se registrará en la carpeta raíz de la tarea y el nombre de la tarea será un valor GUID creado por el servicio Programador de tareas.

Un nombre de tarea no puede comenzar ni terminar con un carácter de espacio. No se puede usar el carácter '.' para especificar la carpeta de tareas actual y '.'. no se pueden usar caracteres para especificar la carpeta de tareas primaria en la ruta de acceso.

[in] pDefinition

Definición de la tarea registrada.

[in] flags

Constante TASK_CREATION.

Valor	Significado
TASK_VALIDATE_ONLY 0x1	El Programador de tareas comprueba la sintaxis del XML que describe la tarea, pero no registra la tarea. Esta constante no se puede combinar con los valores de TASK_CREATE, TASK_UPDATEo TASK_CREATE_OR_UPDATE.
TASK_CREATE 0x2	El Programador de tareas registra la tarea como una nueva tarea.
TASK_UPDATE 0x4	El Programador de tareas registra la tarea como una versión actualizada de una tarea existente. Cuando se actualiza una tarea con un desencadenador de registro, la tarea se ejecutará después de que se produzca la actualización.
TASK_CREATE_OR_UPDATE 0x6	El Programador de tareas registra la tarea como una nueva tarea o como una versión actualizada si la tarea ya existe. Equivalente a TASK_CREATE | TASK_UPDATE.
TASK_DISABLE 0x8	El Programador de tareas deshabilita la tarea existente.
TASK_DONT_ADD_PRINCIPAL_ACE 0x10	Se impide que el Programador de tareas agregue la entrada permitir el control de acceso (ACE) para la entidad de seguridad de contexto. Cuando se llama a la función ITaskFolder::RegisterTaskDefini tion con esta marca para actualizar una tarea, el servicio Programador de tareas no agrega la ACE para la nueva entidad de seguridad de contexto y no quita la ACE de la entidad de seguridad del contexto anterior.
TASK_IGNORE_REGISTRATION_TRIGGERS 0x20	El Programador de tareas crea la tarea, pero omite los desencadenadores de registro en la tarea. Al omitir los desencadenadores de registro, la tarea no se ejecutará cuando se registre, a menos que un desencadenador basado en tiempo haga que se ejecute en el registro.

[in] userId

Credenciales de usuario usadas para registrar la tarea. Si está presente, estas credenciales tienen prioridad sobre las credenciales especificadas en el objeto de definición de tarea al que apunta el parámetro pDefinition.

Nota Si la tarea se define como tarea programador de tareas 1.0, no use un nombre de grupo (en lugar de un nombre de usuario específico) en este parámetro userId. Una tarea se define como una tarea del Programador de tareas 1.0 cuando la propiedad compatibilidad de se establece en TASK_COMPATIBILITY_V1 en la configuración de la tarea.

 

[in] password

Contraseña del userId usado para registrar la tarea. Cuando se usa el tipo de inicio de sesión de TASK_LOGON_SERVICE_ACCOUNT, la contraseña debe ser un valor VARIANT vacío, como VT_NULL o VT_EMPTY.

[in] logonType

Define qué técnica de inicio de sesión se usa para ejecutar la tarea registrada.

Valor	Significado
TASK_LOGON_NONE 0	No se especifica el método de inicio de sesión. Se usa para las credenciales que no son de NT.
TASK_LOGON_PASSWORD 1	Use una contraseña para iniciar sesión en el usuario. La contraseña debe proporcionarse en el momento del registro.
TASK_LOGON_S4U 2	Use un token interactivo existente para ejecutar una tarea. El usuario debe iniciar sesión con un servicio para el inicio de sesión del usuario (S4U). Cuando se usa un inicio de sesión S4U, el sistema no almacena ninguna contraseña y no hay acceso a la red ni a los archivos cifrados.
TASK_LOGON_INTERACTIVE_TOKEN 3	El usuario ya debe iniciar sesión. La tarea solo se ejecutará en una sesión interactiva existente.
TASK_LOGON_GROUP 4	Activación de grupo. El campo groupId especifica el grupo.
TASK_LOGON_SERVICE_ACCOUNT 5	Indica que se usa una cuenta de sistema local, servicio local o servicio de red como contexto de seguridad para ejecutar la tarea.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD 6	En primer lugar, use el token interactivo. Si el usuario no ha iniciado sesión (no hay ningún token interactivo disponible), se usa la contraseña. La contraseña debe especificarse cuando se registra una tarea. Esta marca no se recomienda para las nuevas tareas porque es menos confiable que TASK_LOGON_PASSWORD.

[in, optional] sddl

Descriptor de seguridad asociado a la tarea registrada. Puede especificar la lista de control de acceso (ACL) en el descriptor de seguridad de una tarea para permitir o denegar el acceso de determinados usuarios y grupos a una tarea.

Nota Si se deniega el acceso a una tarea a la cuenta del sistema local, el servicio Programador de tareas puede producir resultados inesperados.

 

[out] ppTask

Interfaz IRegisteredTask que representa la nueva tarea.

Pase una referencia a un puntero de interfaz IRegisteredTas kNULL. Hacer referencia a un puntero null nopuede provocar una pérdida de memoria porque se sobrescribirá el puntero.

Valor devuelto

Este método puede devolver uno de estos valores.

Código y valor devueltos	Descripción
S_OK 0x0	La operación se completó correctamente.
E_ACCESS_DENIED 0x80070005	Se deniega el acceso para conectarse al servicio Programador de tareas.
E_OUTOFMEMORY 0x8007000e	La aplicación no tiene suficiente memoria para completar la operación o el usuario de o contraseña tiene al menos un null y un valor nonull.
SCHED_S_BATCH_LOGON_PROBLEM 0x0004131C	La tarea está registrada, pero puede no iniciarse. El privilegio de inicio de sesión por lotes debe estar habilitado para la entidad de seguridad de la tarea.
SCHED_S_SOME_TRIGGERS_FAILED 0x0004131B	La tarea está registrada, pero no todos los desencadenadores especificados iniciarán la tarea.

Observaciones

Para una tarea, que contiene una acción de cuadro de mensaje, se mostrará el cuadro de mensaje si la tarea está activada y la tarea tiene un tipo de inicio de sesión interactivo. Para establecer el tipo de inicio de sesión de tarea para que sea interactivo, especifique TASK_LOGON_INTERACTIVE_TOKEN o TASK_LOGON_GROUP en la propiedad LogonType de la entidad de seguridad de la tarea o en el parámetro logonType de ITaskFolder::RegisterTask o ITaskFolder::RegisterTaskDefinition.

Solo un miembro del grupo Administradores puede crear una tarea con un desencadenador de arranque.

Puede registrar correctamente una tarea con un grupo especificado en el parámetro userId y TASK_LOGON_INTERACTIVE_TOKEN especificado en el parámetro logonType de ITaskFolder::RegisterTask o ITaskFolder::RegisterTaskDefinition, pero la tarea no se ejecutará.

Pasar los valores TASK_VALIDATE_ONLY y TASK_IGNORE_REGISTRATION_TRIGGERS juntos a las marcas de parámetro es un argumento no válido.

El método ITaskFolder::RegisterTaskDefinition devuelve 80070534 de error cuando lo llama la cuenta del sistema con el parámetro de usuario igual aNULL, el parámetro contraseña igual a NULLy el parámetro logonType igual a TASK_LOGON_SERVICE_ACCOUNT.

Si una tarea define una red que no existe en la configuración de NetworkSettings de la tarea, el método ITaskFolder::RegisterTaskDefinition devolverá el error 0x8000ffff cuando se registre la tarea.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2008 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	taskschd.h
biblioteca de	Taskschd.lib
DLL de	Taskschd.dll

Consulte también

IRegisteredTask

ITaskFolder

programador de tareas de