Win32 API 日本語リファレンス
ホームSystem.TaskScheduler › IRegisteredTask

IRegisteredTask

COMIDispatch (デュアル)
IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。
IID9c86f320-dee3-4dd1-b972-a303f26b061e継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

タスクを即座に実行する、タスクの実行中インスタンスを取得する、タスクの登録に使用する資格情報を取得または設定する、およびタスクを記述するプロパティを取得するために使用するメソッドを提供します。

メソッド 18

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT get_Name(LPWSTR* pName)

登録済みタスクの名前を取得します。

pNameLPWSTR*out登録済みタスクの名前を受け取る出力ポインタである。SysFreeString で解放する。
vtbl 8 HRESULT get_Path(LPWSTR* pPath)

登録済みタスクが格納されている場所へのパスを取得します。

pPathLPWSTR*out登録済みタスクのパスを受け取る出力ポインタである。SysFreeString で解放する。
vtbl 9 HRESULT get_State(TASK_STATE* pState)

登録済みタスクの動作状態を取得します。

pStateTASK_STATE*out登録済みタスクの現在の状態を表す TASK_STATE 値を受け取る変数へのポインタである。
vtbl 10 HRESULT get_Enabled(VARIANT_BOOL* pEnabled)

登録済みタスクが有効かどうかを示すブール値を取得または設定します。(Get)

pEnabledVARIANT_BOOL*outタスクが有効かどうかを受け取る VARIANT_BOOL へのポインタである。

解説(Remarks)

このプロパティは VARIANT_BOOL 型で、true 値を指定するには -1 を、false を表すには 0 を使用します。-1 または 0 以外の値を使用してもエラーは返されません。

vtbl 11 HRESULT put_Enabled(VARIANT_BOOL enabled)

登録済みタスクが有効かどうかを示すブール値を取得または設定します。(Put)

enabledVARIANT_BOOLinタスクの有効・無効を指定する VARIANT_BOOL である。

解説(Remarks)

このプロパティは VARIANT_BOOL 型で、true 値を指定するには -1 を、false を表すには 0 を使用します。-1 または 0 以外の値を使用してもエラーは返されません。

vtbl 12 HRESULT Run(VARIANT params, IRunningTask** ppRunningTask)

登録済みタスクを即座に実行します。

paramsVARIANTin

タスクアクションで値として使用されるパラメーターです。タスクアクションにパラメーター値を指定しない場合は、このパラメーターを 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 を参照してください。

ppRunningTaskIRunningTask**out

タスクの新しいインスタンスを定義する IRunningTask インターフェイスです。

NULLIRunningTask インターフェイスポインターへの参照を渡してください。NULL 以外のポインターを参照すると、ポインターが上書きされるためメモリリークが発生する可能性があります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

タスクの ITaskSettings の AllowDemandStart プロパティが false に設定されている場合、このメソッドはエラーを返さずに戻りますが、タスクは実行されません。

IRegisteredTask::Run 関数は、flags パラメーターを 0、user パラメーターを NULL にした IRegisteredTask::RunEx 関数と同等です。

IRegisteredTask::Run が無効なタスクから呼び出された場合は、SCHED_E_TASK_DISABLED を返します。

vtbl 13 HRESULT RunEx(VARIANT params, INT flags, INT sessionID, LPWSTR user, IRunningTask** ppRunningTask)

指定したフラグとセッション識別子を使用して、登録済みタスクを即座に実行します。

paramsVARIANTin

タスクアクションで値として使用されるパラメーターです。タスクアクションにパラメーター値を指定しない場合は、このパラメーターを 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 を参照してください。

flagsINTinタスクの実行方法を定義する TASK_RUN_FLAGS 定数です。
sessionIDINTin

タスクを開始するターミナルサーバーセッションです。

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 パラメーターで指定されたユーザーとしてタスクを対話的に開始しようとします。

userLPWSTRinタスクを実行するユーザーです。
ppRunningTaskIRunningTask**out

タスクの新しいインスタンスを定義する IRunningTask インターフェイスです。

NULLIRunningTask インターフェイスポインターへの参照を渡してください。NULL 以外のポインターを参照すると、ポインターが上書きされるためメモリリークが発生する可能性があります。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

タスクの ITaskSettings の AllowDemandStart プロパティが false に設定されている場合、このメソッドはエラーを返さずに戻りますが、タスクは実行されません。

IRegisteredTask::RunEx が無効なタスクから呼び出された場合は S_OK を返しますが、タスクは実行されません。

vtbl 14 HRESULT GetInstances(INT flags, IRunningTaskCollection** ppRunningTasks)

現在実行中の登録済みタスクのすべてのインスタンスを返します。

flagsINTinこのパラメーターは将来の使用のために予約されており、0 に設定する必要があります。
ppRunningTasksIRunningTaskCollection**out

ユーザーのコンテキストで現在実行中のタスクのすべてのインスタンスを含む IRunningTaskCollection インターフェイスです。

NULLIRunningTaskCollection インターフェイスポインターへの参照を渡してください。NULL 以外のポインターを参照すると、ポインターが上書きされるためメモリリークが発生する可能性があります。

戻り値

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

