ITaskFolder
COMIDispatch (デュアル)comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。公式ドキュメント
フォルダー内へのタスクの登録(作成)、フォルダーからのタスクの削除、フォルダーのサブフォルダーの作成または削除に使用するメソッドを提供します。
メソッド 13
vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。
タスクを格納するフォルダーを識別するために使用される名前を取得します。
| pName | LPWSTR* | out | このフォルダーの名前を受け取る文字列ポインタへのポインタである。 |
フォルダーが格納されている場所へのパスを取得します。
| pPath | LPWSTR* | out | このフォルダーのパスを受け取る文字列ポインタへのポインタである。 |
指定した場所にあるタスクを格納するフォルダーを取得します。
| path | LPWSTR | in | フォルダーへのパス(場所)。パス内の最後のフォルダー名の後にバックスラッシュを付けないでください。ルート タスク フォルダーはバックスラッシュ(\)で指定します。ルート タスク フォルダー配下のタスク フォルダー パスの例は、 \MyTaskFolder です。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 |
| ppFolder | ITaskFolder** | out | 指定した場所にあるフォルダー。 NULL の ITaskFolder インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
フォルダー内のすべてのサブフォルダーを取得します。
| flags | INT | in | このパラメーターは将来の使用のために予約されており、0 に設定する必要があります。 |
| ppFolders | ITaskFolderCollection** | out | フォルダー内のサブフォルダーのコレクション。 NULL の ITaskFolderCollection インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
関連するタスク用のフォルダーを作成します。
| subFolderName | LPWSTR | in | フォルダーを識別するために使用される名前。"FolderName\SubFolder1\SubFolder2" を指定した場合、フォルダーが存在しなければフォルダー ツリー全体が作成されます。このパラメーターは、現在の ITaskFolder インスタンスへの相対パスにできます。ルート タスク フォルダーはバックスラッシュ(\)で指定します。ルート タスク フォルダー配下のタスク フォルダー パスの例は、 \MyTaskFolder です。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 |
| sddl | VARIANT | in | フォルダーに関連付けられたセキュリティ記述子。SDDL_REVISION_1 形式の VT_BSTR として指定します。 |
| ppFolder | ITaskFolder** | out | 新しいサブフォルダーを表す ITaskFolder インターフェイス。 NULL の ITaskFolder インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
解説(Remarks)
親フォルダーのサブフォルダーを取得するには、GetFolders メソッドを使用します。
作成しようとしているフォルダーが既に存在する場合、CreateFolder メソッドは 0x800700b7 を返します。
sddl パラメーターに無効なセキュリティ記述子を指定すると、このメソッドは E_INVALIDARG を返します。
親フォルダーからサブフォルダーを削除します。
| subFolderName | LPWSTR | in | 削除するサブフォルダーの名前。ルート タスク フォルダーはバックスラッシュ(\)で指定します。このパラメーターは、削除したいフォルダーへの相対パスにできます。ルート タスク フォルダー配下のタスク フォルダー パスの例は、 \MyTaskFolder です。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 |
| flags | INT | in | サポートされていません。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
フォルダー内の指定した場所にあるタスクを取得します。
| path | LPWSTR | in | フォルダー内のタスクへのパス(場所)。ルート タスク フォルダーはバックスラッシュ(\)で指定します。ルート タスク フォルダー配下のタスク フォルダー パスの例は、 \MyTaskFolder です。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 |
| ppTask | IRegisteredTask** | out | 指定した場所にあるタスク。 NULL の IRegisteredTask インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
フォルダー内のすべてのタスクを取得します。
| flags | INT | in | 隠しタスクを取得するかどうかを指定します。隠しタスクを含むフォルダー内のすべてのタスクを取得するには TASK_ENUM_HIDDEN を渡し、隠しタスクを除くフォルダー内のすべてのタスクを取得するには 0 を渡します。 |
| ppTasks | IRegisteredTaskCollection** | out | フォルダー内のすべてのタスクの IRegisteredTaskCollection コレクション。 NULL の IRegisteredTaskCollection インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
フォルダーからタスクを削除します。
| name | LPWSTR | in | タスクの登録時に指定されたタスクの名前。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 |
| flags | INT | in | サポートされていません。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
XML を使用してタスクを定義し、フォルダーに新しいタスクを登録(作成)します。
| path | LPWSTR | in | タスク名。この値が NULL の場合、タスクはルート タスク フォルダーに登録され、タスク名はタスク スケジューラ サービスによって作成される GUID 値になります。 タスク名の先頭または末尾を空白文字にすることはできません。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 | ||||||||||||||||
| xmlText | LPWSTR | in | タスクの XML 形式の定義。 次のトピックには XML を使用して定義されたタスクが含まれています。 | ||||||||||||||||
| flags | INT | in | TASK_CREATION 定数。
| ||||||||||||||||
| userId | VARIANT | in | タスクの登録に使用するユーザー資格情報。 注意 タスクが タスク スケジューラ 1.0 タスクとして定義されている場合は、この userId パラメーターに(特定のユーザー名ではなく)グループ名を使用しないでください。タスクの XML 内の Task 要素の version 属性が 1.1 に設定されている場合、そのタスクは タスク スケジューラ 1.0 タスクとして定義されます。
| ||||||||||||||||
| password | VARIANT | in | タスクの登録に使用する userId のパスワード。TASK_LOGON_SERVICE_ACCOUNT ログオン タイプを使用する場合、パスワードは VT_NULL や VT_EMPTY のような空の VARIANT 値でなければなりません。 | ||||||||||||||||
| logonType | TASK_LOGON_TYPE | in | 登録されたタスクの実行にどのログオン方式が使用されるかを定義する値。
| ||||||||||||||||
| sddl | VARIANT | in | 登録されたタスクに関連付けられたセキュリティ記述子。特定のユーザーやグループに対してタスクへのアクセスを許可または拒否するために、タスクのセキュリティ記述子でアクセス制御リスト(ACL)を指定できます。 注意 Local System アカウントがタスクへのアクセスを拒否されると、タスク スケジューラ サービスが予期しない結果を生じることがあります。
| ||||||||||||||||
| ppTask | IRegisteredTask** | out | 新しいタスクを表す IRegisteredTask インターフェイス。 NULL の IRegisteredTask インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドは次のいずれかの値を返すことがあります。
| リターン コード/値 | 説明 |
|---|---|
|
操作は正常に完了しました。 |
|
タスク スケジューラ サービスへの接続が拒否されました。 |
|
操作を完了するのに十分なメモリがアプリケーションにないか、user または password の少なくとも一方が null で、もう一方が非 null になっています。 |
|
タスクは登録されましたが、開始に失敗する可能性があります。タスク プリンシパルに対してバッチ ログオン特権を有効にする必要があります。 |
|
タスクは登録されましたが、指定されたすべてのトリガーがタスクを開始するわけではありません。 |
解説(Remarks)
メッセージ ボックス アクションを含むタスクの場合、タスクがアクティブ化され、かつタスクが対話型ログオン タイプを持つときにメッセージ ボックスが表示されます。タスクのログオン タイプを対話型に設定するには、タスク プリンシパルの LogonType プロパティ、または ITaskFolder::RegisterTask や ITaskFolder::RegisterTaskDefinition の logonType パラメーターで TASK_LOGON_INTERACTIVE_TOKEN または TASK_LOGON_GROUP を指定します。
ブート トリガーを持つタスクを作成できるのは、Administrators グループのメンバーのみです。
userId パラメーターにグループを指定し、ITaskFolder::RegisterTask または ITaskFolder::RegisterTaskDefinition の logonType パラメーターに TASK_LOGON_INTERACTIVE_TOKEN を指定してタスクを登録することは可能ですが、そのタスクは実行されません。
flags パラメーターに TASK_VALIDATE_ONLY と TASK_IGNORE_REGISTRATION_TRIGGERS の両方を一緒に渡すことは無効な引数です。
タスクが、タスクの NetworkSettings 設定に存在しないネットワークを定義している場合、タスクの登録時に ITaskFolder::RegisterTask メソッドはエラー 0x8000ffff を返します。
ITaskDefinition インターフェイスを使用してタスクを定義し、指定した場所にタスクを登録(作成)します。
| path | LPWSTR | in | タスクの名前。この値が NULL の場合、タスクはルート タスク フォルダーに登録され、タスク名はタスク スケジューラ サービスによって作成される GUID 値になります。 タスク名の先頭または末尾を空白文字にすることはできません。パス内で、現在のタスク フォルダーを指定するために '.' 文字を使用することはできず、親タスク フォルダーを指定するために '..' 文字を使用することもできません。 | ||||||||||||||||
| pDefinition | ITaskDefinition* | inoptional | 登録するタスクの定義。 | ||||||||||||||||
| flags | INT | in | TASK_CREATION 定数。
| ||||||||||||||||
| userId | VARIANT | in | タスクの登録に使用するユーザー資格情報。指定されている場合、これらの資格情報は pDefinition パラメーターが指すタスク定義オブジェクトで指定された資格情報より優先されます。 注意 タスクが タスク スケジューラ 1.0 タスクとして定義されている場合は、この userId パラメーターに(特定のユーザー名ではなく)グループ名を使用しないでください。タスクの設定で Compatibility プロパティが TASK_COMPATIBILITY_V1 に設定されている場合、そのタスクは タスク スケジューラ 1.0 タスクとして定義されます。
| ||||||||||||||||
| password | VARIANT | in | タスクの登録に使用する userId のパスワード。TASK_LOGON_SERVICE_ACCOUNT ログオン タイプを使用する場合、パスワードは VT_NULL や VT_EMPTY のような空の VARIANT 値でなければなりません。 | ||||||||||||||||
| logonType | TASK_LOGON_TYPE | in | 登録されたタスクの実行にどのログオン方式が使用されるかを定義します。
| ||||||||||||||||
| sddl | VARIANT | in | 登録されたタスクに関連付けられたセキュリティ記述子。特定のユーザーやグループに対してタスクへのアクセスを許可または拒否するために、タスクのセキュリティ記述子でアクセス制御リスト(ACL)を指定できます。 注意 Local System アカウントがタスクへのアクセスを拒否されると、タスク スケジューラ サービスが予期しない結果を生じることがあります。
| ||||||||||||||||
| ppTask | IRegisteredTask** | out | 新しいタスクを表す IRegisteredTask インターフェイス。 NULL の IRegisteredTask インターフェイス ポインターへの参照を渡してください。非 NULL のポインターを参照渡しすると、ポインターが上書きされるためメモリ リークが発生する可能性があります。 |
戻り値
このメソッドは次のいずれかの値を返すことがあります。
| リターン コード/値 | 説明 |
|---|---|
|
操作は正常に完了しました。 |
|
タスク スケジューラ サービスへの接続が拒否されました。 |
|
操作を完了するのに十分なメモリがアプリケーションにないか、user または password の少なくとも一方が null で、もう一方が非 null になっています。 |
|
タスクは登録されましたが、開始に失敗する可能性があります。タスク プリンシパルに対してバッチ ログオン特権を有効にする必要があります。 |
|
タスクは登録されましたが、指定されたすべてのトリガーがタスクを開始するわけではありません。 |
解説(Remarks)
メッセージ ボックス アクションを含むタスクの場合、タスクがアクティブ化され、かつタスクが対話型ログオン タイプを持つときにメッセージ ボックスが表示されます。タスクのログオン タイプを対話型に設定するには、タスク プリンシパルの LogonType プロパティ、または ITaskFolder::RegisterTask や ITaskFolder::RegisterTaskDefinition の logonType パラメーターで TASK_LOGON_INTERACTIVE_TOKEN または TASK_LOGON_GROUP を指定します。
ブート トリガーを持つタスクを作成できるのは、Administrators グループのメンバーのみです。
userId パラメーターにグループを指定し、ITaskFolder::RegisterTask または ITaskFolder::RegisterTaskDefinition の logonType パラメーターに TASK_LOGON_INTERACTIVE_TOKEN を指定してタスクを登録することは可能ですが、そのタスクは実行されません。
flags パラメーターに TASK_VALIDATE_ONLY と TASK_IGNORE_REGISTRATION_TRIGGERS の両方を一緒に渡すことは無効な引数です。
ITaskFolder::RegisterTaskDefinition メソッドは、System アカウントによって user パラメーターに NULL、password パラメーターに NULL、logonType パラメーターに TASK_LOGON_SERVICE_ACCOUNT を指定して呼び出された場合、エラー 80070534 を返します。
タスクが、タスクの NetworkSettings 設定に存在しないネットワークを定義している場合、タスクの登録時に ITaskFolder::RegisterTaskDefinition メソッドはエラー 0x8000ffff を返します。
フォルダーのセキュリティ記述子を取得します。
| securityInformation | INT | in | SECURITY_INFORMATION から取得するセキュリティ情報。 |
| pSddl | LPWSTR* | out | フォルダーのセキュリティ記述子。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
フォルダーのセキュリティ記述子を設定します。
| sddl | LPWSTR | in | フォルダーのセキュリティ記述子。 注意 Local System アカウントがタスク フォルダーへのアクセスを拒否されると、タスク スケジューラ サービスが予期しない結果を生じることがあります。
|
| flags | INT | in | セキュリティ記述子をどのように設定するかを指定する値。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。
解説(Remarks)
特定のユーザーやグループに対してタスク フォルダーへのアクセスを許可または拒否するために、タスク フォルダーのセキュリティ記述子でアクセス制御リスト(ACL)を指定できます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ITaskFolder "{8CFAC062-A080-4C15-9A88-AA7C2AF80DFC}" #usecom global ITaskFolder IID_ITaskFolder "{}" #comfunc global ITaskFolder_get_Name 7 var #comfunc global ITaskFolder_get_Path 8 var #comfunc global ITaskFolder_GetFolder 9 wstr,sptr #comfunc global ITaskFolder_GetFolders 10 int,sptr #comfunc global ITaskFolder_CreateFolder 11 wstr,int,sptr #comfunc global ITaskFolder_DeleteFolder 12 wstr,int #comfunc global ITaskFolder_GetTask 13 wstr,sptr #comfunc global ITaskFolder_GetTasks 14 int,sptr #comfunc global ITaskFolder_DeleteTask 15 wstr,int #comfunc global ITaskFolder_RegisterTask 16 wstr,wstr,int,int,int,int,int,sptr #comfunc global ITaskFolder_RegisterTaskDefinition 17 wstr,sptr,int,int,int,int,int,sptr #comfunc global ITaskFolder_GetSecurityDescriptor 18 int,var #comfunc global ITaskFolder_SetSecurityDescriptor 19 wstr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_ITaskFolder "{8CFAC062-A080-4C15-9A88-AA7C2AF80DFC}" #usecom global ITaskFolder IID_ITaskFolder "{}" #comfunc global ITaskFolder_get_Name 7 sptr #comfunc global ITaskFolder_get_Path 8 sptr #comfunc global ITaskFolder_GetFolder 9 wstr,sptr #comfunc global ITaskFolder_GetFolders 10 int,sptr #comfunc global ITaskFolder_CreateFolder 11 wstr,int,sptr #comfunc global ITaskFolder_DeleteFolder 12 wstr,int #comfunc global ITaskFolder_GetTask 13 wstr,sptr #comfunc global ITaskFolder_GetTasks 14 int,sptr #comfunc global ITaskFolder_DeleteTask 15 wstr,int #comfunc global ITaskFolder_RegisterTask 16 wstr,wstr,int,int,int,int,int,sptr #comfunc global ITaskFolder_RegisterTaskDefinition 17 wstr,sptr,int,int,int,int,int,sptr #comfunc global ITaskFolder_GetSecurityDescriptor 18 int,sptr #comfunc global ITaskFolder_SetSecurityDescriptor 19 wstr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。 ; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。