Функция CfRegisterSyncRoot (cfapi.h)

Выполняет однократную корневую регистрацию синхронизации, позволяя поставщику синхронизации запрашивать всю структуру дерева каталогов, корневую в SyncRootPath, как собственную для управления.

Синтаксис

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

Параметры

[in] SyncRootPath

Путь к корню синхронизации для регистрации.

[in] Registration

Содержит сведения о поставщике синхронизации и корневом каталоге синхронизации для регистрации.

ProviderName и ProviderVersion — это строки для конечных пользователей длиной не более 255 символов.

Как SyncRootIdentity , так и FileIdentity являются необязательными, и если они не указаны, их длина буфера также должна иметь значение 0 . Поставщик синхронизации может постоянно связывать произвольные данные с корнем синхронизации.

Платформа будет предоставлять SyncRootIdentity обратно поставщику синхронизации во всех обратных вызовах к поставщику синхронизации. Большой двоичный объект FileIdentity в корневом каталоге синхронизации будет предоставляться только в том случае, если субъектом обратного вызова является сам корень синхронизации.

Эта возможность предоставляется исключительно для удобства поставщика синхронизации, и оба больших двоичных объекта не имеют особого значения за пределами поставщика синхронизации.

Максимально допустимая длина Параметра FileIdentity составляет 4 КБ, а максимально допустимая длина Параметра SyncRootIdentity — 64 КБ. Api завершается сбоем с ERROR_INVALID_PARAMETER при превышении максимальной длины.

ProviderId — это GUID, предназначенный для идентификации конкретного поставщика синхронизации. Этот параметр необязателен. Если этот параметр не указан, платформа создает GUID с помощью хэша MD5 строки ProviderName . Сведения используются для телеметрии только таким образом, что платформа может лучше сопоставлять действия одного и того же поставщика синхронизации более эффективно и более точно, даже если поставщик синхронизации регистрирует корни синхронизации с разными строками ProviderName . Рекомендуется, чтобы поставщик синхронизации всегда предоставлял один и тот же идентификатор GUID для всех версий своих продуктов синхронизации. Однако поставщики синхронизации могут выбирать разные строки ProviderName для оптимального взаимодействия с пользователем.

[in] Policies

Политики корневого каталога синхронизации для регистрации.

[in] RegisterFlags

Флаги для регистрации предыдущих и новых корней синхронизации.

Flag	Описание
CF_REGISTER_FLAG_UPDATE	Поставщик синхронизации может передать CF_REGISTER_FLAG_UPDATE для повторной регистрации ранее зарегистрированных корневых удостоверений и политик синхронизации.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	Поведение заполнения каталогов или папок по запросу глобально контролируется политикой заполнения. Этот флаг позволяет поставщику синхронизации отказаться от поведения заполнения по запросу только для самого корня синхронизации, сохраняя при этом заполнение по запросу для всех остальных каталогов в корневом каталоге синхронизации. Это полезно, если поставщик синхронизации хочет предварительно заполнить непосредственные дочерние файлы или каталоги корневого каталога синхронизации.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Этот флаг позволяет поставщику синхронизации помечать корень синхронизации для одновременной регистрации во время регистрации. Альтернативой является вызов CfSetInSyncState в корневом каталоге синхронизации позже.

Возвращаемое значение

Если эта функция выполняется успешно, она возвращает .S_OK В противном случае возвращается код ошибки HRESULT .

Комментарии

Это можно использовать во время установки поставщика синхронизации, при первой настройке для отдельного пользователя или при настройке другого корневого каталога синхронизации (если этот сценарий поддерживается).

Примечание

Не допускается перекрытие двух корневых деревьев синхронизации. Так как жесткие ссылки каталога запрещены файловой системой, единственным способом перекрытия двух корней синхронизации является наличие прямой связи между предками и потомками. Платформа отвечает за постоянное запоминание всех корней синхронизации, зарегистрированных на заданном томе, и за неудачу любых попыток создания перекрывающихся корней синхронизации.

Поставщик синхронизации должен иметь WRITE_DATA или WRITE_DAC доступ к корню синхронизации для регистрации, иначе регистрация завершится сбоем с ERROR_CLOUD_FILE_ACCESS_DENIED.

