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

Этот API изменяет характеристики существующего заполнителя. Наиболее вероятно, что этот API используется, когда файл был изменен в облаке, и поставщик синхронизации хочет включить результаты этого изменения в заполнитель. Для поддержки этого сценария вызывающий объект может передать новые метаданные файловой системы (метки времени, размер файла и т. д.) для применения и (или) новый BLOB-объект FileIdentity .

Синтаксис

HRESULT CfUpdatePlaceholder(
  [in]                HANDLE               FileHandle,
  [in, optional]      const CF_FS_METADATA *FsMetadata,
  [in, optional]      LPCVOID              FileIdentity,
  [in]                DWORD                FileIdentityLength,
  [in, optional]      const CF_FILE_RANGE  *DehydrateRangeArray,
  [in]                DWORD                DehydrateRangeCount,
  [in]                CF_UPDATE_FLAGS      UpdateFlags,
  [in, out, optional] USN                  *UpdateUsn,
  [in, out, optional] LPOVERLAPPED         Overlapped
);

Параметры

[in] FileHandle

FileHandle — это дескриптор файла или каталога, метаданные которого необходимо обновить. В случае с файлом вызывающий объект должен получить эксклюзивный дескриптор файла, если он также намерен одновременно обезвоживать файл или может произойти повреждение данных. Чтобы свести к минимуму влияние на пользовательские приложения, настоятельно рекомендуется, чтобы вызывающий объект был монопольным, используя надлежащие блокировки (через CfOpenFileWithOplock), а не дескриптор "ничего общего доступа".

[in, optional] FsMetadata

FsMetadata содержит метаданные файловой системы о обновляемом заполнителье, включая все метки времени, атрибуты файла и размер файла (необязательно для каталогов). Это необязательное поле. Если значение не указано, все эти поля остаются без изменений после вызова.

  • Значение 0 в поле метки времени (CreationTime, LastAccessTime, LastWriteTime и ChangeTime) означает, что текущая метка времени в файле не изменяется.
  • Значение 0 в FileAttributes означает отсутствие изменений в текущих атрибутах файла в файле.
  • В FileSize нет специального значения; Значение 0 в fileSize усекает размер файла до 0.

[in, optional] FileIdentity

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

[in] FileIdentityLength

Длина FileIdentity в байтах.

[in, optional] DehydrateRangeArray

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

Самый простой способ использования этого параметра — передать один диапазон, сообщая платформе, что весь диапазон байтов данных теперь недопустим. Более сложное использование этого параметра заключается в предоставлении ряда дискретных диапазонов, которые будут считаться недопустимыми. Это означает, что поставщик синхронизации может различать изменения на уровне вложенного файла. Все смещения и длины должны быть PAGE_SIZE выровнены. Платформа гарантирует, что все указанные диапазоны будут обезвожены при обновлении. При сбое обезвоживания каких-либо диапазонов API приведет к сбою, а не к разрыву содержимого файла.

Примечание

Передача одного диапазона со смещением 0 и длиной CF_EOF сделает недействительным весь файл. Это будет таким же эффектом, как и передача флага CF_UPDATE_FLAG_DEHYDRATE . Кроме того, передача CF_UPDATE_FLAG_DEHYDRATE приводит к автоматическому сбросу DehydrateRangeArray

[in] DehydrateRangeCount

Количество рядов дискретных разделов DehydrateRangeArray данных заполнителей.

[in] UpdateFlags

Обновите флаги для заполнителей. UpdateFlags можно задать следующие значения:

