ホーム › Storage.FileHistory › IFhConfigMgr

IFhConfigMgr

COM

📘 Microsoft Learn (日本語) · English

IID6a5fea5b-bf8f-4ee5-b8c3-44d8a0d7331c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IFhConfigMgr インターフェイスを使用すると、クライアントアプリケーションは、このインターフェイスのメソッドを呼び出したユーザーアカウントに対するファイル履歴 (File History) の構成を読み取り、変更できます。

メソッド 14

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

vtbl 3 HRESULT LoadConfiguration()

現在のユーザーのファイル履歴構成情報を FhConfigMgr オブジェクトに読み込みます。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は、FhErrors.h ヘッダーファイルで定義されている値などの HRESULT エラーコードを返します。

解説(Remarks)

他の IFhConfigMgr メソッドを呼び出す前に、このメソッドまたは IFhConfigMgr::CreateDefaultConfiguration メソッドを呼び出す必要があります。

vtbl 4 HRESULT CreateDefaultConfiguration(BOOL OverwriteIfExists)

現在のユーザー用に既定の設定を持つファイル履歴構成ファイルを作成し、それを FhConfigMgr オブジェクトに読み込みます。

OverwriteIfExists

BOOL

現在のユーザーのファイル履歴構成ファイルが既に存在し、このパラメーターが TRUE に設定されている場合、それらのファイルは上書きされ、以前のすべての設定とポリシーが既定値にリセットされます。

現在のユーザーのファイル履歴構成ファイルが既に存在し、このパラメーターが FALSE に設定されている場合、それらのファイルは上書きされず、失敗を示す HRESULT 値が返されます。

戻り値

成功した場合は S_OK、失敗した場合は失敗を示す HRESULT 値を返します。失敗を示す HRESULT 値には、FhErrors.h ヘッダーファイルで定義されている値が含まれます。

解説(Remarks)

他の IFhConfigMgr メソッドを呼び出す前に、このメソッドまたは LoadConfiguration メソッドを呼び出す必要があります。

vtbl 5 HRESULT SaveConfiguration()

現在のユーザーのファイル履歴構成ファイルに対して LoadConfiguration、CreateDefaultConfiguration、または SaveConfiguration メソッドが最後に呼び出されて以降に FhConfigMgr オブジェクトで行われたすべての変更を、ディスクに保存します。

戻り値

解説(Remarks)

このメソッドは、FhConfigMgr オブジェクトの有効期間中、必要な回数だけ呼び出すことができます。

vtbl 6 HRESULT AddRemoveExcludeRule(BOOL Add, FH_PROTECTED_ITEM_CATEGORY Category, LPWSTR Item)

除外規則を除外リストに追加するか、リストから規則を削除します。

Add	BOOL	in	このパラメーターが TRUE の場合、新しい除外規則が追加されます。 FALSE に設定されている場合、既存の除外規則が削除されます。
Category	FH_PROTECTED_ITEM_CATEGORY	in	除外規則の種類を指定します。指定できる値については、FH_PROTECTED_ITEM_CATEGORY 列挙型を参照してください。
Item	LPWSTR	in	除外規則が適用される項目のフォルダーパス、ライブラリ名、または GUID。

戻り値

解説(Remarks)

ファイル履歴の保護スコープとは、ファイル履歴機能によってバックアップされるファイルの集合です。保護スコープには、包含規則と除外規則が含まれます。包含規則は対象に含めるファイルとフォルダーを指定し、除外規則は対象から除外するファイルとフォルダーを指定します。

既定の保護スコープには、すべてのユーザーライブラリのすべてのフォルダーと、連絡先、デスクトップ、お気に入りの各フォルダーが含まれます。

除外規則は包含規則より優先されます。つまり、包含規則と除外規則が競合する場合、ファイル履歴機能は除外規則に従います。

保護スコープを狭めるには、IFhConfigMgr::AddRemoveExcludeRule を使用して除外規則を追加します。

このメソッドは除外規則の追加と削除に使用できます。包含規則の変更には使用できません。

ユーザーライブラリは、SHGetKnownFolderItem 関数と、IShellItem および IEnumShellItems インターフェイスのメソッドを呼び出すことで列挙できます。

