ホーム › System.TaskScheduler › IScheduledWorkItem

IScheduledWorkItem

COM

IIDa6b952f0-a4b1-11d0-997d-00aa006887ec継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

特定の作業項目を管理するためのメソッドを提供します。

解説(Remarks)

IScheduledWorkItem インターフェイスは、 ITask インターフェイスの基底インターフェイスです。 IScheduledWorkItem が提供するすべてのメソッドは ITask インターフェイスに継承され、通常はそのインターフェイスを通じて呼び出されます。

例

このインターフェイスの詳細とサンプルコードについては、C/C++ コード例: タスクの終了を参照してください。

メソッド 29

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT CreateTrigger(WORD* piNewTrigger, ITaskTrigger** ppTrigger)

作業項目のトリガーを作成します。

piNewTrigger	WORD*	out	新しいトリガーの、返されるトリガーインデックス値へのポインター。作業項目に関連付けられた最初のトリガーのトリガーインデックスは "0" です。トリガーインデックスのその他の用途については、「解説」を参照してください。
ppTrigger	ITaskTrigger**	out	ITaskTrigger インターフェイスへのポインターへのポインター。現在サポートされている作業項目はタスクのみです。

戻り値

CreateTrigger メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

トリガーの取得または削除を行う際には、piNewTrigger で返されるトリガーインデックスを使用します。ただし、トリガーインデックスは識別子ではありません。これは、作業項目に関連付けられた現在の他のトリガーに対する新しいトリガーの相対的な位置を示すにすぎません。

新しいトリガーの条件を設定するには、 ITaskTrigger::SetTrigger を呼び出します。

作業項目の新しいトリガーを作成した後、アプリケーションは新しいトリガーをディスクに保存するために IPersistFile::Save メソッドを呼び出す必要があります。

例

新しいトリガーを作成する際にトリガーの条件を設定する方法の例については、新しいトリガーの作成を参照してください。

vtbl 4 HRESULT DeleteTrigger(WORD iTrigger)

作業項目からトリガーを削除します。

iTrigger

WORD

削除するトリガーを指定するトリガーインデックス値。詳細については、「解説」を参照してください。

戻り値

DeleteTrigger メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

トリガーインデックスは、トリガーの作成時に各トリガーに対して作成されます。ただし、これは特定のトリガーに対する一意の識別子ではありません。たとえば、4 つのトリガーを作成すると、それらには 0 から 3 までの番号が付けられます。しかし、2 番目のトリガーを削除すると、残りのトリガーには 0 から 2 までの番号が付け直されます。最初のトリガーのインデックスは常に 0 であり、最後のトリガーのインデックスは作業項目のトリガーの総数より 1 小さい値 (TriggerCount -1) になることに注意してください。

トリガーの数は IScheduledWorkItem::GetTriggerCount を使用して取得できます。

トリガーの削除を完了するには、プログラムは DeleteTrigger を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。IPersistFile::Save を呼び出すと、変更がディスクに保存されます。

vtbl 5 HRESULT GetTriggerCount(WORD* pwCount)

現在の作業項目のトリガーの数を取得します。

pwCount

WORD*

out

作業項目に関連付けられたトリガーの数が格納される WORD へのポインター。

戻り値

GetTriggerCount メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

vtbl 6 HRESULT GetTrigger(WORD iTrigger, ITaskTrigger** ppTrigger)

タスクトリガーを取得します。

iTrigger	WORD	in	取得するトリガーのインデックス。
ppTrigger	ITaskTrigger**	out	取得したトリガーの ITaskTrigger インターフェイスへのポインターへのポインター。

戻り値

GetTrigger メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

vtbl 7 HRESULT GetTriggerString(WORD iTrigger, LPWSTR* ppwszTrigger)

作業項目のトリガーを説明する文字列を取得します。

iTrigger	WORD	in	取得するトリガーのインデックス。最初のトリガーは常に 0 で参照されます。詳細については、「解説」を参照してください。
ppwszTrigger	LPWSTR*	out	取得したトリガーの説明を格納する、null で終わる文字列へのポインター。この文字列は不要になった後、CoTaskMemFree の呼び出しで解放する必要があることに注意してください。

戻り値

GetTriggerString メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

トリガーインデックスは識別子ではありません。これは、作業項目に関連付けられた現在のトリガーに対するトリガーの相対的な位置を示すにすぎません。たとえば、4 つのトリガーを作成すると、それらには 0 から 3 までの番号が付けられます。しかし、2 番目のトリガーを削除すると、残りのトリガーには 0 から 2 までの番号が付け直されます。最初のトリガーのインデックスは常に 0 であり、最後のトリガーのインデックスは作業項目のトリガーの総数より 1 小さい値 (TriggerCount -1) になることに注意してください。

