ITaskFolder::RegisterTask メソッド (taskschd.h)

  • [アーティクル]

XML を使用してタスクを定義する新しいタスクをフォルダーに登録 (作成) します。

構文

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

タスクの登録に使用されるユーザー資格情報。

メモ タスクがタスク スケジューラ 1.0 タスクとして定義されている場合は、この userId パラメーターでグループ名 (特定のユーザー名ではなく) を使用しないでください。 タスクの XML 内の Task 要素の version 属性が 1.1 に設定されている場合、タスクはタスク スケジューラ 1.0 タスクとして定義されます。
 

[in] password

タスクの登録に使用する userId のパスワード。 TASK_LOGON_SERVICE_ACCOUNTログオンの種類を使用する場合、パスワードは、VT_NULLやVT_EMPTYなどの空の VARIANT 値である必要があります。

[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
 アプリケーションに操作を完了するための十分なメモリがないか、 ユーザー または パスワード に少なくとも 1 つの null 値と 1 つの 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 パラメーターで指定されたグループにタスクを正常に登録し、ITaskFolder::RegisterTask または ITaskFolder::RegisterTaskDefinition の logonType パラメーターで指定TASK_LOGON_INTERACTIVE_TOKENできますが、タスクは実行されません。

TASK_VALIDATE_ONLYとTASK_IGNORE_REGISTRATION_TRIGGERSの値を flags パラメーターに渡すことは無効な引数です。

タスクの NetworkSettings 設定に存在しないネットワークがタスクで定義されている場合、タスクの登録時に ITaskFolder::RegisterTask メソッドはエラー 0x8000ffffを返します。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー taskschd.h
Library Taskschd.lib
[DLL] Taskschd.dll

こちらもご覧ください

IRegisteredTask

ITaskFolder

タスク スケジューラ