Condividi tramite

Metodo ITaskFolder::RegisterTask (taskschd.h)

  • Articolo

Registra (crea) una nuova attività nella cartella utilizzando XML per definire l'attività.

Sintassi

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

Parametri

[in] path

Nome dell'attività. Se questo valore è NULL, l'attività verrà registrata nella cartella dell'attività radice e il nome dell'attività sarà un valore GUID creato dal servizio Utilità di pianificazione.

Un nome di attività non può iniziare o terminare con un carattere di spazio. Impossibile utilizzare il carattere '.' per specificare la cartella dell'attività corrente e '.'. Non è possibile utilizzare caratteri per specificare la cartella dell'attività padre nel percorso.

[in] xmlText

Definizione in formato XML dell'attività.

Gli argomenti seguenti contengono attività definite tramite XML.

[in] flags

Costante TASK_CREATION .

Valore Significato
TASK_VALIDATE_ONLY
0x1
 L'Utilità di pianificazione verifica la sintassi del codice XML che descrive l'attività, ma non registra l'attività. Questa costante non può essere combinata con i valori TASK_CREATE, TASK_UPDATE o TASK_CREATE_OR_UPDATE .
TASK_CREATE
0x2
 Utilità di pianificazione registra l'attività come nuova attività.
TASK_UPDATE
0x4
 Utilità di pianificazione registra l'attività come versione aggiornata di un'attività esistente. Quando un'attività con un trigger di registrazione viene aggiornata, l'attività verrà eseguita dopo l'aggiornamento.
TASK_CREATE_OR_UPDATE
0x6
 Utilità di pianificazione registra l'attività come nuova attività o come versione aggiornata se l'attività esiste già. Equivalente a TASK_CREATE | TASK_UPDATE.
TASK_DISABLE
0x8
 Utilità di pianificazione disabilita l'attività esistente.
TASK_DONT_ADD_PRINCIPAL_ACE
0x10
 L'Utilità di pianificazione non consente di aggiungere la voce di controllo di accesso (ACE) consentita per l'entità di contesto. Quando la funzione ITaskFolder::RegisterTask viene chiamata con questo flag per aggiornare un'attività, il servizio Utilità di pianificazione non aggiunge l'ace per la nuova entità di contesto e non rimuove l'ACE dall'entità di contesto precedente.
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 L'Utilità di pianificazione crea l'attività, ma ignora i trigger di registrazione nell'attività. Ignorando i trigger di registrazione, l'attività non verrà eseguita quando viene registrata, a meno che un trigger basato sul tempo non ne causi l'esecuzione durante la registrazione.

[in] userId

Credenziali utente usate per registrare l'attività.

Nota Se l'attività è definita come attività Utilità di pianificazione 1.0, non usare un nome di gruppo (anziché un nome utente specifico) in questo parametro userId. Un'attività viene definita come attività Utilità di pianificazione 1.0 quando l'attributo version dell'elemento Task nel codice XML dell'attività è impostato su 1.1.
 

[in] password

Password per l'id utente utilizzato per registrare l'attività. Quando viene usato il tipo di accesso TASK_LOGON_SERVICE_ACCOUNT, la password deve essere un valore VARIANT vuoto, ad esempio VT_NULL o VT_EMPTY.

[in] logonType

Valore che definisce la tecnica di accesso utilizzata per eseguire l'attività registrata.

Valore Significato
TASK_LOGON_NONE
0
 Il metodo di accesso non è specificato. Utilizzato per le credenziali non NT.
TASK_LOGON_PASSWORD
1
 Usare una password per l'accesso all'utente. La password deve essere specificata al momento della registrazione.
TASK_LOGON_S4U
2
 Usare un token interattivo esistente per eseguire un'attività. L'utente deve accedere usando un servizio per l'accesso utente (S4U). Quando viene usato un accesso S4U, nessuna password viene archiviata dal sistema e non vi è accesso alla rete o ai file crittografati.