トリガーの数は IScheduledWorkItem::GetTriggerCount を使用して取得できます。

例

タスクに関連付けられたすべてのトリガーのトリガー文字列を取得する方法の例については、トリガー文字列の取得例を参照してください。

vtbl 8 HRESULT GetRunTimes(SYSTEMTIME* pstBegin, SYSTEMTIME* pstEnd, WORD* pCount, SYSTEMTIME** rgstTaskTimes)

指定した期間における作業項目の実行時刻を取得します。

pstBegin	SYSTEMTIME*	in	チェックする期間の開始時刻を格納する SYSTEMTIME 構造体へのポインター。この値は範囲に含まれます (inclusive)。
pstEnd	SYSTEMTIME*	in	チェックする期間の終了時刻を格納する SYSTEMTIME 構造体へのポインター。この値は範囲に含まれません (exclusive)。この値に NULL を渡した場合、終了時刻は無限になります。
pCount	WORD*	inout	取得する実行時刻の数を指定する WORD 値へのポインター。入力時、このパラメーターには要求する実行時刻の数が格納されます。これは 1 から TASK_MAX_RUN_TIMES までの数値にできます。出力時、このパラメーターには取得された実行時刻の数が格納されます。
rgstTaskTimes	SYSTEMTIME**	out	SYSTEMTIME 構造体の配列へのポインター。このパラメーターには NULL の LPSYSTEMTIME オブジェクトを渡す必要があります。戻り時、この配列には pCount 個の実行時刻が格納されます。この配列は CoTaskMemFree 関数を呼び出して解放する必要があります。

戻り値

GetRunTimes メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	要求した数の実行時刻が取得されました。
S_FALSE	メソッドは成功しましたが、取得された実行時刻の数は要求した数より少なくなっています。取得された実行時刻の数は pCount が指す値に格納されます。取得された実行時刻の数が 0 の場合、指定した期間内に作業項目を実行させ得るイベントベースのトリガーも存在しません。
SCHED_S_TASK_NO_VALID_TRIGGERS	作業項目は有効ですが、有効なトリガーがありません。
SCHED_S_TASK_DISABLED	作業項目は無効になっています。
E_INVALIDARG	1 つ以上の引数が無効です。
E_OUTOFMEMORY	結果を計算するのに十分なメモリがありません。

vtbl 9 HRESULT GetNextRunTime(SYSTEMTIME* pstNextRun)

作業項目が次に実行される時刻を取得します。

pstNextRun

SYSTEMTIME*

inout

作業項目が次に実行される時刻を格納する SYSTEMTIME 構造体へのポインター。

戻り値

GetNextRunTime メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
SCHED_S_TASK_DISABLED	タスクは無効になっているため、スケジュールされた時刻には実行されません。

vtbl 10 HRESULT SetIdleWait(WORD wIdleMinutes, WORD wDeadlineMinutes)

作業項目が実行される前にシステムがアイドル状態でなければならない時間 (分) を設定します。

wIdleMinutes	WORD	in	作業項目が実行される前にシステムがアイドル状態を維持しなければならない時間 (分) を指定する値。
wDeadlineMinutes	WORD	in	タスクスケジューラが pwIdleMinutes で返されるアイドル時間の期間を待機する最大の分数を指定する値。

戻り値

SetIdleWait メソッドは S_OK を返します。

解説(Remarks)

ここで指定するアイドル時間は、アイドルトリガーおよびアイドル条件と組み合わせて使用されます。詳細については、タスクのアイドル条件を参照してください。アイドルトリガーは、スケジュールされた時刻に関連付けられないイベントベースのトリガーです。これに対して、アイドル条件はタスクのスケジュールされた開始時刻に関連付けられます。

アイドルトリガーを指定するには、 TASK_TRIGGER の TASK_TRIGGER_TYPE メンバーを TASK_EVENT_TRIGGER_ON_IDLE に設定します。アイドルトリガーは、システムが wIdleMinutes で指定された時間だけアイドル状態になったときに発生します。

アイドル条件を設定するには、 IScheduledWorkItem::SetFlags を呼び出します。TASK_FLAG_START_ONLY_IF_IDLE フラグが設定されている場合、作業項目はシステムが wIdleMinutes で指定された時間だけアイドル状態になった場合にのみ、スケジュールされた時刻に実行されます。タスクスケジューラサービスは、システムがアイドル状態になるかどうかを確認するために、スケジュールされた開始時刻から wDeadlineMinutes で指定された分数まで待機します。

