CF_SYNC_POLICIES structure (cfapi.h)

Defines the sync policies used by a sync root.

Syntax

typedef struct CF_SYNC_POLICIES {
  ULONG                            StructSize;
  CF_HYDRATION_POLICY              Hydration;
  CF_POPULATION_POLICY             Population;
  CF_INSYNC_POLICY                 InSync;
  CF_HARDLINK_POLICY               HardLink;
  CF_PLACEHOLDER_MANAGEMENT_POLICY PlaceholderManagement;
} CF_SYNC_POLICIES;

Members

StructSize

The size of the CF_SYNC_POLICIES structure.

Hydration

The hydration policy allows a sync provider to control how placeholder files should be hydrated by the platform. It consists of a primary policy and a set of policy modifiers.

The primary policy has four possible values:

Policy	Description
ALWAYS_FULL	When ALWAYS_FULL is selected, the platform will fail, with HRESULT ERROR_CLOUD_FILE_INVALID_REQUEST, any placeholder operation that could result in a not fully hydrated placeholder, which includes CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder with the dehydrate option, and CfConvertPlaceholder with the dehydrate option.
FULL	When FULL is selected, the platform will allow a placeholder to be dehydrated. When the platform detects access to a dehydrated placeholder, it will ensure that the full content of the placeholder is available locally before completing the user IO request, even if the request is only asking for 1 byte.
PROGRESSIVE	When PROGRESSIVE is selected, the platform will allow a placeholder to be dehydrated. When the platform detects access to a dehydrated placeholder, it will complete the user IO request as soon as it determines that sufficient data is received from the sync provider. However, the platform promises to continue requesting the remaining content in the placeholder from the sync provider in the background until either the full content of the placeholder is available locally or the last user handle on the placeholder is closed. Note that sync providers who opt in for PROGRESSIVE may not assume that hydration callbacks arrive sequentially from offset 0. In other words, sync providers with PROGRESSIVE policy are expected to handle random seeks on the placeholder.
PARTIAL	The PARTIAL policy is very similar to PROGRESSIVE. The only difference between the two is the lack of continuous hydration in the background with the PARTIAL policy.

Three policy modifiers are currently supported: VALIDATION_REQUIRED, STREAMING_ALLOWED, and AUTO_DEHYDRATION_ALLOWED. In general, modifiers can be mixed and matched with any primary policies and other policy modifiers as long as the combination is not self-conflicting.

Policy modifier	Description
VALIDATION_REQUIRED	This policy modifier offers two guarantees to a sync provider. First, it guarantees that the data returned by the sync provider is always persisted to the disk prior to it being returned to the user application. Second, it allows the sync provider to retrieve the same data it has returned previously to the platform and validate its integrity. Only upon a successful confirmation of the integrity by the sync provider will the platform complete the user IO request. This modifier helps support end-to-end data integrity at the cost of extra disk IOs.
STREAMING_ALLOWED	This policy modifier grants the platform the permission to not store any data returned by a sync provider on local disks. This policy modifier is mutually exclusive with VALIDATION_REQUIRED. The API fails with ERROR_INVALID_PARAMETER when both flags are specified.
AUTO_DEHYDRATION_ALLOWED	This policy modifier grants the platform the permission to dehydrate in-sync cloud file placeholders without the help of sync providers. Without this flag, the platform is not allowed to call CfDehydratePlaceholder directly. Instead, the only supported way to dehydrate a cloud file placeholder is to clear the file’s pinned attribute and set the file’s unpinned attribute. Then the actual dehydration will be performed asynchronously by the sync engine after it receives the directory change notification on the two attributes. When this flag is specified, the platform will be allowed to invoke CfDehydratePlaceholder directly on any in-sync cloud file placeholder. It is recommended for sync providers to support auto dehydration.
ALLOW_FULL_RESTART_HYDRATION	This policy modifier grants the platform permission to fully hydrate a file synchronously when it intercepts an attempt by an AV Filter to scan the file. Sync providers that wish to use RestartHydration to change the fileSize from a FetchData callback must opt-in for the ALLOW_FULL_RESTART_HYDRATION policy to avoid possible deadlocks with anti-virus and anti-malware software trying to scan the file and the provider trying to change fileSize using RestartHydration. Note: This modifier is supported only if the PlatformVersion.IntegrationNumber obtained from CfGetPlatformInfo is 0x500 or higher.

Population

The population policy allows a sync provider to control how placeholder namespace, both directories and files, should be created by the platform. There are currently three primary policies with no modifiers defined:

Policy	Description
ALWAYS_FULL	When ALWAYS_FULL is selected, the platform assumes that the full name space is always available locally. It will never forward any directory enumeration request to the sync provider.
FULL	With the FULL population policy, when the platform detects access on a not fully populated directory, it will request the sync provider return all entries under the directory before completing the user request.
PARTIAL	With the PARTIAL population policy, when the platform detects access on a not fully populated directory, it will request only the entries required by the user application from the sync provider.

InSync

The InSync policy allows a sync provider to control when the platform should clear the in-sync state on a placeholder. In addition to always clearing in-sync on any data modification, the platform can currently clear in-sync on changes of any combinations of three file attributes (ReadOnly, System, and Hidden) and two file times (CreateTime and LastWriteTime). These policies can be applied to files and directories separately.

HardLink

By default, the platform does not allow hard links to be created on any placeholder. However, sync providers that are capable of handling hard links can instruct the platform to enable the support via the ALLOWED policy. With this policy, applications can create as many hard links as the file system supports so long as the links are under either the same sync root or no sync root. The platform will force a placeholder to be hydrated when the first out-of-sync-root link is introduced and revert a placeholder to normal file when its last in-sync-root link is removed. Hardlink creation that is not compatible with the policy will fail with HRESULT ERROR_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. Placeholder operations that are not compatible with the policy will also fail with ERROR_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

PlaceholderManagement

By default, only a sync provider can perform placeholder management operations in a sync root. Non sync provider processes can perform placeholder management operations only if the sync root is inactive (i.e., when no sync providers are connected to the sync root.) These policies, when enabled, allow non sync provider processes to perform respective placeholder management operations in an active sync root. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT is the default policy, allowing only a connected sync provider to perform any placeholder management operations. The three policies below can be specified in any combination:

Policy	Description
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	When this policy is specified during registration, any process can create a placeholder within an active sync root by calling CfCreatePlaceholders.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	When this policy is specified during registration, any process can convert a file or a directory within an active sync root to a placeholder by calling CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	When this policy is specified during registration, any process can update a placeholder within an active sync root via the API CfUpdatePlaceholder.

Note

These flags are supported only if the PlatformVersion.IntegrationNumber obtained from CfGetPlatformInfo is 0x310 or higher.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1709 [desktop apps only]
Minimum supported server	Windows Server 2016 [desktop apps only]
Header	cfapi.h

See also

CfCreatePlaceholders

CfConvertToPlaceholder

CfGetPlatformInfo