TASK_LOGON_INTERACTIVE_TOKEN
3
 L'utente deve essere già connesso. L'attività verrà eseguita solo in una sessione interattiva esistente.
TASK_LOGON_GROUP
4
 Attivazione del gruppo. Il campo groupId specifica il gruppo.
TASK_LOGON_SERVICE_ACCOUNT
5
 Indica che un account del sistema locale, del servizio locale o del servizio di rete viene usato come contesto di sicurezza per eseguire l'attività.
TASK_LOGON_INTERACTIVE_TOKEN_OR_PASSWORD
6
 Usare prima di tutto il token interattivo. Se l'utente non è connesso (non è disponibile alcun token interattivo), viene usata la password. La password deve essere specificata quando viene registrata un'attività. Questo flag non è consigliato per le nuove attività perché è meno affidabile di TASK_LOGON_PASSWORD.

[in, optional] sddl

Descrittore di sicurezza associato all'attività registrata. È possibile specificare l'elenco di controllo di accesso (ACL) nel descrittore di sicurezza per un'attività per consentire o negare a determinati utenti e gruppi l'accesso a un'attività.

Nota Se l'account di sistema locale viene negato l'accesso a un'attività, il servizio Utilità di pianificazione può produrre risultati imprevisti.
 

[out] ppTask

Interfaccia IRegisteredTask che rappresenta la nuova attività.

Passare un riferimento a un puntatore all'interfaccia IRegisteredTaskNULL. Fare riferimento a un puntatore non NULL può causare una perdita di memoria perché il puntatore verrà sovrascritto.

Valore restituito

Questo metodo può restituire uno di questi valori.

Codice/valore restituito Descrizione
S_OK
0x0
 Operazione riuscita.
E_ACCESS_DENIED
0x80070005
 L'accesso viene negato per connettersi al servizio Utilità di pianificazione.
E_OUTOFMEMORY
0x8007000e
 L'applicazione non ha memoria sufficiente per completare l'operazione o l'utente o la password ha almeno un valore Null e un valore non Null.
SCHED_S_BATCH_LOGON_PROBLEM
0x0004131C
 L'attività viene registrata, ma potrebbe non riuscire ad avviare. Il privilegio di accesso batch deve essere abilitato per l'entità attività.
SCHED_S_SOME_TRIGGERS_FAILED
0x0004131B
 L'attività viene registrata, ma non tutti i trigger specificati inizieranno l'attività.

Commenti

Per un'attività che contiene un'azione della finestra di messaggio, la casella di messaggio verrà visualizzata se l'attività viene attivata e l'attività ha un tipo di accesso interattivo. Per impostare il tipo di accesso dell'attività per essere interattivo, specificare TASK_LOGON_INTERACTIVE_TOKEN o TASK_LOGON_GROUP nella proprietà LogonType dell'entità attività o nel parametro logonType di ITaskFolder::RegisterTask o ITaskFolder::RegisterTaskDefinition.

Solo un membro del gruppo Administrators può creare un'attività con un trigger di avvio.

È possibile registrare correttamente un'attività con un gruppo specificato nel parametro userId e TASK_LOGON_INTERACTIVE_TOKEN specificato nel parametro logonType di ITaskFolder::RegisterTaskFolder::RegisterTaskFolder::RegisterTaskDefinition, ma l'attività non verrà eseguita.

Il passaggio dei valori TASK_VALIDATE_ONLY e TASK_IGNORE_REGISTRATION_TRIGGERS insieme al parametro flags è un argomento non valido.

Se un'attività definisce una rete che non esiste nelle impostazioni NetworkSettings dell'attività, il metodo ITaskFolder::RegisterTask restituirà l'errore 0x8000ffff quando l'attività viene registrata.

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione taskschd.h
Libreria Taskschd.lib
DLL Taskschd.dll

Vedi anche

IRegisteredTask

ITaskFolder

Utilità di pianificazione