アプリケーションは、アイドル待機間隔を更新するために SetIdleWait を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

例

アイドルトリガーを作成する際にアイドル待機時間を設定する方法の例については、アイドルトリガーの作成例を参照してください。

vtbl 11 HRESULT GetIdleWait(WORD* pwIdleMinutes, WORD* pwDeadlineMinutes)

作業項目のアイドル待機時間を取得します。

pwIdleMinutes	WORD*	out	現在の作業項目のアイドル待機時間 (分) を格納する WORD へのポインター。
pwDeadlineMinutes	WORD*	out	タスクスケジューラが pwIdleMinutes で返されるアイドル時間の期間を待機する最大の分数を指定する WORD へのポインター。

戻り値

GetIdleWait メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。

解説(Remarks)

ここで返されるアイドル時間は、アイドルトリガーおよびアイドル条件と組み合わせて使用されます。アイドルトリガーは、スケジュールされた時刻に関連付けられないイベントベースのトリガーです。アイドル条件はタスクのスケジュールされた開始時刻に関連付けられます。

アイドルトリガーを指定するには、 TASK_TRIGGER 構造体の TASK_TRIGGER_TYPE メンバーに値 TASK_EVENT_TRIGGER_ON_IDLE を設定します。アイドルトリガーは、システムが pwIdleMinutes で返される時間だけアイドル状態になったときに発生します。

アイドル条件は、 IScheduledWorkItem::SetFlags を呼び出して設定できます。TASK_FLAG_START_ONLY_IF_IDLE フラグが設定されている場合、作業項目はシステムが pwIdleMinutes で返される時間だけアイドル状態になった場合にのみ、スケジュールされた時刻に実行されます。タスクスケジューラサービスは、システムがアイドル状態になるかどうかを確認するために、スケジュールされた開始時刻から pwDeadlineMinutes まで待機します。

例

タスクのアイドル待機時間を取得する方法の例については、C/C++ コード例: タスクのアイドル待機時間の取得を参照してください。

vtbl 12 HRESULT Run()

作業項目を実行するようタスクスケジューラサービスに要求を送信します。

戻り値

Run メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。要求は送信されました。詳細については、「解説」を参照してください。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

Run は非同期操作です。S_OK のリターンコードは、作業項目を実行する要求が行われたことを意味し、作業項目が実行を開始したことを意味するものではありません。 Run が戻ってから作業項目が実際に実行を開始するまでに、数秒の遅延が生じることがあります。

作業項目が実行中かどうかを判断するには、 IScheduledWorkItem::GetStatus を呼び出します。

例

タスクを開始する方法の例については、タスクの開始例を参照してください。

vtbl 13 HRESULT Terminate()

このメソッドは、作業項目の実行を終了します。

戻り値

Terminate メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

Terminate メソッドは非同期に動作します。リターン値を返す前に、タスクが終了するのを待機しません。

WM_CLOSE メッセージを送信できない場合 (たとえば、アプリケーションにウィンドウがない場合)、またはアプリケーションが WM_CLOSE を受信してから 3 分以内に終了しなかった場合、タスクスケジューラは TerminateProcess を使用してアプリケーションを終了します。

例

タスクの状態を取得してタスクを終了する方法の例については、タスクの終了例を参照してください。

vtbl 14 HRESULT EditWorkItem(HWND hParent, DWORD dwReserved)

作業項目の [タスク]、[スケジュール]、[設定] のプロパティページを表示し、ユーザーがそれらのページでプロパティを設定できるようにします。

hParent	HWND	in	将来の使用のために予約されています。このパラメーターには NULL を設定してください。
dwReserved	DWORD	in	内部使用のために予約されています。このパラメーターには 0 を設定する必要があります。

戻り値

EditWorkItem メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
STG_E_NOTFILEBASEDSTORAGE	作業項目オブジェクトは永続的ではありません。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

vtbl 15 HRESULT GetMostRecentRunTime(SYSTEMTIME* pstLastRun)

作業項目が最後に実行を開始した時刻を取得します。

pstLastRun

SYSTEMTIME*

out

現在の作業項目が最後に実行された時刻を格納する SYSTEMTIME 構造体へのポインター。

戻り値

GetMostRecentRunTime メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
SCHED_S_TASK_HAS_NOT_RUN	作業項目は一度も実行されていません。

vtbl 16 HRESULT GetStatus(HRESULT* phrStatus)

作業項目の状態を取得します。

phrStatus

HRESULT*

out

戻り時に次のいずれかの値を格納する HRESULT 値へのポインター。

SCHED_S_TASK_READY

作業項目は、次にスケジュールされた時刻に実行できる状態です。

