From 2251e5d7b1f33d6d2973b0859f3f90a45be9b0bf Mon Sep 17 00:00:00 2001 From: dahall Date: Thu, 30 Sep 2021 12:14:05 -0600 Subject: [PATCH] Added methods and interfaces for File History -- tests still failing --- PInvoke/FhSvcCtl/FhSvcCtl.cs | 1280 +++++++++++++++++++++++ PInvoke/FhSvcCtl/Vanara.PInvoke.FhSvcCtl.csproj | 19 + UnitTests/PInvoke/FhSvcCtl/FhSvcCtl.csproj | 8 + UnitTests/PInvoke/FhSvcCtl/FhSvcCtlTests.cs | 52 + Vanara.sln | 16 + 5 files changed, 1375 insertions(+) create mode 100644 PInvoke/FhSvcCtl/FhSvcCtl.cs create mode 100644 PInvoke/FhSvcCtl/Vanara.PInvoke.FhSvcCtl.csproj create mode 100644 UnitTests/PInvoke/FhSvcCtl/FhSvcCtl.csproj create mode 100644 UnitTests/PInvoke/FhSvcCtl/FhSvcCtlTests.cs diff --git a/PInvoke/FhSvcCtl/FhSvcCtl.cs b/PInvoke/FhSvcCtl/FhSvcCtl.cs new file mode 100644 index 00000000..5db05ac5 --- /dev/null +++ b/PInvoke/FhSvcCtl/FhSvcCtl.cs @@ -0,0 +1,1280 @@ +using System; +using System.Runtime.InteropServices; +using FILETIME = System.Runtime.InteropServices.ComTypes.FILETIME; + +namespace Vanara.PInvoke +{ + /// Items from the FhSvcCtl.dll for File History. + public static partial class FhSvcCtl + { + private const string Lib_FhSvcCtl = "fhsvcctl.dll"; + + /// Specifies whether File History backups are enabled. + /// + /// + /// The protection scope is the set of files and folders that are backed up by the File History feature. The default protection + /// scope includes all folders from all user libraries and the Contacts, Desktop, and Favorites folders. + /// + /// + /// The FH_STATUS_DISABLED_BY_GP status can be queried by calling the IFhConfigMgr::GetBackupStatus method, but it cannot be + /// set by calling the IFhConfigMgr::SetBackupStatus method. This is because it can only be set by Group Policy. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_backup_status typedef enum _FH_BACKUP_STATUS { + // FH_STATUS_DISABLED, FH_STATUS_DISABLED_BY_GP, FH_STATUS_ENABLED, FH_STATUS_REHYDRATING, MAX_BACKUP_STATUS } FH_BACKUP_STATUS; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_BACKUP_STATUS")] + public enum FH_BACKUP_STATUS + { + /// File History backups are not enabled by the user. + FH_STATUS_DISABLED, + + /// File History backups are disabled by Group Policy. + FH_STATUS_DISABLED_BY_GP, + + /// File History backups are enabled. + FH_STATUS_ENABLED, + + /// + FH_STATUS_REHYDRATING, + } + + /// Indicates whether the storage device or network share can be used as a File History backup target. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_device_validation_result typedef enum + // _FH_DEVICE_VALIDATION_RESULT { FH_ACCESS_DENIED, FH_INVALID_DRIVE_TYPE, FH_READ_ONLY_PERMISSION, FH_CURRENT_DEFAULT, + // FH_NAMESPACE_EXISTS, FH_TARGET_PART_OF_LIBRARY, FH_VALID_TARGET, MAX_VALIDATION_RESULT } FH_DEVICE_VALIDATION_RESULT, *PFH_DEVICE_VALIDATION_RESULT; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_DEVICE_VALIDATION_RESULT")] + public enum FH_DEVICE_VALIDATION_RESULT + { + /// The storage device or network share cannot be used as a backup target, because it is not accessible. + FH_ACCESS_DENIED, + + /// + /// The storage device or network share cannot be used as a backup target, because the drive type is not supported. For example, + /// a CD or DVD cannot be used as a File History backup target. + /// + FH_INVALID_DRIVE_TYPE, + + /// The storage device or network share cannot be used as a backup target, because it is read-only. + FH_READ_ONLY_PERMISSION, + + /// The storage device or network share is already being used as a backup target. + FH_CURRENT_DEFAULT, + + /// + /// The storage device or network share was previously used to back up files from a computer or user that has the same name as + /// the current computer or user. It can be used as a backup target, but if it is used, the operating system will delete the + /// previous backup. + /// + FH_NAMESPACE_EXISTS, + + /// + /// The storage device or network share cannot be used as a backup target, because it is in the File History protection scope. + /// + FH_TARGET_PART_OF_LIBRARY, + + /// The storage device or network share can be used as a backup target. + FH_VALID_TARGET, + } + + /// + /// Specifies the type of a local policy for the File History feature. Each local policy has a numeric parameter associated with it. + /// + /// + /// To retrieve the value of the numeric parameter for a local policy, use the IFhConfigMgr::GetLocalPolicy method. + /// To set the value of the numeric parameter for the local policy, use the IFhConfigMgr::SetLocalPolicy method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_local_policy_type typedef enum _FH_LOCAL_POLICY_TYPE { + // FH_FREQUENCY, FH_RETENTION_TYPE, FH_RETENTION_AGE, MAX_LOCAL_POLICY } FH_LOCAL_POLICY_TYPE, *PFH_LOCAL_POLICY_TYPE; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_LOCAL_POLICY_TYPE")] + public enum FH_LOCAL_POLICY_TYPE + { + /// + /// This local policy specifies how frequently backups are to be performed for the current user. The numeric parameter contains + /// the time, in seconds, from the end of one backup until the start of the next one. The default value of the numeric parameter + /// for this policy is 3600 seconds (1 hour). + /// + FH_FREQUENCY, + + /// + /// This local policy specifies when previous versions of files and folders can be deleted from a backup target. See the + /// FH_RETENTION_TYPES enumeration for the list of possible values. The default value of the numeric parameter for this policy + /// is FH_RETENTION_DISABLED. + /// + FH_RETENTION_TYPE, + + /// + /// This local policy specifies the minimum age of previous versions that can be deleted from a backup target when the + /// FH_RETENTION_AGE_BASED retention type is specified. For more information, see the FH_RETENTION_TYPES enumeration. The + /// numeric parameter contains the minimum age, in days. The default value of the numeric parameter for this policy is 365 days + /// (1 year). + /// + FH_RETENTION_AGE, + } + + /// Specifies the type of an inclusion or exclusion list. + /// + /// + /// To retrieve the inclusion and exclusion rules that are currently stored in an FhConfigMgr object, call the + /// IFhConfigMgr::GetIncludeExcludeRules method. + /// + /// To add or remove an exclusion rule, call the IFhConfigMgr::AddRemoveExcludeRule method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_protected_item_category typedef enum + // _FH_PROTECTED_ITEM_CATEGORY { FH_FOLDER, FH_LIBRARY, MAX_PROTECTED_ITEM_CATEGORY } FH_PROTECTED_ITEM_CATEGORY, *PFH_PROTECTED_ITEM_CATEGORY; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_PROTECTED_ITEM_CATEGORY")] + public enum FH_PROTECTED_ITEM_CATEGORY + { + /// The inclusion or exclusion list is a list of folders. + FH_FOLDER, + + /// The inclusion or exclusion list is a list of libraries. + FH_LIBRARY, + } + + /// Specifies under what conditions previous versions of files and folders can be deleted from a backup target. + /// + /// + /// The operating system deletes previous versions from a backup target only when the target is full or when the user has initiated + /// data retention manually by using the File History item in Control Panel. + /// + /// + /// If FH_RETENTION_AGE_BASED is specified and the target is large enough, it is possible for the target to contain versions + /// that are much older than the minimum age that is specified by the FH_RETENTION_AGE local policy. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_retention_types typedef enum _FH_RETENTION_TYPES { + // FH_RETENTION_DISABLED, FH_RETENTION_UNLIMITED, FH_RETENTION_AGE_BASED, MAX_RETENTION_TYPE } FH_RETENTION_TYPES; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_RETENTION_TYPES")] + public enum FH_RETENTION_TYPES + { + /// Previous versions are never deleted from the backup target. + FH_RETENTION_DISABLED, + + /// + /// The operating system can delete any previous version on an as-needed basis, unless it is the most recent version of a file + /// that currently exists and is within the protection scope. + /// + FH_RETENTION_UNLIMITED, + + /// + /// The operating system can delete any previous version older than the specified minimum age on as-needed basis, unless it is + /// the most recent version of a file that currently exists and is within the protection scope. The minimum age is specified by + /// the FH_RETENTION_AGE local policy. + /// + FH_RETENTION_AGE_BASED, + } + + /// The current File History protection state. + [PInvokeData("fhstatus.h")] + public enum FH_STATE + { + /// + /// The File History protection state is unknown, because the File History service is not started or the current user is not + /// tracked in it. This value cannot be ORed with FH_STATE_RUNNING (0x100). + /// + FH_STATE_NOT_TRACKED = 0x00, + + /// + /// File History protection is not enabled for the current user. No files will be backed up. This value cannot be ORed with + /// FH_STATE_RUNNING (0x100). + /// + FH_STATE_OFF = 0x01, + + /// + /// File History protection is disabled by Group Policy. No files will be backed up. This value cannot be ORed with + /// FH_STATE_RUNNING (0x100). + /// + FH_STATE_DISABLED_BY_GP = 0x02, + + /// + /// There is a fatal error in one of the files that store internal File History information for the current user. No files will + /// be backed up. This value cannot be ORed with FH_STATE_RUNNING (0x100). + /// + FH_STATE_FATAL_CONFIG_ERROR = 0x03, + + /// + /// The current user does not have write permission for the currently assigned target. Backup copies of file versions will not + /// be created. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the + /// current user right now. + /// + FH_STATE_TARGET_ACCESS_DENIED = 0x0E, + + /// + /// The currently assigned target has been marked as dirty. Backup copies of file versions will not be created until after the + /// Chkdsk utility is run. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being + /// performed for the current user right now. + /// + FH_STATE_TARGET_VOLUME_DIRTY = 0x0F, + + /// + /// The currently assigned target does not have sufficient space for storing backup copies of files from the File History + /// protection scope, and retention is already set to the most aggressive policy. File History will provide a degraded level of + /// protection. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the + /// current user right now. + /// + FH_STATE_TARGET_FULL_RETENTION_MAX = 0x10, + + /// + /// The currently assigned target does not have sufficient space for storing backup copies of files from the File History + /// protection scope. File History will provide a degraded level of protection. This value can be ORed with FH_STATE_RUNNING + /// (0x100) to indicate that a backup cycle is being performed for the current user right now. + /// + FH_STATE_TARGET_FULL = 0x11, + + /// + /// The File History cache on one of the local disks does not have sufficient space for storing backup copies of files from the + /// File History protection scope temporarily. File History will provide a degraded level of protection. This value can be ORed + /// with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the current user right now. + /// + FH_STATE_STAGING_FULL = 0x12, + + /// + /// The currently assigned target is running low on free space, and retention is already set to the most aggressive policy. The + /// level of File History protection is likely to degrade soon. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate + /// that a backup cycle is being performed for the current user right now. + /// + FH_STATE_TARGET_LOW_SPACE_RETENTION_MAX = 0x13, + + /// + /// The currently assigned target is running low on free space. The level of File History protection is likely to degrade soon. + /// This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the current user + /// right now. + /// + FH_STATE_TARGET_LOW_SPACE = 0x14, + + /// + /// The currently assigned target has not been available for backups for a substantial period of time, causing File History + /// level of protection to start degrading. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle + /// is being performed for the current user right now. + /// + FH_STATE_TARGET_ABSENT = 0x15, + + /// + /// Too many changes have been made in the protected files or the protection scope. File History level of protection is likely + /// to degrade, unless the user explicitly initiates an immediate backup instead of relying on regular backup cycles to be + /// performed in the background. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being + /// performed for the current user right now. + /// + FH_STATE_TOO_MUCH_BEHIND = 0xF0, + + /// + /// File History backups are performed regularly, no error conditions are detected, an optimal level of File History protection + /// is provided. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the + /// current user right now. + /// + FH_STATE_NO_ERROR = 0xFF, + + /// + /// Indicates that File History is in a depreciated state where backup is not supported. This is only applicable if the user has + /// an existing backup configured. + /// + FH_STATE_BACKUP_NOT_SUPPORTED = 0x810, + + /// File History backups are currently running. + FH_STATE_RUNNING = 0x100 + } + + /// Specifies the type of a File History backup target. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_target_drive_types typedef enum _FH_TARGET_DRIVE_TYPES { + // FH_DRIVE_UNKNOWN, FH_DRIVE_REMOVABLE, FH_DRIVE_FIXED, FH_DRIVE_REMOTE } FH_TARGET_DRIVE_TYPES; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_TARGET_DRIVE_TYPES")] + public enum FH_TARGET_DRIVE_TYPES + { + /// The type of the backup target is unknown. + FH_DRIVE_UNKNOWN, + + /// The backup target is a locally attached removable storage device, such as a USB thumb drive. + FH_DRIVE_REMOVABLE, + + /// The backup target is a locally attached nonremovable storage device, such as an internal hard drive. + FH_DRIVE_FIXED, + + /// + /// The backup target is a storage device that is accessible over network, such as a computer that is running Windows Home Server. + /// + FH_DRIVE_REMOTE, + } + + /// Specifies the type of a property of a backup target. + /// + /// + /// To query a backup target property, call the IFhTarget::GetStringProperty method or the IFhTarget::GetNumericalProperty method. + /// + /// + /// For local disks, the FH_TARGET_URL property contains the drive letter. This path must end with a trailing backslash (for + /// example, "X:"). + /// + /// + /// For network shares, the FH_TARGET_URL property contains the full path of the share. This path must end with a trailing + /// backslash (for example, "\myserver\myshare"). + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/ne-fhcfg-fh_target_property_type typedef enum _FH_TARGET_PROPERTY_TYPE { + // FH_TARGET_NAME, FH_TARGET_URL, FH_TARGET_DRIVE_TYPE, MAX_TARGET_PROPERTY } FH_TARGET_PROPERTY_TYPE, *PFH_TARGET_PROPERTY_TYPE; + [PInvokeData("fhcfg.h", MSDNShortId = "NE:fhcfg._FH_TARGET_PROPERTY_TYPE")] + public enum FH_TARGET_PROPERTY_TYPE + { + /// + /// The property is a string that contains the backup target’s friendly name. The friendly name is set during target + /// provisioning by calling the IFhConfigMgr::ProvisionAndSetNewTarget method. + /// + FH_TARGET_NAME, + + /// The property is a string that contains a path to the backup target. + FH_TARGET_URL, + + /// + /// + /// The property is a numeric property that specifies the target type of the backup target. See the FH_TARGET_DRIVE_TYPES + /// enumeration for the list of possible backup target types. + /// + /// + FH_TARGET_DRIVE_TYPE, + } + + /// + /// + /// The IFhConfigMgr interface allows client applications to read and modify the File History configuration for the user + /// account under which the methods of this interface are called. + /// + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nn-fhcfg-ifhconfigmgr + [PInvokeData("fhcfg.h", MSDNShortId = "NN:fhcfg.IFhConfigMgr")] + [ComImport, Guid("6A5FEA5B-BF8F-4EE5-B8C3-44D8A0D7331C"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(FhConfigMgr))] + public interface IFhConfigMgr + { + /// + /// Loads the File History configuration information for the current user into an FhConfigMgr object. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// This method or the IFhConfigMgr::CreateDefaultConfiguration method must be called before any other IFhConfigMgr method can + /// be called. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-loadconfiguration HRESULT LoadConfiguration(); + void LoadConfiguration(); + + /// + /// + /// Creates File History configuration files with default settings for the current user and loads them into an FhConfigMgr object. + /// + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// + /// If File History configuration files already exist for the current user and this parameter is set to TRUE, those files + /// are overwritten and all previous settings and policies are reset to default values. + /// + /// + /// If File History configuration files already exist for the current user and this parameter is set to FALSE, those + /// files are not overwritten and an unsuccessful HRESULT value is returned. + /// + /// + /// This method or the LoadConfiguration method must be called before any other IFhConfigMgr method can be called. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-createdefaultconfiguration HRESULT + // CreateDefaultConfiguration( BOOL OverwriteIfExists ); + void CreateDefaultConfiguration([MarshalAs(UnmanagedType.Bool)] bool OverwriteIfExists); + + /// + /// + /// Saves to disk all the changes that were made in an FhConfigMgr object since the last time that the LoadConfiguration, + /// CreateDefaultConfiguration or SaveConfiguration method was called for the File History configuration files of the + /// current user. + /// + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// This method can be called as many times as needed during the lifetime of an FhConfigMgr object. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-saveconfiguration HRESULT SaveConfiguration(); + void SaveConfiguration(); + + /// + /// Adds an exclusion rule to the exclusion list or removes a rule from the list. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// If this parameter is TRUE, a new exclusion rule is added. If it is set to FALSE, an existing exclusion rule is removed. + /// + /// + /// Specifies the type of the exclusion rule. See the FH_PROTECTED_ITEM_CATEGORY enumeration for possible values. + /// + /// The folder path or library name or GUID of the item that the exclusion rule applies to. + /// + /// + /// The File History protection scope is the set of files that are backed up by the File History feature. It contains inclusion + /// rules and exclusion rules. Inclusion rules specify the files and folders that are included. Exclusion rules specify the + /// files and folders that are excluded. + /// + /// + /// The default protection scope includes all folders from all user libraries and the Contacts, Desktop, and Favorites folders. + /// + /// + /// Exclusion rules take precedence over inclusion rules. In other words, if an inclusion rule conflicts with an exclusion rule, + /// the File History feature follows the exclusion rule. + /// + /// To reduce the protection scope, use the IFhConfigMgr::AddRemoveExcludeRule to add exclusion rules. + /// This method can be used to add or remove exclusion rules. It cannot be used to modify inclusion rules. + /// + /// User libraries can be enumerated by calling the SHGetKnownFolderItem function and the methods of the IShellItem and + /// IEnumShellItems interfaces. + /// + /// + /// Standard folders and libraries are specified by a GUID, prefixed with an asterisk. For example, + /// *a990ae9f-a03b-4e80-94bc-9912d7504104 specifies the Pictures library. For a list of standard folders and libraries and their + /// GUIDs, see the KNOWNFOLDERID documentation. + /// + /// Custom libraries are specified by name. Folders are specified by their full path (for example, C:\Users\Public\Videos). + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-addremoveexcluderule HRESULT + // AddRemoveExcludeRule( BOOL Add, FH_PROTECTED_ITEM_CATEGORY Category, BSTR Item ); + void AddRemoveExcludeRule([MarshalAs(UnmanagedType.Bool)] bool Add, FH_PROTECTED_ITEM_CATEGORY Category, [MarshalAs(UnmanagedType.BStr)] string Item); + + /// + /// Retrieves the inclusion and exclusion rules that are currently stored in an FhConfigMgr object. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// If set to TRUE, inclusion rules are returned. If set to FALSE, exclusion rules are returned. + /// + /// + /// An FH_PROTECTED_ITEM_CATEGORY enumeration value that specifies the type of the inclusion or exclusion rules. + /// + /// Receives an IFhScopeIterator interface pointer that can be used to enumerate the rules in the requested category. + /// + /// + /// The File History protection scope is the set of files that are backed up by this feature. It contains inclusion rules and + /// exclusion rules. Inclusion rules specify the files and folders that are included. Exclusion rules specify the files and + /// folders that are excluded. + /// + /// + /// The default protection scope includes all folders from all user libraries and the Contacts, Desktop, and Favorites folders. + /// + /// + /// You can modify the File History protection scope by adding exclusion rules to reduce the File History protection scope + /// without removing folders from user libraries. + /// + /// + /// Exclusion rules take precedence over inclusion rules. In other words, if an inclusion rule conflicts with an exclusion rule, + /// the File History feature follows the exclusion rule. + /// + /// + /// The IFhConfigMgr::AddRemoveExcludeRule method can be used to add or remove exclusion rules. It cannot be used to modify the + /// inclusion rules. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-getincludeexcluderules HRESULT + // GetIncludeExcludeRules( BOOL Include, FH_PROTECTED_ITEM_CATEGORY Category, IFhScopeIterator **Iterator ); + IFhScopeIterator GetIncludeExcludeRules([MarshalAs(UnmanagedType.Bool)] bool Include, FH_PROTECTED_ITEM_CATEGORY Category); + + /// + /// Retrieves the numeric parameter for a local policy for the File History feature. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// Specifies the local policy. + /// Receives the value of the numeric parameter for the specified local policy. + /// + /// + /// Each local policy contains a numeric parameter that specifies how or when the File History feature backs up files and + /// folders. See the FH_LOCAL_POLICY_TYPE enumeration for more information about the local policies that can be specified. + /// + /// To set the numeric parameter value for a local policy, use the IFhConfigMgr::SetLocalPolicy method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-getlocalpolicy HRESULT GetLocalPolicy( + // FH_LOCAL_POLICY_TYPE LocalPolicyType, ULONGLONG *PolicyValue ); + ulong GetLocalPolicy(FH_LOCAL_POLICY_TYPE LocalPolicyType); + + /// + /// Changes the numeric parameter value of a local policy in an FhConfigMgr object. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// Specifies the local policy. + /// Specifies the new value of the numeric parameter for the specified local policy. + /// + /// + /// Each local policy contains a numeric parameter that specifies how or when the File History feature backs up files and + /// folders. See the FH_LOCAL_POLICY_TYPE enumeration for more information about the local policies that can be specified. + /// + /// To retrieve the numeric parameter value for a local policy, use the IFhConfigMgr::GetLocalPolicy method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-setlocalpolicy HRESULT SetLocalPolicy( + // FH_LOCAL_POLICY_TYPE LocalPolicyType, ULONGLONG PolicyValue ); + void SetLocalPolicy(FH_LOCAL_POLICY_TYPE LocalPolicyType, ulong PolicyValue); + + /// + /// Retrieves the backup status value for an FhConfigMgr object. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// Receives the backup status value. See the FH_BACKUP_STATUS enumeration for the list of possible backup status values. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-getbackupstatus HRESULT GetBackupStatus( + // FH_BACKUP_STATUS *BackupStatus ); + FH_BACKUP_STATUS GetBackupStatus(); + + /// + /// Changes the backup status value for an FhConfigMgr object. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// The backup status value. See the FH_BACKUP_STATUS enumeration for a list of possible backup status values. + /// + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values + /// include values defined in the FhErrors.h header file. + /// + /// FH_STATUS_DISABLED_BY_GP is not a valid value for the BackupStatus parameter. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-setbackupstatus HRESULT SetBackupStatus( + // FH_BACKUP_STATUS BackupStatus ); + void SetBackupStatus(FH_BACKUP_STATUS BackupStatus); + + /// + /// + /// Returns a pointer to an IFhTarget interface that can be used to query information about the currently assigned backup target. + /// + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// Receives a pointer to the IFhTarget interface of an object that represents the currently assigned default target, or + /// NULL if there is no default target. + /// + /// + /// If no backup target is currently assigned, this method returns + /// HRESULT_FROM_WIN32(ERROR_NOT_FOUND) + /// . + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-getdefaulttarget HRESULT GetDefaultTarget( + // IFhTarget **DefaultTarget ); + IFhTarget GetDefaultTarget(); + + /// + /// Checks whether a certain storage device or network share can be used as a File History backup target. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// The storage device or network share to be validated. + /// + /// Receives the result of the device validation. See the FH_DEVICE_VALIDATION_RESULT enumeration for the list of possible + /// device validation result values. + /// + /// + /// + /// For local disks, the TargetUrl parameter contains the drive letter. This path must end with a trailing backslash (for + /// example, "X:"). + /// + /// + /// For network shares, the TargetUrl parameter contains the full path of the share. This path must end with a trailing + /// backslash (for example, "\myserver\myshare"). + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-validatetarget HRESULT ValidateTarget( BSTR + // TargetUrl, PFH_DEVICE_VALIDATION_RESULT ValidationResult ); + FH_DEVICE_VALIDATION_RESULT ValidateTarget([MarshalAs(UnmanagedType.BStr)] string TargetUrl); + + /// + /// + /// Provisions a certain storage device or network share as a File History backup target and assigns it as the default backup + /// target for the current user. + /// + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// Specifies the storage device or network share to be provisioned and assigned as the default. + /// Specifies a user-friendly name for the specified backup target. + /// + /// + /// For local disks, the TargetUrl parameter contains the drive letter. This path must end with a trailing backslash (for + /// example, "X:"). + /// + /// + /// For network shares, the TargetUrl parameter contains the full path of the share. This path must end with a trailing + /// backslash (for example, "\myserver\myshare"). + /// + /// + /// It is highly recommended that the storage device or network share specified by the TargetUrl parameter be validated first + /// using the IFhConfigMgr::ValidateTarget method. If ValidateTarget returns a validation result other than + /// FH_VALID_TARGET, assigning this storage device or network share as the default backup target may have unpredictable consequences. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-provisionandsetnewtarget HRESULT + // ProvisionAndSetNewTarget( BSTR TargetUrl, BSTR TargetName ); + void ProvisionAndSetNewTarget([MarshalAs(UnmanagedType.BStr)] string TargetUrl, [MarshalAs(UnmanagedType.BStr)] string TargetName); + + /// + /// + /// Causes the currently assigned backup target to be recommended or not recommended to other members of the home group that the + /// computer belongs to. + /// + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// If set to TRUE, the currently assigned backup target is recommended to other members of the home group. If set to + /// FALSE and the currently assigned backup target is currently recommended to other members of the home group, this + /// recommendation is withdrawn. + /// + /// + /// + /// When a backup target is recommended to other computers in the home group, users on those computers see that storage device + /// in the list of available backup targets in the File History item in Control Panel. + /// + /// + /// If the backup target is not recommended to other computers in the home group, or if the recommendation is withdrawn, the + /// target does not appear in the list of available backup targets on the other computers. + /// + /// + /// A backup target cannot be recommended or not recommended on a computer that is joined to a domain or on a computer that is + /// having ARM architecture. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-changedefaulttargetrecommendation HRESULT + // ChangeDefaultTargetRecommendation( BOOL Recommend ); + void ChangeDefaultTargetRecommendation([MarshalAs(UnmanagedType.Bool)] bool Recommend); + + /// + /// Retrieves the current File History protection state. + /// IFhConfigMgr is deprecated and may be altered or unavailable in future releases. + /// + /// + /// + /// On return, this parameter receives the current File History protection state. The following protection states are defined in + /// the FhStatus.h header file. + /// + /// + /// + /// Value + /// Meaning + /// + /// + /// FH_STATE_NOT_TRACKED 0x00 + /// + /// The File History protection state is unknown, because the File History service is not started or the current user is not + /// tracked in it. This value cannot be ORed with FH_STATE_RUNNING (0x100). + /// + /// + /// + /// FH_STATE_OFF 0x01 + /// + /// File History protection is not enabled for the current user. No files will be backed up. This value cannot be ORed with + /// FH_STATE_RUNNING (0x100). + /// + /// + /// + /// FH_STATE_DISABLED_BY_GP 0x02 + /// + /// File History protection is disabled by Group Policy. No files will be backed up. This value cannot be ORed with + /// FH_STATE_RUNNING (0x100). + /// + /// + /// + /// FH_STATE_FATAL_CONFIG_ERROR 0x03 + /// + /// There is a fatal error in one of the files that store internal File History information for the current user. No files will + /// be backed up. This value cannot be ORed with FH_STATE_RUNNING (0x100). + /// + /// + /// + /// FH_STATE_TARGET_ACCESS_DENIED 0x0E + /// + /// The current user does not have write permission for the currently assigned target. Backup copies of file versions will not + /// be created. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the + /// current user right now. + /// + /// + /// + /// FH_STATE_TARGET_VOLUME_DIRTY 0x0F + /// + /// The currently assigned target has been marked as dirty. Backup copies of file versions will not be created until after the + /// Chkdsk utility is run. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being + /// performed for the current user right now. + /// + /// + /// + /// FH_STATE_TARGET_FULL_RETENTION_MAX 0x10 + /// + /// The currently assigned target does not have sufficient space for storing backup copies of files from the File History + /// protection scope, and retention is already set to the most aggressive policy. File History will provide a degraded level of + /// protection. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the + /// current user right now. + /// + /// + /// + /// FH_STATE_TARGET_FULL 0x11 + /// + /// The currently assigned target does not have sufficient space for storing backup copies of files from the File History + /// protection scope. File History will provide a degraded level of protection. This value can be ORed with FH_STATE_RUNNING + /// (0x100) to indicate that a backup cycle is being performed for the current user right now. + /// + /// + /// + /// FH_STATE_STAGING_FULL 0x12 + /// + /// The File History cache on one of the local disks does not have sufficient space for storing backup copies of files from the + /// File History protection scope temporarily. File History will provide a degraded level of protection. This value can be ORed + /// with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the current user right now. + /// + /// + /// + /// FH_STATE_TARGET_LOW_SPACE_RETENTION_MAX 0x13 + /// + /// The currently assigned target is running low on free space, and retention is already set to the most aggressive policy. The + /// level of File History protection is likely to degrade soon. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate + /// that a backup cycle is being performed for the current user right now. + /// + /// + /// + /// FH_STATE_TARGET_LOW_SPACE 0x14 + /// + /// The currently assigned target is running low on free space. The level of File History protection is likely to degrade soon. + /// This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the current user + /// right now. + /// + /// + /// + /// FH_STATE_TARGET_ABSENT 0x15 + /// + /// The currently assigned target has not been available for backups for a substantial period of time, causing File History + /// level of protection to start degrading. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle + /// is being performed for the current user right now. + /// + /// + /// + /// FH_STATE_TOO_MUCH_BEHIND 0x16 + /// + /// Too many changes have been made in the protected files or the protection scope. File History level of protection is likely + /// to degrade, unless the user explicitly initiates an immediate backup instead of relying on regular backup cycles to be + /// performed in the background. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being + /// performed for the current user right now. + /// + /// + /// + /// FH_STATE_NO_ERROR 0xFF + /// + /// File History backups are performed regularly, no error conditions are detected, an optimal level of File History protection + /// is provided. This value can be ORed with FH_STATE_RUNNING (0x100) to indicate that a backup cycle is being performed for the + /// current user right now. + /// + /// + /// + /// + /// + /// + /// Receives a pointer to a string allocated with SysAllocString containing the date and time until which all files within the + /// File History protection scope are protected. The date and time are formatted per the system locale. If the date and time are + /// unknown, an empty string is returned. + /// + /// A file is considered protected until a certain point in time if one of the following conditions is true: + /// + /// + /// + /// There is a version of that file that was captured at or after that point in time and was fully copied to the currently + /// assigned backup target before now. + /// + /// + /// + /// The file was created or included in the File History protection scope at or after that point in time. + /// + /// + /// + /// + /// The caller is responsible for releasing the memory allocated for ProtectedUntilTime by calling SysFreeString on it. + /// + /// The protection state indicates the File History operational state and the date and time until which all files within the + /// protection scope are protected. + /// + /// If the target is full or disconnected, the File History feature will provide a degraded level of protection as follows: + /// + /// + /// Files will be backed up to the File History cache on one of the local disks. + /// + /// + /// If the cache fills up during this time, older copies will be deleted from the cache to back up newer copies. + /// + /// + /// If the target is low on free space, the degraded level of protection will start once the target becomes full. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhconfigmgr-queryprotectionstatus HRESULT + // QueryProtectionStatus( DWORD *ProtectionState, BSTR *ProtectedUntilTime ); + void QueryProtectionStatus(out FH_STATE ProtectionState, [MarshalAs(UnmanagedType.BStr)] out string ProtectedUntilTime); + } + + /// + /// + /// This interface allows client applications to reassociate a File History configuration from a File History target with the + /// current user. Reassociation serves two purposes: + /// + /// + /// + /// + /// It allows the user to access the data that was backed up to the target in the past, possibly from a different computer or under + /// a different account. + /// + /// + /// + /// It allows the user to continue to back up data to the target, possibly on a new computer or under a new account name. + /// + /// + /// IFhReassociation is deprecated and may be altered or unavailable in future releases. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nn-fhcfg-ifhreassociation + [PInvokeData("fhcfg.h", MSDNShortId = "NN:fhcfg.IFhReassociation")] + [ComImport, Guid("6544A28A-F68D-47ac-91EF-16B2B36AA3EE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown), CoClass(typeof(FhReassociation))] + public interface IFhReassociation + { + /// + /// + /// This method checks whether a certain storage device or network share can be used as a File History default target and, thus, + /// whether reassociation is possible at all or not. + /// + /// IFhReassociation is deprecated and may be altered or unavailable in future releases. + /// + /// Specifies the storage device or network share to be validated. + /// + /// On return, contains a value specifying the result of the device validation. See the FH_DEVICE_VALIDATION_RESULT enumeration + /// for a detailed description of supported device validation results. + /// + /// + /// + /// For local disks, the TargetUrl parameter contains the drive letter. This path must end with a trailing backslash (for + /// example, "X:"). + /// + /// + /// For network shares, the TargetUrl parameter contains the full path of the share. This path must end with a trailing + /// backslash (for example, "\myserver\myshare"). + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhreassociation-validatetarget HRESULT ValidateTarget( + // BSTR TargetUrl, PFH_DEVICE_VALIDATION_RESULT ValidationResult ); + FH_DEVICE_VALIDATION_RESULT ValidateTarget([MarshalAs(UnmanagedType.BStr)] string TargetUrl); + + /// + /// + /// Scans the namespace on a specified storage device or network share for File History configurations that can be reassociated + /// with and continued to be used on the current computer. + /// + /// IFhReassociation is deprecated and may be altered or unavailable in future releases. + /// + /// Specifies the storage device or network share to be scanned. + /// + /// + /// For local disks, the TargetUrl parameter contains the drive letter. This path must end with a trailing backslash (for + /// example, "X:"). + /// + /// + /// For network shares, the TargetUrl parameter contains the full path of the share. This path must end with a trailing + /// backslash (for example, "\myserver\myshare"). + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhreassociation-scantargetforconfigurations HRESULT + // ScanTargetForConfigurations( BSTR TargetUrl ); + void ScanTargetForConfigurations([MarshalAs(UnmanagedType.BStr)] string TargetUrl); + + /// + /// + /// This method enumerates File History configurations that were discovered on a storage device or network share by the + /// IFhReassociation::ScanTargetForConfigurations method and returns additional information about each of the discovered configurations. + /// + /// IFhReassociation is deprecated and may be altered or unavailable in future releases. + /// + /// Zero-based index of a discovered configuration. + /// + /// On return, contains a pointer to a string allocated with SysAllocString containing the name of the user account under which + /// the configuration was last backed up to. + /// + /// + /// On return, contains a pointer to a string allocated with SysAllocString containing the name of the computer from which the + /// configuration was last backed up. + /// + /// On return, contains the date and time when the configuration was last backed up. + /// + /// + /// The caller is responsible for releasing the memory allocated for UserName and PcName by calling SysFreeString on each of them. + /// + /// + /// In order to perform reassociation, one of the configurations enumerated by this method must be selected using the + /// IFhReassociation::SelectConfiguration method and then the IFhReassociation::PerformReassociation method needs to be called. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhreassociation-getconfigurationdetails HRESULT + // GetConfigurationDetails( DWORD Index, BSTR *UserName, BSTR *PcName, FILETIME *BackupTime ); + void GetConfigurationDetails(uint Index, [MarshalAs(UnmanagedType.BStr)] out string UserName, [MarshalAs(UnmanagedType.BStr)] out string PcName, out FILETIME BackupTime); + + /// + /// + /// Selects one of the File History configurations discovered on a storage device or network share by the + /// IFhReassociation::ScanTargetForConfigurations method for subsequent reassociation. Actual reassociation is performed by the + /// IFhReassociation::PerformReassociation method. + /// + /// IFhReassociation is deprecated and may be altered or unavailable in future releases. + /// + /// Zero-based index of a discovered configuration. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhreassociation-selectconfiguration HRESULT + // SelectConfiguration( DWORD Index ); + void SelectConfiguration(uint Index); + + /// + /// + /// This method re-establishes relationship between the current user and the configuration selected previously via the + /// IFhReassociation::SelectConfiguration method and prepares the target device for accepting backup data from the current computer. + /// + /// IFhReassociation is deprecated and may be altered or unavailable in future releases. + /// + /// + /// This parameter specifies how to handle the current File History configuration, if it already exists. + /// + /// If this parameter is set to FALSE and File History is already configured for the current user, this method fails with + /// the FHCFG_E_CONFIG_ALREADY_EXISTS error code and backups continue to be performed to the already configured target device. + /// + /// + /// If this parameter is set to TRUE and File History is already configured for the current user, the current + /// configuration is replaced with the selected one and future backups after performed to the target device containing the + /// selected configuration. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhreassociation-performreassociation HRESULT + // PerformReassociation( BOOL OverwriteIfExists ); + void PerformReassociation([MarshalAs(UnmanagedType.Bool)] bool OverwriteIfExists); + } + + /// + /// + /// The IFhScopeIterator interface allows client applications to enumerate individual items in an inclusion or exclusion + /// list. To retrieve inclusion and exclusion lists, call the IFhConfigMgr::GetIncludeExcludeRules method. + /// + /// IFhScopeIterator is deprecated and may be altered or unavailable in future releases. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nn-fhcfg-ifhscopeiterator + [PInvokeData("fhcfg.h", MSDNShortId = "NN:fhcfg.IFhScopeIterator")] + [ComImport, Guid("3197ABCE-532A-44C6-8615-F3666566A720"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IFhScopeIterator + { + /// + /// Moves to the next item in the inclusion or exclusion list. + /// IFhScopeIterator is deprecated and may be altered or unavailable in future releases. + /// + /// + /// S_OK on success, or an unsuccessful HRESULT on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + /// + /// If the current item is the last item in the list, or if the list is empty, this method returns + /// HRESULT_FROM_WIN32(ERROR_NOT_FOUND) + /// . + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhscopeiterator-movetonextitem HRESULT MoveToNextItem(); + [PreserveSig] + HRESULT MoveToNextItem(); + + /// + /// Retrieves the current item in an inclusion or exclusion list. + /// IFhScopeIterator is deprecated and may be altered or unavailable in future releases. + /// + /// + /// On output, it receives a pointer to a string that contains the current element of the list. This element is a library name + /// or a folder name, depending on the parameters that were passed to the IFhConfigMgr::GetIncludeExcludeRules method. The + /// string is allocated by calling SysAllocString. You must call SysFreeString to free the string when it is no longer needed. + /// + /// To move to the next item in the inclusion or exclusion list, call the IFhScopeIterator::MoveToNextItem method. + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhscopeiterator-getitem HRESULT GetItem( BSTR *Item ); + [return: MarshalAs(UnmanagedType.BStr)] + string GetItem(); + } + + /// + /// + /// The IFhTarget interface allows client applications to read numeric and string properties of a File History backup target. + /// + /// IFhTarget is deprecated and may be altered or unavailable in future releases. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nn-fhcfg-ifhtarget + [PInvokeData("fhcfg.h", MSDNShortId = "NN:fhcfg.IFhTarget")] + [ComImport, Guid("D87965FD-2BAD-4657-BD3B-9567EB300CED"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IFhTarget + { + /// + /// Retrieves a string property of the File History backup target that is represented by an IFhTarget interface. + /// IFhTarget is deprecated and may be altered or unavailable in future releases. + /// + /// + /// Specifies the string property. See the FH_TARGET_PROPERTY_TYPE enumeration for the list of possible string property types. + /// + /// + /// This parameter must be NULL on input. On output, it receives a pointer to a string that contains the string property. + /// This string is allocated by calling SysAllocString. You must call SysFreeString to free the string when it is no longer needed. + /// + /// + /// The FH_TARGET_PROPERTY_TYPE enumeration defines property types for string properties and numeric properties. However, the + /// IFhTarget::GetStringProperty method can only be used to retrieve string properties. Numeric properties must be + /// retrieved by calling the IFhTarget::GetNumericalProperty method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhtarget-getstringproperty HRESULT GetStringProperty( + // FH_TARGET_PROPERTY_TYPE PropertyType, BSTR *PropertyValue ); + [return: MarshalAs(UnmanagedType.BStr)] + string GetStringProperty(FH_TARGET_PROPERTY_TYPE PropertyType); + + /// + /// Retrieves a numeric property of the File History backup target that is represented by an IFhTarget interface. + /// IFhTarget is deprecated and may be altered or unavailable in future releases. + /// + /// + /// Specifies the numeric property. See the FH_TARGET_PROPERTY_TYPE enumeration for a list of possible numeric properties. + /// + /// Receives the value of the numeric property. + /// + /// The FH_TARGET_PROPERTY_TYPE enumeration defines property types for string properties and numeric properties. However, the + /// IFhTarget::GetNumericalProperty method can only be used to retrieve numeric properties. String properties must be + /// retrieved by calling the IFhTarget::GetStringProperty method. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhcfg/nf-fhcfg-ifhtarget-getnumericalproperty HRESULT + // GetNumericalProperty( FH_TARGET_PROPERTY_TYPE PropertyType, ULONGLONG *PropertyValue ); + ulong GetNumericalProperty(FH_TARGET_PROPERTY_TYPE PropertyType); + } + + /// + /// This function temporarily blocks backups for the current user. + /// FhServiceBlockBackup is deprecated and may be altered or unavailable in future releases. + /// + /// The communication channel handle returned by an earlier FhServiceOpenPipe call. + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + /// + /// + /// This function instructs the File History Service to not perform backups for the current user until the FhServiceUnblockBackup + /// function is called or the communication channel with the File History Service is closed by calling FhServiceClosePipe. + /// + /// + /// Call this function prior to performing File History configuration reassociation to ensure that File History configuration and + /// data files are not currently in use. (Otherwise, the IFhReassociation::PerformReassociation method may fail.) + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhserviceblockbackup HRESULT FhServiceBlockBackup( + // FH_SERVICE_PIPE_HANDLE Pipe ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceBlockBackup")] + public static extern HRESULT FhServiceBlockBackup(FH_SERVICE_PIPE_HANDLE Pipe); + + /// + /// Closes a communication channel to the File History Service opened with FhServiceOpenPipe. + /// FhServiceClosePipe is deprecated and may be altered or unavailable in future releases. + /// + /// The communication channel handle returned by an earlier FhServiceOpenPipe call. + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + /// + /// An application should call FhServiceClosePipe once for each communication channel handle it opens with FhServiceOpenPipe. + /// Closing a communication channel handle multiple times is not supported and may lead to unpredictable behavior. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhserviceclosepipe HRESULT FhServiceClosePipe( + // FH_SERVICE_PIPE_HANDLE Pipe ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceClosePipe")] + public static extern HRESULT FhServiceClosePipe(FH_SERVICE_PIPE_HANDLE Pipe); + + /// + /// Opens a communication channel to the File History Service. + /// FhServiceOpenPipe is deprecated and may be altered or unavailable in future releases. + /// + /// + /// + /// If the File History Service is not started yet and this parameter is TRUE, this function starts the File History Service + /// before opening a communication channel to it. + /// + /// + /// If the File History Service is not started yet and this parameter is FALSE, this function fails and returns an + /// unsuccessful HRESULT value. + /// + /// + /// + /// On successful return, this parameter contains a non-NULL handle representing a newly opened communication channel to the File + /// History Service. + /// + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhserviceopenpipe HRESULT FhServiceOpenPipe( BOOL + // StartServiceIfStopped, FH_SERVICE_PIPE_HANDLE *Pipe ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceOpenPipe")] + public static extern HRESULT FhServiceOpenPipe([MarshalAs(UnmanagedType.Bool)] bool StartServiceIfStopped, out SafeFH_SERVICE_PIPE_HANDLE Pipe); + + /// + /// This function causes the File History Service to reload the current user’s File History configuration files. + /// FhServiceReloadConfiguration is deprecated and may be altered or unavailable in future releases. + /// + /// The communication channel handle returned by an earlier FhServiceOpenPipe call. + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + /// + /// + /// This function causes the File History Service to schedule periodic backups for the current user if they have not been scheduled + /// yet and File History is enabled for that user. + /// + /// + /// It is recommended to call this function every time a policy is changed in File History configuration via the + /// IFhConfigMgr::SetLocalPolicy method. It should also be called after File History has been enabled or disabled for a user. + /// + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhservicereloadconfiguration HRESULT + // FhServiceReloadConfiguration( FH_SERVICE_PIPE_HANDLE Pipe ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceReloadConfiguration")] + public static extern HRESULT FhServiceReloadConfiguration(FH_SERVICE_PIPE_HANDLE Pipe); + + /// + /// This function starts an immediate backup for the current user. + /// FhServiceStartBackup is deprecated and may be altered or unavailable in future releases. + /// + /// The communication channel handle returned by an earlier FhServiceOpenPipe call. + /// + /// + /// If TRUE, the File History Service is instructed to use low priority I/O for the immediate backup scheduled by this + /// function. Low-priority I/O reduces impact on foreground user activities. It is recommended to set this parameter to TRUE. + /// + /// + /// If FALSE, the File History Service is instructed to use normal priority I/O for the immediate backup scheduled by this + /// function. This results in faster backups but negatively affects the responsiveness and performance of user applications. + /// + /// + /// + /// S_OK on success, or an unsuccessful HRESULT on failure. Possible unsuccessful HRESULT values include values + /// defined in the FhErrors.h header file. + /// + /// + /// + /// This function does not wait until the immediate backup completes. If an error or warning condition is encountered during backup, + /// it is communicated to the user via an Action Center notification and programmatically retrievable via the + /// IFhConfigMgr::QueryProtectionStatus method. + /// + /// A backup cycle initiated by calling this function can be stopped using the FhServiceStopBackup function. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhservicestartbackup HRESULT FhServiceStartBackup( + // FH_SERVICE_PIPE_HANDLE Pipe, BOOL LowPriorityIo ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceStartBackup")] + public static extern HRESULT FhServiceStartBackup(FH_SERVICE_PIPE_HANDLE Pipe, [MarshalAs(UnmanagedType.Bool)] bool LowPriorityIo); + + /// + /// This function stops an ongoing backup cycle for the current user. + /// FhServiceStopBackup is deprecated and may be altered or unavailable in future releases. + /// + /// The communication channel handle returned by an earlier FhServiceOpenPipe call. + /// + /// + /// If TRUE, this function both stops the ongoing backup cycle (if any) and prevents periodic backup cycles for the current + /// user in the future. + /// + /// If FALSE, this function only stops the ongoing backup cycle. + /// + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhservicestopbackup HRESULT FhServiceStopBackup( + // FH_SERVICE_PIPE_HANDLE Pipe, BOOL StopTracking ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceStopBackup")] + public static extern HRESULT FhServiceStopBackup(FH_SERVICE_PIPE_HANDLE Pipe, [MarshalAs(UnmanagedType.Bool)] bool StopTracking); + + /// + /// This function unblocks backups blocked via FhServiceBlockBackup. + /// FhServiceUnblockBackup is deprecated and may be altered or unavailable in future releases. + /// + /// The communication channel handle returned by an earlier FhServiceOpenPipe call. + /// + /// S_OK on success, or an unsuccessful HRESULT value on failure. Possible unsuccessful HRESULT values include + /// values defined in the FhErrors.h header file. + /// + /// + /// This function removes the effects of a prior FhServiceBlockBackup call issued via a given communication channel with the File + /// History Service. + /// + // https://docs.microsoft.com/en-us/windows/win32/api/fhsvcctl/nf-fhsvcctl-fhserviceunblockbackup HRESULT FhServiceUnblockBackup( + // FH_SERVICE_PIPE_HANDLE Pipe ); + [DllImport(Lib_FhSvcCtl, SetLastError = false, ExactSpelling = true)] + [PInvokeData("fhsvcctl.h", MSDNShortId = "NF:fhsvcctl.FhServiceUnblockBackup")] + public static extern HRESULT FhServiceUnblockBackup(FH_SERVICE_PIPE_HANDLE Pipe); + + /// Provides a handle to a communication channel. + [StructLayout(LayoutKind.Sequential)] + public struct FH_SERVICE_PIPE_HANDLE : IHandle + { + private readonly IntPtr handle; + + /// Initializes a new instance of the struct. + /// An object that represents the pre-existing handle to use. + public FH_SERVICE_PIPE_HANDLE(IntPtr preexistingHandle) => handle = preexistingHandle; + + /// Returns an invalid handle by instantiating a object with . + public static FH_SERVICE_PIPE_HANDLE NULL => new(IntPtr.Zero); + + /// Gets a value indicating whether this instance is a null handle. + public bool IsNull => handle == IntPtr.Zero; + + /// Performs an explicit conversion from to . + /// The handle. + /// The result of the conversion. + public static explicit operator IntPtr(FH_SERVICE_PIPE_HANDLE h) => h.handle; + + /// Performs an implicit conversion from to . + /// The pointer to a handle. + /// The result of the conversion. + public static implicit operator FH_SERVICE_PIPE_HANDLE(IntPtr h) => new(h); + + /// Implements the operator !=. + /// The first handle. + /// The second handle. + /// The result of the operator. + public static bool operator !=(FH_SERVICE_PIPE_HANDLE h1, FH_SERVICE_PIPE_HANDLE h2) => !(h1 == h2); + + /// Implements the operator ==. + /// The first handle. + /// The second handle. + /// The result of the operator. + public static bool operator ==(FH_SERVICE_PIPE_HANDLE h1, FH_SERVICE_PIPE_HANDLE h2) => h1.Equals(h2); + + /// + public override bool Equals(object obj) => obj is FH_SERVICE_PIPE_HANDLE h && handle == h.handle; + + /// + public override int GetHashCode() => handle.GetHashCode(); + + /// + public IntPtr DangerousGetHandle() => handle; + } + + /// Class interface for . + [ComImport, Guid("ED43BB3C-09E9-498a-9DF6-2177244C6DB4"), ClassInterface(ClassInterfaceType.None)] + public class FhConfigMgr { } + + /// Class interface for . + [ComImport, Guid("4D728E35-16FA-4320-9E8B-BFD7100A8846"), ClassInterface(ClassInterfaceType.None)] + public class FhReassociation { } + + /// Provides a for that is disposed using . + public class SafeFH_SERVICE_PIPE_HANDLE : SafeHANDLE + { + /// Initializes a new instance of the class and assigns an existing handle. + /// An object that represents the pre-existing handle to use. + /// + /// to reliably release the handle during the finalization phase; otherwise, (not recommended). + /// + public SafeFH_SERVICE_PIPE_HANDLE(IntPtr preexistingHandle, bool ownsHandle = true) : base(preexistingHandle, ownsHandle) { } + + /// Initializes a new instance of the class. + private SafeFH_SERVICE_PIPE_HANDLE() : base() { } + + /// Performs an implicit conversion from to . + /// The safe handle instance. + /// The result of the conversion. + public static implicit operator FH_SERVICE_PIPE_HANDLE(SafeFH_SERVICE_PIPE_HANDLE h) => h.handle; + + /// + protected override bool InternalReleaseHandle() => FhServiceClosePipe(handle).Succeeded; + } + } +} \ No newline at end of file diff --git a/PInvoke/FhSvcCtl/Vanara.PInvoke.FhSvcCtl.csproj b/PInvoke/FhSvcCtl/Vanara.PInvoke.FhSvcCtl.csproj new file mode 100644 index 00000000..0e500edf --- /dev/null +++ b/PInvoke/FhSvcCtl/Vanara.PInvoke.FhSvcCtl.csproj @@ -0,0 +1,19 @@ + + + + fhsvcctl.dll + + + PInvoke API (methods, structures and constants) imported from Windows FhSvcCtl.dll. + $(AssemblyName) + net20;net35;net40;net45;net5.0-windows;netstandard2.0;netcoreapp2.0;netcoreapp2.1;netcoreapp3.0;netcoreapp3.1 + Vanara.PInvoke.FhSvcCtl + $(AssemblyName) + pinvoke;vanara;net-extensions;interop;FhSvcCtl;file history + + + + + + + \ No newline at end of file diff --git a/UnitTests/PInvoke/FhSvcCtl/FhSvcCtl.csproj b/UnitTests/PInvoke/FhSvcCtl/FhSvcCtl.csproj new file mode 100644 index 00000000..9aa44870 --- /dev/null +++ b/UnitTests/PInvoke/FhSvcCtl/FhSvcCtl.csproj @@ -0,0 +1,8 @@ + + + UnitTest.PInvoke.FhSvcCtl + + + + + \ No newline at end of file diff --git a/UnitTests/PInvoke/FhSvcCtl/FhSvcCtlTests.cs b/UnitTests/PInvoke/FhSvcCtl/FhSvcCtlTests.cs new file mode 100644 index 00000000..82935381 --- /dev/null +++ b/UnitTests/PInvoke/FhSvcCtl/FhSvcCtlTests.cs @@ -0,0 +1,52 @@ +using NUnit.Framework; +using NUnit.Framework.Internal; +using System; +using System.Runtime.InteropServices; +using static Vanara.PInvoke.FhSvcCtl; + +namespace Vanara.PInvoke.Tests +{ + [TestFixture] + public class FhSvcCtlTests + { + [OneTimeSetUp] + public void _Setup() + { + } + + [DllImport(Lib.Kernel32, CharSet = CharSet.Auto, SetLastError = true, BestFitMapping = false, ThrowOnUnmappableChar = true)] + static extern HINSTANCE LoadLibraryEx(string lpFileName, [Optional] IntPtr hFile, uint dwFlags); + + [DllImport(Lib.Kernel32, SetLastError = true, ExactSpelling = true)] + [return: MarshalAs(UnmanagedType.Bool)] + static extern bool FreeLibrary(HINSTANCE hModule); + + [OneTimeTearDown] + public void _TearDown() + { + } + + [Test] + public void TestIntf() + { + var mgr = new IFhConfigMgr(); + mgr.LoadConfiguration(); + } + + [Test] + public void TestFn() + { + HINSTANCE hi; + Assert.That(hi = LoadLibraryEx(@"C:\Windows\System32\fhsvccfg.dll", default, 0x1000), ResultIs.ValidHandle); + FreeLibrary(hi); + + Assert.That(FhServiceOpenPipe(true, out var hPipe), ResultIs.Successful); + Assert.That(FhServiceReloadConfiguration(hPipe), ResultIs.Successful); + Assert.That(FhServiceStartBackup(hPipe, true), ResultIs.Successful); + Assert.That(FhServiceBlockBackup(hPipe), ResultIs.Successful); + Assert.That(FhServiceUnblockBackup(hPipe), ResultIs.Successful); + Assert.That(FhServiceStopBackup(hPipe, false), ResultIs.Successful); + Assert.That(() => hPipe.Dispose(), Throws.Nothing); + } + } +} \ No newline at end of file diff --git a/Vanara.sln b/Vanara.sln index 7636fbe2..a6589ae6 100644 --- a/Vanara.sln +++ b/Vanara.sln @@ -323,6 +323,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Vanara.PInvoke.CimFs", "PIn EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CimFs", "UnitTests\PInvoke\CimFs\CimFs.csproj", "{5DBC32A2-1FF0-41F6-9D6B-CE701F599BE0}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Vanara.PInvoke.FhSvcCtl", "PInvoke\FhSvcCtl\Vanara.PInvoke.FhSvcCtl.csproj", "{B419C1F3-AB66-40B9-9693-817CD061F7EF}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "FhSvcCtl", "UnitTests\PInvoke\FhSvcCtl\FhSvcCtl.csproj", "{089EA815-567E-4430-BEB4-4E18FD0B1473}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -1058,6 +1062,16 @@ Global {5DBC32A2-1FF0-41F6-9D6B-CE701F599BE0}.Debug|Any CPU.Build.0 = Debug|Any CPU {5DBC32A2-1FF0-41F6-9D6B-CE701F599BE0}.DebugNoTests|Any CPU.ActiveCfg = Debug|Any CPU {5DBC32A2-1FF0-41F6-9D6B-CE701F599BE0}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B419C1F3-AB66-40B9-9693-817CD061F7EF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B419C1F3-AB66-40B9-9693-817CD061F7EF}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B419C1F3-AB66-40B9-9693-817CD061F7EF}.DebugNoTests|Any CPU.ActiveCfg = Debug|Any CPU + {B419C1F3-AB66-40B9-9693-817CD061F7EF}.DebugNoTests|Any CPU.Build.0 = Debug|Any CPU + {B419C1F3-AB66-40B9-9693-817CD061F7EF}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B419C1F3-AB66-40B9-9693-817CD061F7EF}.Release|Any CPU.Build.0 = Release|Any CPU + {089EA815-567E-4430-BEB4-4E18FD0B1473}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {089EA815-567E-4430-BEB4-4E18FD0B1473}.Debug|Any CPU.Build.0 = Debug|Any CPU + {089EA815-567E-4430-BEB4-4E18FD0B1473}.DebugNoTests|Any CPU.ActiveCfg = Debug|Any CPU + {089EA815-567E-4430-BEB4-4E18FD0B1473}.Release|Any CPU.ActiveCfg = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -1201,6 +1215,8 @@ Global {AD86DDF6-F5BA-4A4D-85BE-8D2415FCA1CC} = {385CAD2D-0A5E-4F80-927B-D5499D126B90} {5C26B1D5-B826-40D0-8D8C-024250FBB306} = {212ABBD0-B724-4CFA-9D6D-E3891547FA90} {5DBC32A2-1FF0-41F6-9D6B-CE701F599BE0} = {385CAD2D-0A5E-4F80-927B-D5499D126B90} + {B419C1F3-AB66-40B9-9693-817CD061F7EF} = {212ABBD0-B724-4CFA-9D6D-E3891547FA90} + {089EA815-567E-4430-BEB4-4E18FD0B1473} = {385CAD2D-0A5E-4F80-927B-D5499D126B90} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {543FAC75-2AF1-4EF1-9609-B242B63FEED4}