Поставщик синхронизации должен предоставить запись регистрации, содержащую различные удостоверения самого поставщика синхронизации и корневого каталога синхронизации, который необходимо регистрировать, набор политик, которые платформа использует для настройки своего поведения на основе корня синхронизации, и набор флагов регистрации, которые позволяют более точно управлять операцией регистрации поставщиком синхронизации.

Если явно не указано как необязательные, все поля являются обязательными, и их отсутствие приведет к сбою вызова API с ошибкой недопустимого параметра.

Все структуры, в которых ожидаются будущие расширения, начинаются с поля StructSize . Вызывающий объект отвечает за точный учет размера структуры.

В настоящее время платформа поддерживает пять типов политик:

Политика гидратации

Политика гидратации позволяет поставщику синхронизации управлять тем, как файлы заполнителей должны быть восстановлены платформой. Он состоит из основной политики и набора модификаторов политики.

Основная политика гидратации имеет четыре разных значения:

Политика	Описание
ALWAYS_FULL	Платформа завершится сбоем (с ERROR_CLOUD_FILE_INVALID_REQUEST) любой операции заполнителя, которая может привести к не полностью гидратированному заполнителю, который включает CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder с параметром dehydrate и CfConvertToPlaceholder с параметром dehydrate.
ПОЛНОЕ	Платформа позволит обезвоживать заполнитель. Когда платформа обнаруживает доступ к обезвоженным заполнителям, она гарантирует, что полное содержимое заполнителя будет доступно локально перед выполнением запроса ввода-вывода пользователя, даже если запрос запрашивает только 1 байт.
ПРОГРЕССИВНЫЙ	Платформа позволит обезвоживать заполнитель. Когда платформа обнаруживает доступ к обезвоженным заполнителям, она завершит запрос ввода-вывода пользователя, как только определит, что от поставщика синхронизации получено достаточное количество данных. Однако платформа обещает продолжать запрашивать оставшееся содержимое заполнителя у поставщика синхронизации в фоновом режиме, пока полное содержимое заполнителя не будет доступно локально или пока последний пользовательский дескриптор заполнителя не будет закрыт. Примечание: Поставщики синхронизации, которые соглашаются на использование PROGRESSIVE , могут не предполагать, что обратные вызовы гидратации поступают последовательно из смещения 0. Иными словами, поставщики синхронизации с политикой PROGRESSIVE должны обрабатывать случайные поиски в заполнитель.
PARTIAL	Эта политика очень похожа на PROGRESSIVE, с единственной разницей является отсутствие непрерывной гидратации в фоновом режиме.

В настоящее время поддерживаются три модификатора политики. Как правило, модификаторы можно смешивать и сопоставлять с любыми основными политиками и другими модификаторами политики, если сочетание не является самоконфлификатором.

Модификатор	Описание
VALIDATION_REQUIRED	Этот модификатор политики предоставляет поставщику синхронизации две гарантии. Во-первых, это гарантирует, что данные, возвращаемые поставщиком синхронизации, всегда сохраняются на диске, прежде чем они будут возвращены в пользовательское приложение. Во-вторых, это позволяет поставщику синхронизации получить те же данные, которые он вернул ранее на платформу, и проверить их целостность. Только после успешного подтверждения целостности поставщиком синхронизации платформа выполнит запрос пользовательского ввода-вывода. Этот модификатор помогает поддерживать сквозную целостность данных за счет дополнительных операций ввода-вывода дисков.
STREAMING_ALLOWED	Этот модификатор политики предоставляет платформе разрешение не хранить данные, возвращаемые поставщиком синхронизации, на локальных дисках. Этот модификатор политики является взаимоисключающим с VALIDATION_REQUIRED. Api завершается сбоем с ERROR_INVALID_PARAMETER , если указаны оба флага.
AUTO_DEHYDRATION_ALLOWED	Этот модификатор политики предоставляет платформе разрешение на обезвоживать заполнители облачных файлов в синхронизации без помощи поставщиков синхронизации. Без этого флага платформа не может вызывать CfDehydratePlaceholder напрямую. Вместо этого единственным поддерживаемым способом обезвоживать заполнитель облачного файла является очистка закрепленного атрибута файла и установка открепленного атрибута файла, после чего фактическое обезущение будет выполняться асинхронно подсистемой синхронизации после получения уведомления об изменении каталога для этих двух атрибутов. Если этот флаг указан, платформе будет разрешено вызывать CfDehydratePlaceholder непосредственно в любом синхронизированном облачном заполнителе файла. Рекомендуется, чтобы поставщики синхронизации поддерживали автоматическое обезвоживание.