SCHED_S_TASK_RUNNING

作業項目は現在実行中です。

SCHED_S_TASK_NOT_SCHEDULED

このタスクをスケジュールに従って実行するために必要なプロパティの 1 つ以上が設定されていません。

SCHED_S_TASK_HAS_NOT_RUN

タスクは実行されていません。この値は、タスクが次にスケジュールされた時刻に実行できる状態であっても、またタスクが繰り返し実行されるタスクであっても、タスクが実行されていない場合には常に返されます。

SCHED_S_TASK_DISABLED

タスクは無効になっているため、スケジュールされた時刻には実行されません。

SCHED_S_TASK_NO_MORE_RUNS

このタスクに対してこれ以上スケジュールされた実行はありません。

SCHED_S_TASK_NO_VALID_TRIGGERS

タスクにトリガーがないか、既存のトリガーが無効になっているか設定されていません。

戻り値

GetStatus メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。要求は送信されました。詳細については、「解説」を参照してください。
E_INVALIDARG	引数が無効です。

解説(Remarks)

IScheduledWorkItem インターフェイスのメソッドは、 ITask インターフェイスに継承されます。そのため、 IScheduledWorkItem::GetStatus は通常 ITask インターフェイスを通じて呼び出されます。

IScheduledWorkItem::GetStatus は、タスクの状態を動的に取得しません。更新された状態を取得するために使用する新しい IScheduledWorkItem インターフェイスを取得するには、ITaskScheduler::Activate を呼び出す必要があります。詳細については、ITaskScheduler::Activate の例を参照してください。

例

タスクの状態を取得する方法の例については、C/C++ コード例: タスクの状態の取得を参照してください。

タスクの終了の一環としてタスクの状態を取得する方法の例については、タスクの終了例を参照してください。

vtbl 17 HRESULT GetExitCode(DWORD* pdwExitCode)

作業項目に関連付けられた実行可能ファイルが前回の実行時に返した最後の終了コードを取得します。このメソッドは、タスクスケジューラが最後に作業項目の実行を試みたときにタスクスケジューラに返された終了コードも返します。

pdwExitCode

DWORD*

out

作業項目の最後の終了コードが設定される DWORD 値へのポインター。これは、作業項目が最後に実行を停止したときに返した終了コードです。作業項目が一度も開始されていない場合は、0 が返されます。

戻り値

GetExitCode メソッドは、作業項目を最後に開始しようとしたときのエラーを返します。可能な値には次のものがあります。

リターンコード	説明
S_OK	作業項目を開始する試みは成功しました。
SCHED_S_TASK_HAS_NOT_RUN	この作業項目を開始する試みは一度も行われていません。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

このメソッドは、次の 2 つの情報を返すことができます。

スケジュールされている実行可能ファイルが返すエラーまたは終了コードは、pdwExitCode パラメーターで返されます。
タスクスケジューラがジョブを開始しようとしたときに受け取ったエラーコードは、 GetExitCode メソッドの呼び出し自体で返されます。

更新されたエラーコードを取得するには、必ず最初に ITaskScheduler::Activate を呼び出して新しい IScheduledWorkItem インターフェイスを取得し、それを使用して更新されたエラーコードを取得します。

例

タスクの作成者を取得する方法の例については、C/C++ コード例: タスクの終了コードの取得を参照してください。

vtbl 18 HRESULT SetComment(LPWSTR pwszComment)

作業項目のコメントを設定します。

pwszComment

LPWSTR

現在の作業項目のコメントを指定する、null で終わる文字列。

戻り値

SetComment メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

作業項目のコメントを設定した後は、必ず IPersistFile::Save を呼び出して、変更した作業項目オブジェクトをディスクに保存してください。

例

タスクのコメントを設定する方法の例については、C/C++ コード例: タスクのコメントの設定を参照してください。

vtbl 19 HRESULT GetComment(LPWSTR* ppwszComment)

作業項目のコメントを取得します。

ppwszComment

LPWSTR*

out

現在の作業項目について取得したコメントを格納する、null で終わる文字列へのポインター。

戻り値

GetComment メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

vtbl 20 HRESULT SetCreator(LPWSTR pwszCreator)

作業項目の作成者の名前を設定します。

pwszCreator

LPWSTR

作業項目の作成者の名前を格納する、null で終わる文字列。

戻り値

SetCreator メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

プログラムは、作成者を更新するために SetCreator を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

vtbl 21 HRESULT GetCreator(LPWSTR* ppwszCreator)

作業項目の作成者の名前を取得します。

ppwszCreator

LPWSTR*

out

