ITask

COM

IID148bd524-a2ab-11ce-b11f-00aa00530503継承元IScheduledWorkItem自前メソッド開始 vtbl32

公式ドキュメント

タスクの実行、タスク情報の取得や設定、タスクの終了を行うメソッドを提供します。IScheduledWorkItem インターフェイスから派生しており、そのインターフェイスのすべてのメソッドを継承しています。

解説(Remarks)

ITask はタスクトリガーオブジェクトの主要なインターフェイスです。タスクオブジェクトを作成するには、既存のタスクの場合は ITaskScheduler::Activate を、新しいタスクの場合は ITaskScheduler::NewWorkItem を呼び出します。

例

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

メソッド 12

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

vtbl 32 HRESULT SetApplicationName(LPWSTR pwszApplicationName)

このメソッドは、特定のアプリケーションを現在のタスクに割り当てます。

pwszApplicationName

LPWSTR

タスクに関連付けるアプリケーションの名前を格納した、null 終端文字列。アプリケーション名をクリアするには空の文字列を使用します。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

解説(Remarks)

アプリケーションのパスを指定しない場合、Task Scheduler は環境変数のパスを検索して正しいパスを見つけます。アプリケーション名でプログラムを指定する場合、Task Scheduler のユーザーインターフェイスがアプリケーションのアイコンを正しく表示できるように、名前には .exe 拡張子を使用してください。

SetApplicationName を呼び出した後は、変更したタスクをディスクに保存するために必ず IPersistFile::Save を呼び出してください。

例

アプリケーション名を設定する方法の例については、C/C++ コード例: アプリケーション名の設定を参照してください。

vtbl 33 HRESULT GetApplicationName(LPWSTR* ppwszApplicationName)

このメソッドは、タスクに関連付けられているアプリケーションの名前を取得します。

ppwszApplicationName

LPWSTR*

out

現在のタスクに関連付けられているアプリケーションの名前を格納した、null 終端文字列へのポインター。この名前を処理した後は、CoTaskMemFree を呼び出してリソースを解放してください。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

vtbl 34 HRESULT SetParameters(LPWSTR pwszParameters)

このメソッドは、タスクのコマンドライン引数を設定します。

pwszParameters

LPWSTR

タスクの引数を格納した null 終端文字列。これらの引数は、タスクが実行するアプリケーションにコマンドライン引数として渡されます。コマンドライン引数プロパティをクリアするには、pwszParameters を L"" に設定します。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

解説(Remarks)

タスクにアプリケーションが関連付けられている場合、このメソッドで設定されたタスク引数は無視されます。

タスクの引数を設定した後は、変更したタスクオブジェクトをディスクに保存するために必ず IPersistFile::Save を呼び出してください。

例

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

vtbl 35 HRESULT GetParameters(LPWSTR* ppwszParameters)

このメソッドは、タスクのコマンドライン引数を取得します。

ppwszParameters

LPWSTR*

out

タスクのコマンドライン引数を格納した、null 終端文字列へのポインター。 GetParameters を呼び出したメソッドは、CoTaskMemFree 関数を使用してこの文字列を解放する責任があります。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

vtbl 36 HRESULT SetWorkingDirectory(LPWSTR pwszWorkingDirectory)

このメソッドは、タスクの作業ディレクトリを設定します。

pwszWorkingDirectory

LPWSTR

タスクの作業ディレクトリへのディレクトリパスを格納した null 終端文字列。

アプリケーションは、このディレクトリを現在の作業ディレクトリとして起動します。ディレクトリをクリアするには、pwszWorkingDirectory を L"" に設定します。作業ディレクトリが L"" に設定されている場合、アプリケーションの実行時に、現在のディレクトリはタスクスケジューラサービスの実行可能ファイルである Mstask.exe が存在するディレクトリになります。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

解説(Remarks)

タスクの作業ディレクトリを設定した後は、変更したタスクオブジェクトをディスクに保存するために必ず IPersistFile::Save を呼び出してください。

例

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

vtbl 37 HRESULT GetWorkingDirectory(LPWSTR* ppwszWorkingDirectory)

このメソッドは、タスクの作業ディレクトリを取得します。

ppwszWorkingDirectory

LPWSTR*

out

タスクの作業ディレクトリを格納した、null 終端文字列へのポインター。 GetWorkingDirectory を呼び出したアプリケーションは、CoTaskMemFree 関数を使用してこの文字列を解放する責任があります。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

vtbl 38 HRESULT SetPriority(DWORD dwPriority)

このメソッドは、タスクの優先度を設定します。

dwPriority

DWORD

現在のタスクの優先度を指定する DWORD。タスクの優先度は、プロセスに割り当てられるタイムスライスの頻度と長さを決定します。これは Windows Server 2003、Windows XP、および Windows 2000 オペレーティングシステムにのみ適用されます。これらの値は CreateProcess の優先度クラスから取られており、次のいずれかのフラグを指定できます(スレッドスケジューリングの優先度が高い順):

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。

解説(Remarks)

タスクの優先度を設定した後は、変更したタスクオブジェクトをディスクに保存するために IPersistFile::Save を呼び出してください。

例

タスクの優先度を設定する方法の詳細と例については、C/C++ コード例: タスク優先度の設定を参照してください。