標準のフォルダーとライブラリは、アスタリスクを前置した GUID で指定します。たとえば、*a990ae9f-a03b-4e80-94bc-9912d7504104 はピクチャライブラリを指定します。標準のフォルダーとライブラリおよびその GUID の一覧については、KNOWNFOLDERID のドキュメントを参照してください。

カスタムライブラリは名前で指定します。フォルダーはフルパスで指定します (例: C:\Users\Public\Videos)。

vtbl 7 HRESULT GetIncludeExcludeRules(BOOL Include, FH_PROTECTED_ITEM_CATEGORY Category, IFhScopeIterator** Iterator)

FhConfigMgr オブジェクトに現在格納されている包含規則および除外規則を取得します。

Include	BOOL	in	TRUE に設定した場合は包含規則が返されます。FALSE に設定した場合は除外規則が返されます。
Category	FH_PROTECTED_ITEM_CATEGORY	in	包含規則または除外規則の種類を指定する FH_PROTECTED_ITEM_CATEGORY 列挙値。
Iterator	IFhScopeIterator**	out	要求したカテゴリの規則を列挙するために使用できる IFhScopeIterator インターフェイスポインターを受け取ります。

戻り値

成功した場合は S_OK、失敗した場合は失敗を示す HRESULT を返します。失敗を示す HRESULT 値には、FhErrors.h ヘッダーファイルで定義されている値が含まれます。

解説(Remarks)

ファイル履歴の保護スコープとは、この機能によってバックアップされるファイルの集合です。保護スコープには、包含規則と除外規則が含まれます。包含規則は対象に含めるファイルとフォルダーを指定し、除外規則は対象から除外するファイルとフォルダーを指定します。

ユーザーライブラリからフォルダーを削除することなく、除外規則を追加してファイル履歴の保護スコープを狭めることで、保護スコープを変更できます。

除外規則は包含規則より優先されます。つまり、包含規則と除外規則が競合する場合、ファイル履歴機能は除外規則に従います。

IFhConfigMgr::AddRemoveExcludeRule メソッドは、除外規則の追加と削除に使用できます。包含規則の変更には使用できません。

vtbl 8 HRESULT GetLocalPolicy(FH_LOCAL_POLICY_TYPE LocalPolicyType, ULONGLONG* PolicyValue)

ファイル履歴機能のローカルポリシーの数値パラメーターを取得します。

LocalPolicyType	FH_LOCAL_POLICY_TYPE	in	ローカルポリシーを指定します。
PolicyValue	ULONGLONG*	out	指定したローカルポリシーの数値パラメーターの値を受け取ります。

戻り値

解説(Remarks)

各ローカルポリシーは、ファイル履歴機能がファイルおよびフォルダーをどのように、またはいつバックアップするかを指定する数値パラメーターを保持します。指定できるローカルポリシーの詳細については、FH_LOCAL_POLICY_TYPE 列挙型を参照してください。

ローカルポリシーの数値パラメーターの値を設定するには、IFhConfigMgr::SetLocalPolicy メソッドを使用します。

vtbl 9 HRESULT SetLocalPolicy(FH_LOCAL_POLICY_TYPE LocalPolicyType, ULONGLONG PolicyValue)

FhConfigMgr オブジェクト内のローカルポリシーの数値パラメーターの値を変更します。

LocalPolicyType	FH_LOCAL_POLICY_TYPE	in	ローカルポリシーを指定します。
PolicyValue	ULONGLONG	in	指定したローカルポリシーの数値パラメーターの新しい値を指定します。

戻り値

解説(Remarks)

ローカルポリシーの数値パラメーターの値を取得するには、IFhConfigMgr::GetLocalPolicy メソッドを使用します。

vtbl 10 HRESULT GetBackupStatus(FH_BACKUP_STATUS* BackupStatus)

FhConfigMgr オブジェクトのバックアップ状態値を取得します。

BackupStatus

FH_BACKUP_STATUS*

out

バックアップ状態値を受け取ります。指定できるバックアップ状態値の一覧については、FH_BACKUP_STATUS 列挙型を参照してください。

戻り値

vtbl 11 HRESULT SetBackupStatus(FH_BACKUP_STATUS BackupStatus)