現在の作業項目の作成者の名前を格納する、null で終わる文字列へのポインター。 GetCreator を呼び出すアプリケーションは、CoTaskMemFree 関数を使用してこの文字列を解放する責任があります。

戻り値

GetCreator メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

vtbl 22 HRESULT SetWorkItemData(WORD cbData, BYTE* rgbData)

このメソッドは、作業項目に関連付けられたアプリケーション定義のデータを格納します。

cbData	WORD	in	データバッファーのバイト数。このメモリの割り当てと解放は呼び出し元が行います。
rgbData	BYTE*	in	コピーするデータ。

戻り値

SetWorkItemData メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

データは IScheduledWorkItem::GetWorkItemData を呼び出して取得できます。

プログラムは、作業項目のデータを更新するために SetWorkItemData を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

vtbl 23 HRESULT GetWorkItemData(WORD* pcbData, BYTE** prgbData)

作業項目に関連付けられたアプリケーション定義のデータを取得します。

pcbData	WORD*	out	コピーされたバイト数へのポインター。
prgbData	BYTE**	out	現在の作業項目のユーザー定義データを格納する BYTE へのポインターへのポインター。 GetWorkItemData を呼び出すメソッドは、CoTaskMemFree を使用してこのメモリを解放する責任があります。

戻り値

GetWorkItemData メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

作業項目のデータを取得しても、作業項目の動作にはいかなる影響も与えません。

vtbl 24 HRESULT SetErrorRetryCount(WORD wRetryCount)

エラーが発生した場合にタスクスケジューラが作業項目の再実行を試みる回数を設定します。このメソッドは実装されていません。

wRetryCount

WORD

現在の作業項目のエラー時の再試行回数を指定する値。

戻り値

SetErrorRetryCount メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
E_NOTIMPL	実装されていません。

解説(Remarks)

プログラムは、エラー時の再試行回数を更新するために SetErrorRetryCount を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

vtbl 25 HRESULT GetErrorRetryCount(WORD* pwRetryCount)

エラーが発生した場合にタスクスケジューラが操作を再試行する回数を取得します。このメソッドは実装されていません。

pwRetryCount

WORD*

out

再試行する回数を格納する WORD へのポインター。

戻り値

実装されていません。

vtbl 26 HRESULT SetErrorRetryInterval(WORD wRetryInterval)

エラーが発生した後にタスクスケジューラが作業項目の実行を試みる間隔 (分) を設定します。このメソッドは実装されていません。

wRetryInterval

WORD

現在の作業項目のエラー時の再試行間隔 (分) を指定する値。

戻り値

SetErrorRetryInterval メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
E_NOTIMPL	実装されていません。

解説(Remarks)

プログラムは、エラー時の再試行間隔を更新するために SetErrorRetryInterval を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

vtbl 27 HRESULT GetErrorRetryInterval(WORD* pwRetryInterval)

エラーが発生した場合にタスクスケジューラが作業項目の実行を試みる間隔 (分) を取得します。このメソッドは実装されていません。

pwRetryInterval

WORD*

out

現在の作業項目の再試行間の時間間隔を格納する WORD 値へのポインター。

戻り値

GetErrorRetryInterval メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
E_NOTIMPL	実装されていません。

vtbl 28 HRESULT SetFlags(DWORD dwFlags)

任意の種類の作業項目の動作を変更するフラグを設定します。

dwFlags

DWORD

次のフラグの 1 つ以上の組み合わせを指定する値。

TASK_FLAG_INTERACTIVE

このフラグは、Windows NT AT サービスのジョブを作業項目に変換する際に使用されます。Windows NT AT サービスのジョブとは、Windows NT Schedule サービス用のジョブを作成するために使用される Windows NT のコマンドラインユーティリティ At.exe を指します。タスクスケジューラサービスは Schedule サービスを置き換えるもので、これと下位互換性があります。変換は、タスクスケジューラが Windows NT/Windows 2000 にインストールされるとき (たとえば Internet Explorer 4.0 をインストールする場合や Windows 2000 にアップグレードする場合) に行われます。セットアップ処理中に、タスクスケジューラのインストールコードは AT サービス用に作成されたジョブをレジストリから検索し、同じ操作を実行する作業項目を作成します。

このような変換されたジョブでは、作業項目をユーザーに表示することが意図されている場合に対話フラグが設定されます。このフラグが設定されていない場合、[タスク] フォルダーに作業項目は表示されず、作業項目の実行時にその作業項目に関連付けられたユーザーインターフェイスもユーザーに提示されません。

TASK_FLAG_DELETE_WHEN_DONE

スケジュールされた実行時刻がなくなると、作業項目は削除されます。

