IRegisteredTask
COMIDispatch (デュアル)comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。公式ドキュメント
タスクを即座に実行する、タスクの実行中インスタンスを取得する、タスクの登録に使用する資格情報を取得または設定する、およびタスクを記述するプロパティを取得するために使用するメソッドを提供します。
メソッド 18
vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。
登録済みタスクの名前を取得します。
| pName | LPWSTR* | out | 登録済みタスクの名前を受け取る出力ポインタである。SysFreeString で解放する。 |
登録済みタスクが格納されている場所へのパスを取得します。
| pPath | LPWSTR* | out | 登録済みタスクのパスを受け取る出力ポインタである。SysFreeString で解放する。 |
登録済みタスクの動作状態を取得します。
| pState | TASK_STATE* | out | 登録済みタスクの現在の状態を表す TASK_STATE 値を受け取る変数へのポインタである。 |
登録済みタスクが有効かどうかを示すブール値を取得または設定します。(Get)
| pEnabled | VARIANT_BOOL* | out | タスクが有効かどうかを受け取る VARIANT_BOOL へのポインタである。 |
解説(Remarks)
このプロパティは VARIANT_BOOL 型で、true 値を指定するには -1 を、false を表すには 0 を使用します。-1 または 0 以外の値を使用してもエラーは返されません。
登録済みタスクが有効かどうかを示すブール値を取得または設定します。(Put)
| enabled | VARIANT_BOOL | in | タスクの有効・無効を指定する VARIANT_BOOL である。 |
解説(Remarks)
このプロパティは VARIANT_BOOL 型で、true 値を指定するには -1 を、false を表すには 0 を使用します。-1 または 0 以外の値を使用してもエラーは返されません。
登録済みタスクを即座に実行します。
| params | VARIANT | in | タスクアクションで値として使用されるパラメーターです。タスクアクションにパラメーター値を指定しない場合は、このパラメーターを VT_NULL または VT_EMPTY に設定します。それ以外の場合は、単一の BSTR 値または BSTR 値の配列を指定できます。 指定した BSTR 値は名前と対にされ、名前と値のペアとして格納されます。単一の BSTR 値を指定した場合、Arg0 がその値に割り当てられる名前になります。この値は、アクションプロパティで $(Arg0) 変数が使用されているタスクアクションで使用できます。 "0"、"100"、"250" のような値を BSTR 値の配列として渡すと、"0" はアクションプロパティで使用されている $(Arg0) 変数を、"100" は $(Arg1) 変数を、"250" は $(Arg2) 変数を置き換えます。 最大 32 個の BSTR 値を指定できます。 詳細情報と、値に $(Arg0)、$(Arg1)、...、$(Arg32) 変数を使用できるアクションプロパティの一覧については、Task Actions を参照してください。 |
| ppRunningTask | IRunningTask** | out | タスクの新しいインスタンスを定義する IRunningTask インターフェイスです。 NULL の IRunningTask インターフェイスポインターへの参照を渡してください。NULL 以外のポインターを参照すると、ポインターが上書きされるためメモリリークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
タスクの ITaskSettings の AllowDemandStart プロパティが false に設定されている場合、このメソッドはエラーを返さずに戻りますが、タスクは実行されません。
IRegisteredTask::Run 関数は、flags パラメーターを 0、user パラメーターを NULL にした IRegisteredTask::RunEx 関数と同等です。
IRegisteredTask::Run が無効なタスクから呼び出された場合は、SCHED_E_TASK_DISABLED を返します。
指定したフラグとセッション識別子を使用して、登録済みタスクを即座に実行します。
| params | VARIANT | in | タスクアクションで値として使用されるパラメーターです。タスクアクションにパラメーター値を指定しない場合は、このパラメーターを VT_NULL または VT_EMPTY に設定します。それ以外の場合は、単一の BSTR 値、または BSTR 値の配列を指定できます。 指定した BSTR 値は名前と対にされ、名前と値のペアとして格納されます。単一の BSTR 値を指定した場合、Arg0 がその値に割り当てられる名前になります。この値は、アクションプロパティで $(Arg0) 変数が使用されているタスクアクションで使用できます。 "0"、"100"、"250" のような値を BSTR 値の配列として渡すと、"0" はアクションプロパティで使用されている $(Arg0) 変数を、"100" は $(Arg1) 変数を、"250" は $(Arg2) 変数を置き換えます。 最大 32 個の BSTR 値を指定できます。 詳細情報と、値に $(Arg0)、$(Arg1)、...、$(Arg32) 変数を使用できるアクションプロパティの一覧については、Task Actions を参照してください。 |
| flags | INT | in | タスクの実行方法を定義する TASK_RUN_FLAGS 定数です。 |
| sessionID | INT | in | タスクを開始するターミナルサーバーセッションです。 TASK_RUN_USE_SESSION_ID 定数が flags パラメーターに渡されていない場合、このパラメーターで指定した値は無視されます。TASK_RUN_USE_SESSION_ID 定数が flags パラメーターに渡され、sessionID 値が 0 以下の場合は、無効な引数エラーが返されます。 TASK_RUN_USE_SESSION_ID 定数が flags パラメーターに渡され、sessionID 値が 0 より大きい有効なセッション ID であり、user パラメーターに値が指定されていない場合、タスクスケジューラーサービスは、指定されたセッションにログオンしているユーザーとしてタスクを対話的に開始しようとします。 TASK_RUN_USE_SESSION_ID 定数が flags パラメーターに渡され、sessionID 値が 0 より大きい有効なセッション ID であり、user パラメーターにユーザーが指定されている場合、タスクスケジューラーサービスは、user パラメーターで指定されたユーザーとしてタスクを対話的に開始しようとします。 |
| user | LPWSTR | in | タスクを実行するユーザーです。 |
| ppRunningTask | IRunningTask** | out | タスクの新しいインスタンスを定義する IRunningTask インターフェイスです。 NULL の IRunningTask インターフェイスポインターへの参照を渡してください。NULL 以外のポインターを参照すると、ポインターが上書きされるためメモリリークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
タスクの ITaskSettings の AllowDemandStart プロパティが false に設定されている場合、このメソッドはエラーを返さずに戻りますが、タスクは実行されません。
IRegisteredTask::RunEx が無効なタスクから呼び出された場合は S_OK を返しますが、タスクは実行されません。
現在実行中の登録済みタスクのすべてのインスタンスを返します。
| flags | INT | in | このパラメーターは将来の使用のために予約されており、0 に設定する必要があります。 |
| ppRunningTasks | IRunningTaskCollection** | out | ユーザーのコンテキストで現在実行中のタスクのすべてのインスタンスを含む IRunningTaskCollection インターフェイスです。 NULL の IRunningTaskCollection インターフェイスポインターへの参照を渡してください。NULL 以外のポインターを参照すると、ポインターが上書きされるためメモリリークが発生する可能性があります。 |
戻り値
このメソッドは、次の値のいずれかを返します。
| Return code | Description |
|---|---|
| 操作は正常に完了しました。 | |
| null 以外のフラグが flags パラメーターに渡されました。 | |
| ppRunningTasks パラメーターに NULL が渡されました。 |
登録済みタスクが最後に実行された時刻を取得します。
| pLastRunTime | DOUBLE* | out | タスクが最後に実行された日時を DATE 形式 (DOUBLE) で受け取る変数へのポインタである。 |
登録済みタスクが最後に実行されたときに返された結果を取得します。
| pLastTaskResult | INT* | out | タスクの最後の実行結果コードを受け取る変数へのポインタである。 |
登録済みタスクがスケジュールされた実行を逃した回数を取得します。
| pNumberOfMissedRuns | INT* | out | 実行されなかった (見逃された) 実行回数を受け取る変数へのポインタである。 |
登録済みタスクが次に実行されるようにスケジュールされている時刻を取得します。
| pNextRunTime | DOUBLE* | out | タスクの次回実行予定日時を DATE 形式 (DOUBLE) で受け取る変数へのポインタである。 |
解説(Remarks)
登録済みタスクに個別に無効化されているトリガーが含まれている場合、それらのトリガーは無効化されていても、返される次のスケジュール実行時刻に影響します。
タスクの定義を取得します。
| ppDefinition | ITaskDefinition** | out | このタスクの定義 (ITaskDefinition) を受け取る出力ポインタである。 |
登録済みタスクの XML 形式の登録情報を取得します。
| pXml | LPWSTR* | out | タスク登録情報を表す XML 文字列を受け取る出力ポインタである。SysFreeString で解放する。 |
登録済みタスクの資格情報として使用されるセキュリティ記述子を取得します。
| securityInformation | INT | in | SECURITY_INFORMATION からのセキュリティ情報です。 |
| pSddl | LPWSTR* | out | 登録済みタスクの資格情報として使用されるセキュリティ記述子です。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
登録済みタスクの資格情報として使用されるセキュリティ記述子を設定します。
| sddl | LPWSTR | in | 登録済みタスクの資格情報として使用されるセキュリティ記述子です。 Note Local System アカウントがタスクへのアクセスを拒否されると、タスクスケジューラーサービスが予期しない結果を生成する可能性があります。
|
| flags | INT | in | セキュリティ記述子の設定方法を指定するフラグです。TASK_CREATION 列挙型の TASK_DONT_ADD_PRINCIPAL_ACE フラグを指定できます。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
特定のユーザーやグループにタスクへのアクセスを許可または拒否するために、タスクのセキュリティ記述子でアクセス制御リスト (ACL) を指定できます。
登録済みタスクを即座に停止します。
| flags | INT | in | 予約済みです。ゼロにする必要があります。 |
戻り値
このメソッドは、次の値のいずれかを返します。
| Return code | Description |
|---|---|
| ユーザーが停止する権限を持つ登録済みタスクのすべてのインスタンスが停止されました。 | |
| ユーザーはタスクのインスタンスを正常に停止できません。 |
解説(Remarks)
IRegisteredTask::Stop 関数は、タスクのすべてのインスタンスを停止します。
System アカウントのユーザーはタスクを停止でき、Administrator グループの権限を持つユーザーはタスクを停止でき、ユーザーがタスクの実行と読み取りの権限を持っている場合、そのユーザーはタスクを停止できます。ユーザーは、自分のユーザーアカウントと同じ資格情報で実行されているタスクインスタンスを停止できます。それ以外のすべての場合、ユーザーはタスクを停止するアクセスを拒否されます。
指定した期間内に登録済みタスクが実行されるようにスケジュールされている時刻を取得します。
| pstStart | SYSTEMTIME* | in | クエリの開始時刻です。 |
| pstEnd | SYSTEMTIME* | in | クエリの終了時刻です。 |
| pCount | DWORD* | inout | 入力時は要求する実行回数、出力時は返される実行回数です。 |
| pRunTimes | SYSTEMTIME** | out | タスクが実行されるスケジュール時刻です。このパラメーターには NULL の LPSYSTEMTIME オブジェクトを渡してください。戻り値では、この配列に pCount 個の実行時刻が格納されます。この配列は CoTaskMemFree 関数を呼び出して解放する必要があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。このメソッドが S_FALSE を返した場合、pRunTimes パラメーターには pCount 個の項目が格納されていますが、返されなかったタスクの実行がさらに存在します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
登録済みタスクに個別に無効化されているトリガーが含まれている場合、それらのトリガーは無効化されていても、返される次のスケジュール実行時刻に影響します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IRegisteredTask "{9C86F320-DEE3-4DD1-B972-A303F26B061E}" #usecom global IRegisteredTask IID_IRegisteredTask "{}" #comfunc global IRegisteredTask_get_Name 7 var #comfunc global IRegisteredTask_get_Path 8 var #comfunc global IRegisteredTask_get_State 9 var #comfunc global IRegisteredTask_get_Enabled 10 var #comfunc global IRegisteredTask_put_Enabled 11 int #comfunc global IRegisteredTask_Run 12 int,sptr #comfunc global IRegisteredTask_RunEx 13 int,int,int,wstr,sptr #comfunc global IRegisteredTask_GetInstances 14 int,sptr #comfunc global IRegisteredTask_get_LastRunTime 15 var #comfunc global IRegisteredTask_get_LastTaskResult 16 var #comfunc global IRegisteredTask_get_NumberOfMissedRuns 17 var #comfunc global IRegisteredTask_get_NextRunTime 18 var #comfunc global IRegisteredTask_get_Definition 19 sptr #comfunc global IRegisteredTask_get_Xml 20 var #comfunc global IRegisteredTask_GetSecurityDescriptor 21 int,var #comfunc global IRegisteredTask_SetSecurityDescriptor 22 wstr,int #comfunc global IRegisteredTask_Stop 23 int #comfunc global IRegisteredTask_GetRunTimes 24 var,var,var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IRegisteredTask "{9C86F320-DEE3-4DD1-B972-A303F26B061E}" #usecom global IRegisteredTask IID_IRegisteredTask "{}" #comfunc global IRegisteredTask_get_Name 7 sptr #comfunc global IRegisteredTask_get_Path 8 sptr #comfunc global IRegisteredTask_get_State 9 sptr #comfunc global IRegisteredTask_get_Enabled 10 sptr #comfunc global IRegisteredTask_put_Enabled 11 int #comfunc global IRegisteredTask_Run 12 int,sptr #comfunc global IRegisteredTask_RunEx 13 int,int,int,wstr,sptr #comfunc global IRegisteredTask_GetInstances 14 int,sptr #comfunc global IRegisteredTask_get_LastRunTime 15 sptr #comfunc global IRegisteredTask_get_LastTaskResult 16 sptr #comfunc global IRegisteredTask_get_NumberOfMissedRuns 17 sptr #comfunc global IRegisteredTask_get_NextRunTime 18 sptr #comfunc global IRegisteredTask_get_Definition 19 sptr #comfunc global IRegisteredTask_get_Xml 20 sptr #comfunc global IRegisteredTask_GetSecurityDescriptor 21 int,sptr #comfunc global IRegisteredTask_SetSecurityDescriptor 22 wstr,int #comfunc global IRegisteredTask_Stop 23 int #comfunc global IRegisteredTask_GetRunTimes 24 sptr,sptr,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。