vtbl 39 HRESULT GetPriority(DWORD* pdwPriority)

このメソッドは、タスクの優先度を取得します。

pdwPriority

DWORD*

out

現在のタスクの優先度を格納した DWORD へのポインター。優先度の値は、プロセスに割り当てられるタイムスライスの頻度と長さを決定します。これは Windows Server 2003、Windows XP、および Windows 2000 オペレーティングシステムにのみ適用されます。この値は CreateProcess の優先度クラスから取られており、次のいずれかのフラグになります(スレッドスケジューリングの優先度が高い順):

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

vtbl 40 HRESULT SetTaskFlags(DWORD dwFlags)

このメソッドは、スケジュールされたタスクの動作を変更するフラグを設定します。

dwFlags

DWORD

現在、スケジュールされたタスクに対して定義されているフラグはありません。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

解説(Remarks)

アプリケーションは、タスクフラグを更新するために、 SetTaskFlags を呼び出した後に IPersistFile::Save メソッドを呼び出す必要があります。

このメソッドは、スケジュールされたタスクにのみ適用されるフラグを設定するために設計されています。一方、 IScheduledWorkItem::SetFlags は、あらゆる種類のスケジュールされた作業項目に適用されるフラグを設定するために使用されます。

vtbl 41 HRESULT GetTaskFlags(DWORD* pdwFlags)

このメソッドは、タスクの動作を変更するフラグを返します。

pdwFlags

DWORD*

out

現在、スケジュールされたタスクに対して定義されているフラグはありません。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

このメソッドは、スケジュールされたタスクにのみ適用されるフラグを取得するために設計されています。一方、 IScheduledWorkItem::GetFlags は、あらゆる種類のスケジュールされた作業項目に適用されるフラグを取得するために使用されます。

vtbl 42 HRESULT SetMaxRunTime(DWORD dwMaxRunTimeMS)

このメソッドは、タスクが終了するまでに実行できる最大時間をミリ秒単位で設定します。

dwMaxRunTimeMS

DWORD

タスクの最大実行時間(ミリ秒単位)を指定する DWORD 値。無制限の時間を指定するには、このパラメーターを INFINITE に設定できます。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

解説(Remarks)

最大実行時間を超えると、Task Scheduler はタスクに関連付けられたアプリケーションの終了を試みます。WM_CLOSE メッセージを送信できない場合(たとえばアプリケーションにウィンドウがない場合)、またはアプリケーションが WM_CLOSE の受信から 3 分以内に終了しない場合、Task Scheduler は TerminateProcess を使用してアプリケーションを終了します。

最大実行時間を設定した後は、変更したタスクオブジェクトをディスクに保存するために必ず IPersistFile::Save を呼び出してください。

例

最大実行時間を設定する方法の例については、C/C++ コード例: MaxRunTime の設定を参照してください。

vtbl 43 HRESULT GetMaxRunTime(DWORD* pdwMaxRunTimeMS)

このメソッドは、タスクが終了するまでに実行できる最大の時間の長さをミリ秒単位で取得します。

pdwMaxRunTimeMS

DWORD*

out

現在のタスクの最大実行時間を格納した DWORD へのポインター。

タスクの実行中に最大実行時間に達すると、Task Scheduler はまず関連付けられたアプリケーションに WM_CLOSE メッセージを送信します。アプリケーションが 3 分以内に終了しない場合は、TerminateProcess が実行されます。

戻り値

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

戻り値	説明
S_OK	操作は成功しました。
E_INVALIDARG	引数が無効です。
E_OUTOFMEMORY	十分なメモリがありません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITask "{148BD524-A2AB-11CE-B11F-00AA00530503}"
#usecom global ITask IID_ITask "{}"
#comfunc global ITask_SetApplicationName   32 wstr
#comfunc global ITask_GetApplicationName   33 var
#comfunc global ITask_SetParameters        34 wstr
#comfunc global ITask_GetParameters        35 var
#comfunc global ITask_SetWorkingDirectory  36 wstr
#comfunc global ITask_GetWorkingDirectory  37 var
#comfunc global ITask_SetPriority          38 int
#comfunc global ITask_GetPriority          39 var
#comfunc global ITask_SetTaskFlags         40 int
#comfunc global ITask_GetTaskFlags         41 var
#comfunc global ITask_SetMaxRunTime        42 int
#comfunc global ITask_GetMaxRunTime        43 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ITask "{148BD524-A2AB-11CE-B11F-00AA00530503}"
#usecom global ITask IID_ITask "{}"
#comfunc global ITask_SetApplicationName   32 wstr
#comfunc global ITask_GetApplicationName   33 sptr
#comfunc global ITask_SetParameters        34 wstr
#comfunc global ITask_GetParameters        35 sptr
#comfunc global ITask_SetWorkingDirectory  36 wstr
#comfunc global ITask_GetWorkingDirectory  37 sptr
#comfunc global ITask_SetPriority          38 int
#comfunc global ITask_GetPriority          39 sptr
#comfunc global ITask_SetTaskFlags         40 int
#comfunc global ITask_GetTaskFlags         41 sptr
#comfunc global ITask_SetMaxRunTime        42 int
#comfunc global ITask_GetMaxRunTime        43 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。