FhConfigMgr オブジェクトのバックアップ状態値を変更します。

BackupStatus

FH_BACKUP_STATUS

バックアップ状態値。指定できるバックアップ状態値の一覧については、FH_BACKUP_STATUS 列挙型を参照してください。

戻り値

解説(Remarks)

FH_STATUS_DISABLED_BY_GP は、BackupStatus パラメーターに指定できる有効な値ではありません。

vtbl 12 HRESULT GetDefaultTarget(IFhTarget** DefaultTarget)

現在割り当てられているバックアップターゲットに関する情報を照会するために使用できる IFhTarget インターフェイスへのポインターを返します。

DefaultTarget

IFhTarget**

out

現在割り当てられている既定のターゲットを表すオブジェクトの IFhTarget インターフェイスへのポインターを受け取ります。既定のターゲットが存在しない場合は NULL を受け取ります。

戻り値

解説(Remarks)

バックアップターゲットが現在割り当てられていない場合、このメソッドは HRESULT_FROM_WIN32(ERROR_NOT_FOUND) を返します。

vtbl 13 HRESULT ValidateTarget(LPWSTR TargetUrl, FH_DEVICE_VALIDATION_RESULT* ValidationResult)

特定のストレージデバイスまたはネットワーク共有を、ファイル履歴のバックアップターゲットとして使用できるかどうかを確認します。

TargetUrl	LPWSTR	in	検証するストレージデバイスまたはネットワーク共有。
ValidationResult	FH_DEVICE_VALIDATION_RESULT*	out	デバイス検証の結果を受け取ります。指定できるデバイス検証結果値の一覧については、FH_DEVICE_VALIDATION_RESULT 列挙型を参照してください。

戻り値

解説(Remarks)

