ITaskFolder：：RegisterTaskDefinition 方法 (taskschd.h)

  • 發行項

註冊 (使用 ITaskDefinition 介面定義工作，在指定的位置建立工作) 。

語法

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

參數

[in] path

工作的名稱。 如果此值為 NULL，工作將會在根工作資料夾中註冊，而工作名稱將是工作排程器服務所建立的 GUID 值。

工作名稱不能以空格字元開頭或結尾。 '.' 字元無法用來指定目前的工作資料夾和 '..' 字元無法用來指定路徑中的父工作資料夾。

[in] pDefinition

已註冊工作的定義。

[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：：RegisterTaskDefinition 函式以更新工作時，工作排程器服務不會新增新內容主體的 ACE，也不會從舊的內容主體中移除 ACE。
TASK_IGNORE_REGISTRATION_TRIGGERS
0x20
 工作排程器會建立工作，但忽略工作中的註冊觸發程式。 藉由忽略註冊觸發程式，除非以時間為基礎的觸發程式在註冊時，否則工作將不會執行。

[in] userId

用來註冊工作的用戶認證。 如果存在，這些認證會優先於 pDefinition 參數所指向的工作定義物件中指定的認證。

注意 如果工作定義為工作排程器 1.0 工作，則請勿在此 userId 參數中使用組名 (而非特定用戶名稱) 。 當 相容性 屬性設定為工作設定中的TASK_COMPATIBILITY_V1時，工作會定義為工作排程器 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屬性中指定TASK_LOGON_INTERACTIVE_TOKEN或TASK_LOGON_GROUP，或在ITaskFolder：：RegisterTask 或 ITaskFolder：：RegisterTaskDefinition 的 logonType 參數中指定 。

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

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

將TASK_VALIDATE_ONLY和TASK_IGNORE_REGISTRATION_TRIGGERS值一起傳遞至 flags 參數是無效的自變數。

當 System 帳戶呼叫的用戶參數等於 NULL 時，ITaskFolder：：RegisterTaskDefinition 方法會傳回錯誤80070534，密碼參數等於 NULL，而 logonType 參數等於 TASK_LOGON_SERVICE_ACCOUNT。

如果工作定義工作之 NetworkSettings 設定中不存在的網路， ITaskFolder：：RegisterTaskDefinition 方法會在工作註冊時傳回錯誤0x8000ffff。

規格需求

需求 值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 taskschd.h
程式庫 Taskschd.lib
Dll Taskschd.dll

另請參閱

IRegisteredTask

ITaskFolder

工作排程器