Flag Описание
CF_UPDATE_FLAG_VERIFY_IN_SYNC Обновление завершится ошибкой, если атрибут IN_SYNC в настоящее время не задан для заполнителя. Это необходимо для предотвращения гонки между синхронизацией изменений из облака с локальным заполнителем и локальным изменением потока данных заполнителя.
CF_UPDATE_FLAG_MARK_IN_SYNC Платформа помечает заполнитель как синхронизированный после успешной операции обновления заполнителя.
CF_UPDATE_FLAG_DEHYDRATE Применимо только для файлов. Если этот параметр указан, платформа обезвоживает файл после успешного обновления заполнителя. При указании этого флага вызывающий объект должен получить эксклюзивный дескриптор, иначе могут возникнуть повреждения данных. Обратите внимание, что платформа не проверяет эксклюзивность дескриптора.
CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION Применимо только для каталогов. При указании он помечает обновленный каталог заполнителя частично, чтобы любой будущий доступ к нему приведет к FETCH_PLACEHOLDERS обратному вызову, отправленном поставщику синхронизации.
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION Применимо только для каталогов. При указании он помечает обновленный каталог заполнителей полностью, чтобы любой будущий доступ к нему обрабатывался платформой без обратных вызовов к поставщику синхронизации.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY FileIdentity и FileIdentityLength игнорируются, и платформа удалит существующий blob-объект идентификатора файла в заполнитель после успешного вызова обновления.
CF_UPDATE_FLAG_CLEAR_IN_SYNC Платформа помечает заполнитель как не синхронизированный после успешной операции обновления заполнителя.
CF_UPDATE_FLAG_REMOVE_PROPERTY Платформа удаляет все существующие экстринсовые свойства заполнителя.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA Платформа передает CF_FS_METADATA в файловую систему без фильтрации; В противном случае платформа пропускает установку полей со значением 0.
CF_UPDATE_FLAG_ALWAYS_FULL Действует только для файлов заполнителей. При указании обновляемого заполнителя всегда помечается как полный. После очистки любая попытка обезвожить такой файл заполнителя завершится сбоем с кодом ошибки ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_UPDATE_FLAG_ALLOW_PARTIAL Действует только для файлов заполнителей. При указании всегда полное состояние в файле заполнителя, если оно присутствует, очищается, что позволяет снова обезвоживать его. Недопустимо указывать этот флаг вместе с CF_UPDATE_FLAG_ALWAYS_FULL и кодом ошибки , ERROR_CLOUD_FILE_INVALID_REQUEST будет возвращен в результате.

[in, out, optional] UpdateUsn

При входе UpdateUsn указывает платформе выполнить обновление только в том случае, если файл по-прежнему имеет то же значение USN, что и переданный. Эта цель аналогична CF_UPDATE_FLAG_VERIFY_IN_SYNC но также охватывает изменения локальных метаданных. Передача указателя на значение USN для входных 0 данных аналогична передаче указателя NULL .

При возврате UpdateUsn получает окончательное значение USN после выполнения действий обновления.

[in, out, optional] Overlapped

Если этот параметр указан и в сочетании с асинхронным FileHandle, overlapped позволяет платформе выполнять асинхронный вызов CfUpdatePlaceholder . Дополнительные сведения см. в разделе Примечания .

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

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

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

Комментарии

Чтобы обновить заполнитель, выполните приведенные далее действия.

  • Обновляемый заполнитель должен содержаться в зарегистрированном корневом дереве синхронизации; Это может быть сам корневой каталог синхронизации или любой другой каталог потомков; В противном случае вызов завершится ошибкой HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
  • Если запрашивается обезвоживание, корневой каталог синхронизации должен быть зарегистрирован с помощью допустимой политики гидратации, которая не CF_HYDRATION_POLICY_ALWAYS_FULL; В противном случае вызов завершится ошибкой HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
  • Если запрашивается обезвоживание, заполнитель не должен быть закреплен локально, иначе вызов завершится ошибкой HRESULT(ERROR_CLOUD_FILE_PINNED).
  • Если запрашивается обезвоживание, заполнитель должен быть синхронизирован, иначе вызов завершится ошибкой HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
  • Вызывающий объект должен иметь WRITE_DATA или WRITE_DAC доступ к заполнителю для обновления. В противном случае операция завершится ошибкой HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

Если API возвращает HRESULT_FROM_WIN32 (ERROR_IO_PENDING) при использовании overlapped асинхронно, вызывающий объект может ждать с помощью GetOverlappedResult.

Требования

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

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

CfOpenFileWithOplock

CF_UPDATE_FLAGS

  • Last updated on