Политика в области населения

Политика заполнения позволяет поставщику синхронизации управлять созданием пространства имен заполнителей (как каталогов, так и файлов) платформой. В настоящее время существует три основные политики без определения модификаторов:

Политика	Описание
ALWAYS_FULL	Платформа предполагает, что полное пространство имен всегда доступно локально. Он никогда не перенаправит запрос на перечисление каталога поставщику синхронизации.
ПОЛНОЕ	Когда платформа обнаруживает доступ в не полностью заполненном каталоге, она запрашивает у поставщика синхронизации возврат всех записей в каталоге перед выполнением запроса пользователя.
PARTIAL	Когда платформа обнаруживает доступ к не полностью заполненным каталогам, она запрашивает у поставщика синхронизации только записи, необходимые пользовательскому приложению.

Политика отслеживания InSync

Политика InSync позволяет поставщику синхронизации управлять тем, когда платформа должна очищать состояние синхронизации для заполнителя. В дополнение к постоянной очистке синхронизированного изменения данных платформа в настоящее время может очистить синхронизированные изменения любых сочетаний трех атрибутов файла (ReadOnly, System и Hidden) и двух файлов (CreateTime и LastWriteTime). Эти политики можно применять к файлам и каталогам отдельно.

Политика жесткой связи

По умолчанию платформа не позволяет создавать жесткие ссылки для любого заполнителя. Однако поставщики синхронизации, способные обрабатывать жесткие ссылки, могут поручить платформе включить поддержку с помощью политики ALLOWED . С помощью этой политики приложения могут создавать столько жестких ссылок, сколько поддерживает файловая система, при условии, что ссылки находятся в одном корневом каталоге синхронизации или не находятся в корне синхронизации. Платформа принудительно восстанавливает заполнитель при появлении первой корневой ссылки вне синхронизации и отменить изменения заполнитель в обычный файл при удалении последней корневой ссылки в синхронизации. Создание жесткой ссылки, несовместимой с политикой, завершится сбоем при STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. Операции заполнителей, несовместимые с политикой, также завершатся сбоем с STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

Политика управления заполнителями

По умолчанию только поставщик синхронизации может выполнять операции управления заполнителями в корневом каталоге синхронизации. Несинхронизированные процессы поставщика могут выполнять операции управления заполнителями только в том случае, если корень синхронизации неактивен, т. е. если корень синхронизации не подключен ни к одному поставщику синхронизации. Эти политики, если они включены, позволяют несинхронизированным процессам поставщика выполнять соответствующие операции управления заполнителями в активном корневом каталоге синхронизации. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT — это политика по умолчанию, позволяющая выполнять любые операции управления заполнителями только подключенным поставщиком синхронизации. Следующие политики можно указать в любом сочетании:

Политика	Описание
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Если эта политика указана во время регистрации, любой процесс может создать заполнитель в активном корневом каталоге синхронизации, вызвав CfCreatePlaceholders.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Если эта политика указана во время регистрации, любой процесс может преобразовать файл или каталог в активном корневом каталоге синхронизации в заполнитель, вызвав CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Если эта политика указана во время регистрации, любой процесс может обновить заполнитель в активном корневом каталоге синхронизации, вызвав CfUpdatePlaceholder.

Примечание

Эти флаги поддерживаются только в том случае , если параметр PlatformVersion.IntegrationNumber , полученный из CfGetPlatformInfo , имеет значение 0x310 или выше.

Требования

Требование	Значение
Минимальная версия клиента	Windows 10, версия 1709 [только классические приложения]
Минимальная версия сервера	Windows Server 2016 [только классические приложения]
Целевая платформа	Windows
Header	cfapi.h
Библиотека	CldApi.lib
DLL	CldApi.dll

См. также раздел

CfCreatePlaceholders

CfDehydratePlaceholder

CfUpdatePlaceholder

CfConvertToPlaceholder

CfGetPlatformInfo

CfSetInSyncState