TASK_FLAG_DISABLED

作業項目は無効になっています。これは、作業項目がスケジュールされた時刻に実行されるのを一時的に防ぐのに便利です。

TASK_FLAG_HIDDEN

作成された作業項目は非表示になります。

TASK_FLAG_RUN_ONLY_IF_LOGGED_ON

作業項目は、 IScheduledWorkItem::SetAccountInformation で指定されたユーザーが対話的にログオンしている場合にのみ実行されます。このフラグは、ローカルアカウントで実行するよう設定された作業項目には影響しません。

TASK_FLAG_START_ONLY_IF_IDLE

作業項目は、スケジュールされた開始時刻にコンピューターが使用中でない場合にのみ開始されます。

TASK_FLAG_SYSTEM_REQUIRED

作業項目は、システムがバッテリ電源で動作している場合に、システムを再開 (ウェイクアップ) させます。このフラグは、再開タイマーをサポートするシステムでのみサポートされます。

TASK_FLAG_KILL_ON_IDLE_END

作業項目は、実行中にコンピューターがアイドル状態から非アイドル状態に遷移した場合に終了します。コンピューターは、ユーザー入力がないまま IdleWait トリガーの時間が経過するまではアイドル状態とは見なされません。アイドルトリガーについては、アイドルトリガーを参照してください。

TASK_FLAG_RESTART_ON_IDLE_RESUME

作業項目は、そのすべての task_triggers が経過する前にコンピューターが非アイドル状態からアイドル状態に遷移した場合に再び開始されます。(このフラグは TASK_FLAG_KILL_ON_IDLE_END と組み合わせて使用してください。)

TASK_FLAG_DONT_START_IF_ON_BATTERIES

作業項目は、対象のコンピューターがバッテリ電源で動作している場合には開始されません。

TASK_FLAG_KILL_IF_GOING_ON_BATTERIES

作業項目の対象コンピューターがバッテリ電源に切り替わると、作業項目は終了し、関連付けられたアプリケーションも終了します。

TASK_FLAG_RUN_IF_CONNECTED_TO_INTERNET

作業項目は、現在有効なインターネット接続がある場合にのみ実行されます。

注意この機能は現在実装されていません。

戻り値

SetFlags メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

プログラムは、フラグを更新するために SetFlags を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

このメソッドは、任意の種類のスケジュールされた作業項目で使用されるフラグを設定するために使用されます。これに対して、 ITask::SetTaskFlags は、スケジュールされたタスクで使用されるフラグの設定にのみ使用されます。

vtbl 29 HRESULT GetFlags(DWORD* pdwFlags)

任意の種類の作業項目の動作を変更するフラグを取得します。

pdwFlags

DWORD*

out

作業項目のフラグを格納する DWORD へのポインター。これらのフラグの一覧については、 SetFlags を参照してください。

戻り値

GetFlags メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。

解説(Remarks)

このメソッドは、任意の種類のスケジュールされた作業項目で使用されるフラグを取得するために使用されます。これに対して、 ITask::GetTaskFlags は、スケジュールされたタスクで使用されるフラグの取得にのみ使用されます。

vtbl 30 HRESULT SetAccountInformation(LPWSTR pwszAccountName, LPWSTR pwszPassword)

作業項目の実行に使用するアカウント名とパスワードを設定します。

pwszAccountName

LPWSTR

作業項目を実行するユーザーアカウントの、null で終わる名前を格納する文字列。ローカルシステムアカウントを指定するには、空文字列 L"" を使用します。ローカルシステムアカウントを指定するのに、これ以外の文字列を使用しないでください。詳細については、「解説」を参照してください。

pwszPassword

LPWSTR

pwszAccountName で指定したアカウントのパスワードを格納する文字列。

ローカルシステムアカウントを指定する場合は、このパラメーターを NULL に設定します。TASK_FLAG_RUN_ONLY_IF_LOGGED_ON フラグを設定する場合は、ローカルまたはドメインのユーザーアカウントについても pwszPassword を NULL に設定できます。このフラグを設定するには IScheduledWorkItem::SetFlags メソッドを使用します。

タスクスケジューラは、同じアカウントを使用するすべてのタスクについて、アカウント情報を 1 回だけ格納します。あるタスクでアカウントのパスワードが更新されると、同じアカウントを使用するすべてのタスクが更新後のパスワードを使用します。

パスワードの使用が終わったら、SecureZeroMemory 関数を呼び出してパスワード情報をクリアしてください。パスワードの保護の詳細については、パスワードの取り扱いを参照してください。

戻り値

