共用方式為


ITaskFolder::RegisterTask 方法 (taskschd.h)

使用 XML 來定義工作,在資料夾中註冊 (creates) 新工作。

語法

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_CREATETASK_UPDATETASK_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

用來註冊工作的用戶認證。

注意 如果工作定義為 Task Scheduler 1.0 工作,則請勿在此 userId 參數中使用組名(而非特定使用者名稱)。 當工作 XML 中 Task 元素的版本屬性設定為 1.1 時,工作會定義為 Task 排程器 1.0 工作。
 

[in] password

用來註冊工作之userId的密碼。 使用TASK_LOGON_SERVICE_ACCOUNT登入類型時,密碼必須是空 VARIANT 值,例如 VT_NULLVT_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
工作已註冊,但並非所有指定的觸發程式都會啟動工作。

言論

針對包含消息框動作的工作,如果工作已啟用且工作具有互動式登入類型,則會顯示消息框。 若要將工作登入類型設定為互動式,請在工作主體的 LogonType 屬性中,或在 ITaskFolder::RegisterTaskITaskFolder::RegisterTaskDefinitionlogonType 參數中指定 TASK_LOGON_INTERACTIVE_TOKENTASK_LOGON_GROUP

只有 Administrators 群組的成員可以使用開機觸發程式建立工作。

您可以成功向 userId 參數中指定的群組註冊工作,TASK_LOGON_INTERACTIVE_TOKEN 並在 ITaskFolder::RegisterTaskFolder::RegisterTaskITaskFolder::RegisterTaskDefinitionlogonType 指定,但工作將不會執行。

將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

工作排程器