Return code Description
S_OK
操作は正常に完了しました。
E_INVALIDARG
null 以外のフラグが flags パラメーターに渡されました。
E_POINTER
ppRunningTasks パラメーターに NULL が渡されました。
vtbl 15 HRESULT get_LastRunTime(DOUBLE* pLastRunTime)

登録済みタスクが最後に実行された時刻を取得します。

pLastRunTimeDOUBLE*outタスクが最後に実行された日時を DATE 形式 (DOUBLE) で受け取る変数へのポインタである。
vtbl 16 HRESULT get_LastTaskResult(INT* pLastTaskResult)

登録済みタスクが最後に実行されたときに返された結果を取得します。

pLastTaskResultINT*outタスクの最後の実行結果コードを受け取る変数へのポインタである。
vtbl 17 HRESULT get_NumberOfMissedRuns(INT* pNumberOfMissedRuns)

登録済みタスクがスケジュールされた実行を逃した回数を取得します。

pNumberOfMissedRunsINT*out実行されなかった (見逃された) 実行回数を受け取る変数へのポインタである。
vtbl 18 HRESULT get_NextRunTime(DOUBLE* pNextRunTime)

登録済みタスクが次に実行されるようにスケジュールされている時刻を取得します。

pNextRunTimeDOUBLE*outタスクの次回実行予定日時を DATE 形式 (DOUBLE) で受け取る変数へのポインタである。

解説(Remarks)

登録済みタスクに個別に無効化されているトリガーが含まれている場合、それらのトリガーは無効化されていても、返される次のスケジュール実行時刻に影響します。

vtbl 19 HRESULT get_Definition(ITaskDefinition** ppDefinition)

タスクの定義を取得します。

ppDefinitionITaskDefinition**outこのタスクの定義 (ITaskDefinition) を受け取る出力ポインタである。
vtbl 20 HRESULT get_Xml(LPWSTR* pXml)

登録済みタスクの XML 形式の登録情報を取得します。

pXmlLPWSTR*outタスク登録情報を表す XML 文字列を受け取る出力ポインタである。SysFreeString で解放する。
vtbl 21 HRESULT GetSecurityDescriptor(INT securityInformation, LPWSTR* pSddl)

登録済みタスクの資格情報として使用されるセキュリティ記述子を取得します。

securityInformationINTinSECURITY_INFORMATION からのセキュリティ情報です。
pSddlLPWSTR*out登録済みタスクの資格情報として使用されるセキュリティ記述子です。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 22 HRESULT SetSecurityDescriptor(LPWSTR sddl, INT flags)

登録済みタスクの資格情報として使用されるセキュリティ記述子を設定します。

sddlLPWSTRin

登録済みタスクの資格情報として使用されるセキュリティ記述子です。

Note Local System アカウントがタスクへのアクセスを拒否されると、タスクスケジューラーサービスが予期しない結果を生成する可能性があります。
flagsINTinセキュリティ記述子の設定方法を指定するフラグです。TASK_CREATION 列挙型の TASK_DONT_ADD_PRINCIPAL_ACE フラグを指定できます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

特定のユーザーやグループにタスクへのアクセスを許可または拒否するために、タスクのセキュリティ記述子でアクセス制御リスト (ACL) を指定できます。

vtbl 23 HRESULT Stop(INT flags)

登録済みタスクを即座に停止します。

flagsINTin予約済みです。ゼロにする必要があります。

戻り値

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

Return code Description
S_OK
ユーザーが停止する権限を持つ登録済みタスクのすべてのインスタンスが停止されました。
S_FALSE
ユーザーはタスクのインスタンスを正常に停止できません。

解説(Remarks)

IRegisteredTask::Stop 関数は、タスクのすべてのインスタンスを停止します。

System アカウントのユーザーはタスクを停止でき、Administrator グループの権限を持つユーザーはタスクを停止でき、ユーザーがタスクの実行と読み取りの権限を持っている場合、そのユーザーはタスクを停止できます。ユーザーは、自分のユーザーアカウントと同じ資格情報で実行されているタスクインスタンスを停止できます。それ以外のすべての場合、ユーザーはタスクを停止するアクセスを拒否されます。

vtbl 24 HRESULT GetRunTimes(SYSTEMTIME* pstStart, SYSTEMTIME* pstEnd, DWORD* pCount, SYSTEMTIME** pRunTimes)

指定した期間内に登録済みタスクが実行されるようにスケジュールされている時刻を取得します。

pstStartSYSTEMTIME*inクエリの開始時刻です。
pstEndSYSTEMTIME*inクエリの終了時刻です。
pCountDWORD*inout入力時は要求する実行回数、出力時は返される実行回数です。
pRunTimesSYSTEMTIME**outタスクが実行されるスケジュール時刻です。このパラメーターには NULL の LPSYSTEMTIME オブジェクトを渡してください。戻り値では、この配列に pCount 個の実行時刻が格納されます。この配列は CoTaskMemFree 関数を呼び出して解放する必要があります。

戻り値

このメソッドが成功した場合は S_OK を返します。このメソッドが S_FALSE を返した場合、pRunTimes パラメーターには pCount 個の項目が格納されていますが、返されなかったタスクの実行がさらに存在します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

登録済みタスクに個別に無効化されているトリガーが含まれている場合、それらのトリガーは無効化されていても、返される次のスケジュール実行時刻に影響します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_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 不要)。