SetAccountInformation メソッドは、次のいずれかの値を返します。この呼び出しによるエラーは、後続の IPersistFile::Save の呼び出しによって返されることもある点に注意してください。

リターンコード	説明
S_OK	操作は成功しました。
E_ACCESSDENIED	呼び出し元にこの操作を実行する権限がありません。詳細については、「解説」を参照してください。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
SCHED_E_NO_SECURITY_SERVICES	セキュリティサービスは、Windows Server 2003、Windows XP、および Windows 2000 でのみ利用できます。
SCHED_E_UNSUPPORTED_ACCOUNT_OPTION	pwszPassword パラメーターが NULL に設定されましたが、TASK_FLAG_RUN_ONLY_IF_LOGGED_ON フラグが設定されていませんでした。
SCHED_E_ACCOUNT_INFORMATION_NOT_SET	pwszPassword パラメーターが正しくありませんでした。Windows Server 2003 では、タスクスケジューラはジョブの作成時 (IPersistFile::Save の呼び出し時) にパスワードを検証します。このエラーが発生しても、ジョブファイルは作成される点に注意してください。

解説(Remarks)

このメソッドは、Windows Server 2003、Windows XP、および Windows 2000 を対象としています。

pwszAccountName がローカルシステムアカウントを指定する場合、呼び出し元はローカルコンピューターの管理者であるか、ローカルシステムアカウントで実行されているアプリケーションである必要があります。そうでない場合、このメソッドは失敗します。

pwszPassword で指定したパスワードは、作業項目の実行時にアカウントへログオンするために使用されます。パスワードが正しくないと、作業項目の実行時にエラーになります。ただし Windows Server 2003 では、タスクスケジューラはジョブの作成時 (IPersistFile::Save の呼び出し時) にパスワードを検証します。

通常、パスワードには有効期限があります。無期限に実行されるタスクをスケジュールする場合は、新しいパスワードを反映するようにタスクを更新する必要があります。

エラーは、最初の SetAccountInformation の呼び出し、または後続の IPersistFile::Save の呼び出しのいずれからも返される可能性がある点に注意してください。

この呼び出しが成功するには、タスクスケジューラサービスが実行されている必要があります。(SetAccountInformation はタスクスケジューラサービスへのリモートプロシージャコール (RPC) を発生させますが、その RPC 呼び出しは IPersistFile::Save が呼び出されるまで行われません。)

E_ACCESSDENIED のリターンコードは、次の条件で返されます。

呼び出し元が、スケジュールされた作業項目を表すファイルへの書き込みアクセス権を持っていない。
ローカルアカウントが指定された (pwszAccountName が L"" に設定された) が、呼び出し元がローカルコンピューターの管理者でも、ローカルシステムアカウントで実行されているアプリケーションでもない。
pwszPassword に NULL のパスワードが指定されたが、呼び出し元がローカルコンピューターの管理者でも、ローカルシステムアカウントで実行されているものでもない。
アプリケーションが、pwszAccountName パラメーターで指定されたユーザー名とは異なるユーザー名で実行されている。

作業項目のアカウント情報を設定した後は、必ず IPersistFile::Save を呼び出して、変更した作業項目オブジェクトをディスクに保存してください。

例

タスクのアカウント情報を設定する方法の詳細と例については、C/C++ コード例: タスクのアカウント情報の設定を参照してください。

vtbl 31 HRESULT GetAccountInformation(LPWSTR* ppwszAccountName)

作業項目のアカウント名を取得します。

ppwszAccountName

LPWSTR*

out

現在の作業項目のアカウント名を格納する、null で終わる文字列へのポインター。ローカルシステムアカウントの場合は空文字列 L"" が返されます。

アカウント名の処理が終わったら、必ず CoTaskMemFree を呼び出して文字列を解放してください。

戻り値

GetAccountInformation メソッドは、次のいずれかの値を返します。

リターンコード	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
SCHED_E_ACCOUNT_INFORMATION_NOT_SET	作業項目のアカウント情報が設定されていません。
SCHED_E_NO_SECURITY_SERVICES	セキュリティサービスは、Windows Server 2003、Windows 2000、および Windows XP オペレーティングシステムでのみ利用できます。

解説(Remarks)

GetAccountInformation メソッドは、Windows Server 2003、Windows XP、および Windows 2000 オペレーティングシステムを対象としています。

例