ローカルディスクの場合、TargetUrl パラメーターにはドライブ文字を指定します。このパスは末尾が円記号 (バックスラッシュ) で終わる必要があります (例: "X:\")。

ネットワーク共有の場合、TargetUrl パラメーターには共有のフルパスを指定します。このパスは末尾が円記号 (バックスラッシュ) で終わる必要があります (例: "\\myserver\myshare\")。

vtbl 14 HRESULT ProvisionAndSetNewTarget(LPWSTR TargetUrl, LPWSTR TargetName)

特定のストレージデバイスまたはネットワーク共有をファイル履歴のバックアップターゲットとしてプロビジョニングし、現在のユーザーの既定のバックアップターゲットとして割り当てます。

TargetUrl	LPWSTR	in	プロビジョニングして既定として割り当てるストレージデバイスまたはネットワーク共有を指定します。
TargetName	LPWSTR	in	指定したバックアップターゲットのわかりやすい名前を指定します。

戻り値

解説(Remarks)

TargetUrl パラメーターで指定するストレージデバイスまたはネットワーク共有は、事前に IFhConfigMgr::ValidateTarget メソッドで検証することを強くお勧めします。ValidateTarget が FH_VALID_TARGET 以外の検証結果を返した場合、そのストレージデバイスまたはネットワーク共有を既定のバックアップターゲットとして割り当てると、予期しない結果を招くおそれがあります。

vtbl 15 HRESULT ChangeDefaultTargetRecommendation(BOOL Recommend)

現在割り当てられているバックアップターゲットを、コンピューターが所属するホームグループの他のメンバーに推奨する、または推奨しないようにします。

Recommend

BOOL

TRUE に設定した場合、現在割り当てられているバックアップターゲットがホームグループの他のメンバーに推奨されます。FALSE に設定し、現在割り当てられているバックアップターゲットがホームグループの他のメンバーに推奨されている場合、その推奨は取り消されます。

戻り値

解説(Remarks)

バックアップターゲットがホームグループ内の他のコンピューターに推奨されると、それらのコンピューターのユーザーには、コントロールパネルの「ファイル履歴」項目で、利用可能なバックアップターゲットの一覧にそのストレージデバイスが表示されます。

バックアップターゲットがホームグループ内の他のコンピューターに推奨されていない場合、または推奨が取り消された場合、そのターゲットは他のコンピューターの利用可能なバックアップターゲットの一覧に表示されません。

ドメインに参加しているコンピューター、または ARM アーキテクチャのコンピューターでは、バックアップターゲットを推奨または非推奨にすることはできません。

vtbl 16 HRESULT QueryProtectionStatus(DWORD* ProtectionState, LPWSTR* ProtectedUntilTime)

現在のファイル履歴の保護状態を取得します。

ProtectionState

DWORD*

out

戻り時に、このパラメーターは現在のファイル履歴の保護状態を受け取ります。次の保護状態が FhStatus.h ヘッダーファイルで定義されています。

値	意味
FH_STATE_NOT_TRACKED 0x00	ファイル履歴サービスが開始されていないか、現在のユーザーが追跡対象になっていないため、ファイル履歴の保護状態は不明です。この値を FH_STATE_RUNNING (0x100) と OR 結合することはできません。
FH_STATE_OFF 0x01	現在のユーザーに対してファイル履歴の保護が有効になっていません。ファイルはバックアップされません。この値を FH_STATE_RUNNING (0x100) と OR 結合することはできません。
FH_STATE_DISABLED_BY_GP 0x02	ファイル履歴の保護がグループポリシーによって無効にされています。ファイルはバックアップされません。この値を FH_STATE_RUNNING (0x100) と OR 結合することはできません。
FH_STATE_FATAL_CONFIG_ERROR 0x03	現在のユーザーのファイル履歴の内部情報を格納するファイルのいずれかに致命的なエラーがあります。ファイルはバックアップされません。この値を FH_STATE_RUNNING (0x100) と OR 結合することはできません。
FH_STATE_TARGET_ACCESS_DENIED 0x0E	現在のユーザーには、現在割り当てられているターゲットへの書き込み権限がありません。ファイルバージョンのバックアップコピーは作成されません。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TARGET_VOLUME_DIRTY 0x0F	現在割り当てられているターゲットがダーティとしてマークされています。Chkdsk ユーティリティを実行するまで、ファイルバージョンのバックアップコピーは作成されません。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TARGET_FULL_RETENTION_MAX 0x10	現在割り当てられているターゲットには、ファイル履歴の保護スコープに含まれるファイルのバックアップコピーを格納するのに十分な空き容量がなく、保持ポリシーは既に最も積極的な設定になっています。ファイル履歴が提供する保護レベルは低下します。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TARGET_FULL 0x11	現在割り当てられているターゲットには、ファイル履歴の保護スコープに含まれるファイルのバックアップコピーを格納するのに十分な空き容量がありません。ファイル履歴が提供する保護レベルは低下します。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_STAGING_FULL 0x12	ローカルディスク上のファイル履歴キャッシュに、ファイル履歴の保護スコープに含まれるファイルのバックアップコピーを一時的に格納するのに十分な空き容量がありません。ファイル履歴が提供する保護レベルは低下します。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TARGET_LOW_SPACE_RETENTION_MAX 0x13	現在割り当てられているターゲットの空き容量が不足しつつあり、保持ポリシーは既に最も積極的な設定になっています。ファイル履歴の保護レベルは間もなく低下する可能性があります。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TARGET_LOW_SPACE 0x14	現在割り当てられているターゲットの空き容量が不足しつつあります。ファイル履歴の保護レベルは間もなく低下する可能性があります。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TARGET_ABSENT 0x15	現在割り当てられているターゲットが長期間バックアップに利用できない状態が続いており、ファイル履歴の保護レベルが低下し始めています。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_TOO_MUCH_BEHIND 0x16	保護対象のファイルまたは保護スコープに対して変更が多すぎます。バックグラウンドでの定期的なバックアップサイクルに任せるのではなく、ユーザーが明示的に即時バックアップを開始しない限り、ファイル履歴の保護レベルは低下する可能性があります。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。
FH_STATE_NO_ERROR 0xFF	ファイル履歴のバックアップが定期的に実行されており、エラー状態は検出されず、最適なレベルのファイル履歴保護が提供されています。この値は FH_STATE_RUNNING (0x100) と OR 結合でき、現在のユーザーに対してバックアップサイクルが実行中であることを示します。

ProtectedUntilTime

LPWSTR*

out

ファイル履歴の保護スコープ内のすべてのファイルが保護されている期限の日時を含む、SysAllocString で割り当てられた文字列へのポインターを受け取ります。日時はシステムロケールに従って書式設定されます。日時が不明な場合は、空の文字列が返されます。

次のいずれかの条件が満たされる場合、ファイルはある時点まで保護されているとみなされます。

その時点以降にキャプチャされ、現時点より前に現在割り当てられているバックアップターゲットへ完全にコピーされたバージョンが、そのファイルに存在する。
そのファイルが、その時点以降に作成されたか、ファイル履歴の保護スコープに追加された。

戻り値

解説(Remarks)

呼び出し元は、ProtectedUntilTime 用に割り当てられたメモリを SysFreeString を呼び出して解放する責任があります。

保護状態は、ファイル履歴の動作状態と、保護スコープ内のすべてのファイルが保護されている期限の日時を示します。

ターゲットが満杯であるか切断されている場合、ファイル履歴機能は次のように低下したレベルの保護を提供します。

ファイルはローカルディスク上のファイル履歴キャッシュにバックアップされます。
この間にキャッシュが満杯になった場合、新しいコピーをバックアップするために古いコピーがキャッシュから削除されます。
ターゲットの空き容量が不足している場合、ターゲットが満杯になった時点で保護レベルの低下が始まります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IFhConfigMgr "{6A5FEA5B-BF8F-4EE5-B8C3-44D8A0D7331C}"
#usecom global IFhConfigMgr IID_IFhConfigMgr "{ED43BB3C-09E9-498A-9DF6-2177244C6DB4}"
#comfunc global IFhConfigMgr_LoadConfiguration                  3
#comfunc global IFhConfigMgr_CreateDefaultConfiguration         4 int
#comfunc global IFhConfigMgr_SaveConfiguration                  5
#comfunc global IFhConfigMgr_AddRemoveExcludeRule               6 int,int,wstr
#comfunc global IFhConfigMgr_GetIncludeExcludeRules             7 int,int,sptr
#comfunc global IFhConfigMgr_GetLocalPolicy                     8 int,var
#comfunc global IFhConfigMgr_SetLocalPolicy                     9 int,int64
#comfunc global IFhConfigMgr_GetBackupStatus                    10 var
#comfunc global IFhConfigMgr_SetBackupStatus                    11 int
#comfunc global IFhConfigMgr_GetDefaultTarget                   12 sptr
#comfunc global IFhConfigMgr_ValidateTarget                     13 wstr,var
#comfunc global IFhConfigMgr_ProvisionAndSetNewTarget           14 wstr,wstr
#comfunc global IFhConfigMgr_ChangeDefaultTargetRecommendation  15 int
#comfunc global IFhConfigMgr_QueryProtectionStatus              16 var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IFhConfigMgr "{6A5FEA5B-BF8F-4EE5-B8C3-44D8A0D7331C}"
#usecom global IFhConfigMgr IID_IFhConfigMgr "{ED43BB3C-09E9-498A-9DF6-2177244C6DB4}"
#comfunc global IFhConfigMgr_LoadConfiguration                  3
#comfunc global IFhConfigMgr_CreateDefaultConfiguration         4 int
#comfunc global IFhConfigMgr_SaveConfiguration                  5
#comfunc global IFhConfigMgr_AddRemoveExcludeRule               6 int,int,wstr
#comfunc global IFhConfigMgr_GetIncludeExcludeRules             7 int,int,sptr
#comfunc global IFhConfigMgr_GetLocalPolicy                     8 int,sptr
#comfunc global IFhConfigMgr_SetLocalPolicy                     9 int,int64
#comfunc global IFhConfigMgr_GetBackupStatus                    10 sptr
#comfunc global IFhConfigMgr_SetBackupStatus                    11 int
#comfunc global IFhConfigMgr_GetDefaultTarget                   12 sptr
#comfunc global IFhConfigMgr_ValidateTarget                     13 wstr,sptr
#comfunc global IFhConfigMgr_ProvisionAndSetNewTarget           14 wstr,wstr
#comfunc global IFhConfigMgr_ChangeDefaultTargetRecommendation  15 int
#comfunc global IFhConfigMgr_QueryProtectionStatus              16 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。