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 パラメーターでグループ名 (特定のユーザー名ではなく) を使用しないでください。 タスクの設定で Compatibility プロパティが TASK_COMPATIBILITY_V1 に設定されている場合、タスクはタスク スケジューラ 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 パラメーターに渡すことは無効な引数です。

ITaskFolder::RegisterTaskDefinition メソッドは、ユーザー パラメーターが NULL、パスワード パラメーターが NULL、logonType パラメーターが TASK_LOGON_SERVICE_ACCOUNT と等しいシステム アカウントによって呼び出されると、エラー 80070534を返します。

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

要件

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

こちらもご覧ください

IRegisteredTask

ITaskFolder

タスク スケジューラ