タスクのアカウント情報を取得する方法の詳細と例については、C/C++ コード例: タスクのアカウント情報の取得を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IScheduledWorkItem "{A6B952F0-A4B1-11D0-997D-00AA006887EC}"
#usecom global IScheduledWorkItem IID_IScheduledWorkItem "{}"
#comfunc global IScheduledWorkItem_CreateTrigger          3 var,sptr
#comfunc global IScheduledWorkItem_DeleteTrigger          4 int
#comfunc global IScheduledWorkItem_GetTriggerCount        5 var
#comfunc global IScheduledWorkItem_GetTrigger             6 int,sptr
#comfunc global IScheduledWorkItem_GetTriggerString       7 int,var
#comfunc global IScheduledWorkItem_GetRunTimes            8 var,var,var,var
#comfunc global IScheduledWorkItem_GetNextRunTime         9 var
#comfunc global IScheduledWorkItem_SetIdleWait            10 int,int
#comfunc global IScheduledWorkItem_GetIdleWait            11 var,var
#comfunc global IScheduledWorkItem_Run                    12
#comfunc global IScheduledWorkItem_Terminate              13
#comfunc global IScheduledWorkItem_EditWorkItem           14 sptr,int
#comfunc global IScheduledWorkItem_GetMostRecentRunTime   15 var
#comfunc global IScheduledWorkItem_GetStatus              16 var
#comfunc global IScheduledWorkItem_GetExitCode            17 var
#comfunc global IScheduledWorkItem_SetComment             18 wstr
#comfunc global IScheduledWorkItem_GetComment             19 var
#comfunc global IScheduledWorkItem_SetCreator             20 wstr
#comfunc global IScheduledWorkItem_GetCreator             21 var
#comfunc global IScheduledWorkItem_SetWorkItemData        22 int,var
#comfunc global IScheduledWorkItem_GetWorkItemData        23 var,var
#comfunc global IScheduledWorkItem_SetErrorRetryCount     24 int
#comfunc global IScheduledWorkItem_GetErrorRetryCount     25 var
#comfunc global IScheduledWorkItem_SetErrorRetryInterval  26 int
#comfunc global IScheduledWorkItem_GetErrorRetryInterval  27 var
#comfunc global IScheduledWorkItem_SetFlags               28 int
#comfunc global IScheduledWorkItem_GetFlags               29 var
#comfunc global IScheduledWorkItem_SetAccountInformation  30 wstr,wstr
#comfunc global IScheduledWorkItem_GetAccountInformation  31 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IScheduledWorkItem "{A6B952F0-A4B1-11D0-997D-00AA006887EC}"
#usecom global IScheduledWorkItem IID_IScheduledWorkItem "{}"
#comfunc global IScheduledWorkItem_CreateTrigger          3 sptr,sptr
#comfunc global IScheduledWorkItem_DeleteTrigger          4 int
#comfunc global IScheduledWorkItem_GetTriggerCount        5 sptr
#comfunc global IScheduledWorkItem_GetTrigger             6 int,sptr
#comfunc global IScheduledWorkItem_GetTriggerString       7 int,sptr
#comfunc global IScheduledWorkItem_GetRunTimes            8 sptr,sptr,sptr,sptr
#comfunc global IScheduledWorkItem_GetNextRunTime         9 sptr
#comfunc global IScheduledWorkItem_SetIdleWait            10 int,int
#comfunc global IScheduledWorkItem_GetIdleWait            11 sptr,sptr
#comfunc global IScheduledWorkItem_Run                    12
#comfunc global IScheduledWorkItem_Terminate              13
#comfunc global IScheduledWorkItem_EditWorkItem           14 sptr,int
#comfunc global IScheduledWorkItem_GetMostRecentRunTime   15 sptr
#comfunc global IScheduledWorkItem_GetStatus              16 sptr
#comfunc global IScheduledWorkItem_GetExitCode            17 sptr
#comfunc global IScheduledWorkItem_SetComment             18 wstr
#comfunc global IScheduledWorkItem_GetComment             19 sptr
#comfunc global IScheduledWorkItem_SetCreator             20 wstr
#comfunc global IScheduledWorkItem_GetCreator             21 sptr
#comfunc global IScheduledWorkItem_SetWorkItemData        22 int,sptr
#comfunc global IScheduledWorkItem_GetWorkItemData        23 sptr,sptr
#comfunc global IScheduledWorkItem_SetErrorRetryCount     24 int
#comfunc global IScheduledWorkItem_GetErrorRetryCount     25 sptr
#comfunc global IScheduledWorkItem_SetErrorRetryInterval  26 int
#comfunc global IScheduledWorkItem_GetErrorRetryInterval  27 sptr
#comfunc global IScheduledWorkItem_SetFlags               28 int
#comfunc global IScheduledWorkItem_GetFlags               29 sptr
#comfunc global IScheduledWorkItem_SetAccountInformation  30 wstr,wstr
#comfunc global IScheduledWorkItem_GetAccountInformation  31 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。