共用方式為

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_CREATE、TASK_UPDATE或 TASK_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_NULL 或 VT_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：：RegisterTask 或 ITaskFolder：：RegisterTaskDefinition的 logonType 參數中指定 TASK_LOGON_INTERACTIVE_TOKEN 或 TASK_LOGON_GROUP。

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

您可以成功向 userId 參數中指定的群組註冊工作，TASK_LOGON_INTERACTIVE_TOKEN 並在 ITaskFolder：：RegisterTaskFolder：：RegisterTask 或 ITaskFolder：：RegisterTaskDefinition的 logonType 指定，但工作將不會執行。

將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

工作排程器