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

Создает один или несколько новых файлов заполнителей или каталогов в дереве корневого каталога синхронизации.

Синтаксис

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

Параметры

[in] BaseDirectoryPath

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

• Этот путь должен содержаться в зарегистрированном корневом дереве синхронизации. Это может быть сам корневой каталог синхронизации или любой другой каталог-потомок. В противном случае вызов завершится сбоем с STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT.
• Корневой каталог синхронизации должен быть зарегистрирован с помощью допустимой политики гидратации, которая не CF_HYDRATION_POLICY_ALWAYS_FULL. В противном случае вызов завершится сбоем с STATUS_CLOUD_FILE_NOT_SUPPORTED.
• Вызывающий объект должен иметь WRITE_DATA или WRITE_DAC доступ к базовому каталогу, в котором будет создан заполнитель. В противном случае операция завершится сбоем с STATUS_CLOUD_FILE_ACCESS_DENIED.

[in, out] PlaceholderArray

При успешном создании PlaceholderArray содержит окончательное значение USN и STATUS_OK сообщение. При возврате этот массив содержит значение HRESULT , описывающее, был ли создан заполнитель. PlaceholderArray указывает на массив заполнителей, которые необходимо создать, относительно BaseDirectoryPath. Каждая запись в массиве содержит следующие поля:

• RelativeFileName — это имя создаваемого дочернего заполнителя, как файла, так и каталога.
• FsMetadata содержит метаданные файловой системы о создаваемом заполнителье, включая все метки времени, атрибуты файла и размер файла (необязательно для каталогов).
• FileIdentity и FileIdentityLength описывают буфер пользовательского режима, содержащий непрозрачные сведения о файлах, предоставленные поставщиком синхронизации. Размер большого двоичного объекта FileIdentity не должен превышать CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (определенный до 4 КБ). FileIdentity передается обратно поставщику синхронизации во всех обратных вызовах. Это обязательное поле для файлов.

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

• CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION — этот флаг применим только к дочернему каталогу-заполнителю. При наличии флага считается, что в созданном дочернем каталоге-заполнитель есть все его дочерние элементы локально, поэтому доступ к нему в будущем не активирует FETCH_PLACEHOLDERS обратного вызова. Если флаг отсутствует, вновь созданный каталог-заполнитель считается частичным, и в будущем доступ активируется FETCH_PLACEHOLDERS.
• CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC — этот флаг применим как к файлам-заполнителям, так и к каталогам. При наличии этого флага созданный заполнитель будет помечен как синхронизированный как часть операции TRANSFER_PLACEHOLDERS .
• CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL — этот флаг применяется только к файлу заполнителя. Его можно задать для каталога-заполнителя, но это не оказывает никакого влияния. При наличии этого флага созданный заполнитель будет помечен как всегда полный. После очистки любая попытка обезвожить такой заполнитель файла завершится сбоем с кодом ошибки ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.

[in] PlaceholderCount

Количество заполнителей в PlaceholderArray.

[in] CreateFlags

Флаги для настройки создания заполнителя. Для createFlags можно задать следующие значения:

• CF_CREATE_FLAG_NONE — это режим по умолчанию, в котором API обрабатывает все записи в массиве даже при обнаружении ошибок.
• CF_CREATE_FLAG_STOP_ON_ERROR приводит к немедленному возврату API в случае сбоя создания заполнителя. В этом случае API возвращает код сбоя.

[out] EntriesProcessed

Количество обработанных записей, включая записи, завершившиеся сбоем. Если CF_CREATE_FLAG_STOP_ON_ERROR не был указан в CreateFlags, API возвращает первый возникший код сбоя, но продолжает обработку как можно больше записей; Затем вызывающий объект должен проверить массив, чтобы узнать, какие заполнители не удалось создать.

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

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

Комментарии

Создание заполнителя с помощью этой функции является предпочтительным по сравнению с созданием нового файла с помощью CreateFile и последующего преобразования его в заполнитель с помощью CfConvertToPlaceholder; как для эффективности, так и потому, что это исключает временное окно, в котором файл не является заполнителем. Функция также может создавать несколько файлов или каталогов в пакете, что также может быть более эффективным.

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

Требования

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

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

CreateFile

CfConvertToPlaceholder