Функция PrjUpdateFileIfNeeded (projectedfslib.h)

Позволяет поставщику обновлять элемент, кэшированный в локальной файловой системе.

Синтаксис

HRESULT PrjUpdateFileIfNeeded(
  [in]            PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
  [in]            PCWSTR                               destinationFileName,
  [in]            const PRJ_PLACEHOLDER_INFO           *placeholderInfo,
  [in]            UINT32                               placeholderInfoSize,
  [in, optional]  PRJ_UPDATE_TYPES                     updateFlags,
  [out, optional] PRJ_UPDATE_FAILURE_CAUSES            *failureReason
);

Параметры

[in] namespaceVirtualizationContext

Непрозрачный дескриптор для экземпляра виртуализации.

[in] destinationFileName

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

[in] placeholderInfo

Указатель на буфер PRJ_PLACEHOLDER_INFO , содержащий обновленные метаданные для файла или каталога.

Если заполнительInfo-VersionInfo.ContentID> содержит идентификатор содержимого, который совпадает с идентификатором содержимого, уже имеющимся в файле или каталоге, вызов будет выполнен успешно и обновление не выполняется. В противном случае, если вызов выполняется успешно, заполнительInfo-VersionInfo.ContentID> заменяет существующий идентификатор содержимого в файле.

[in] placeholderInfoSize

Размер буфера в байтах, на который указывает заполнительInfo.

[in, optional] updateFlags

Флаги для управления обновлениями.

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

[out, optional] failureReason

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

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

Если возвращается ошибка HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION), обновление завершилось сбоем из-за состояния элемента и значения updateFlags. failureReason, если он указан, описывает причину сбоя.

Комментарии

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

Эту подпрограмму нельзя вызвать для виртуального файла или каталога. Если обновляемый файл или каталог находится в состоянии, отличном от "заполнитель", поставщик должен указать соответствующее сочетание PRJ_UPDATE_TYPES значений в параметре updateFlags. Это помогает защититься от случайной потери данных, так как при успешном возвращении из этой процедуры элемент становится заполнителем с обновленными метаданными; все метаданные, которые были изменены с момента создания заполнителя, или все содержащиеся в нем данные файла удаляются.

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

Virtual — элемент не существует локально на диске. Он проецируется, т. е. синтезируется, во время перечисления родительского каталога. Виртуальные элементы объединяются со всеми элементами, которые могут существовать на диске для представления полного содержимого родительского каталога.

Заполнитель — для файлов: содержимое файла (основной поток данных) отсутствует на диске. Метаданные файла (имя, размер, метки времени, атрибуты и т. д.) кэшируются на диске. Для каталогов. Некоторые или все непосредственные потомки каталога (файлы и каталоги в каталоге) отсутствуют на диске, т. е. они по-прежнему являются виртуальными. Метаданные каталога (имя, метки времени, атрибуты и т. д.) кэшируются на диске.

Гидратированный заполнитель — для файлов: содержимое и метаданные файла были кэшированы на диск. Также называется частичным файлом. Для каталогов: каталоги никогда не являются гидратированными заполнителями. Каталог, созданный на диске в качестве заполнителя, никогда не становится гидратированным каталогом-заполнителем. Это позволяет поставщику добавлять или удалять элементы из каталога в его резервном хранилище и отражать эти изменения в локальном кэше.

Грязный заполнитель (гидратированный или нет) — метаданные элемента были локально изменены и больше не являются кэшем его состояния в хранилище поставщика. Обратите внимание, что при создании или удалении файла или каталога в каталоге-заполнителе этот каталог становится грязное.

Полный файл/каталог — для файлов: содержимое файла (основной поток данных) было изменено. Файл больше не является кэшем своего состояния в хранилище поставщика. Файлы, созданные в локальной файловой системе (т. е. не существующие в хранилище поставщика), также считаются полными файлами. Для каталогов: каталоги, созданные в локальной файловой системе (т. е. не существующие в хранилище поставщика), считаются полными каталогами. Каталог, созданный на диске в качестве заполнителя, никогда не становится полным каталогом.

Tombstone — специальный скрытый заполнитель, представляющий элемент, удаленный из локальной файловой системы. При перечислении каталога ProjFS объединяет набор локальных элементов (заполнителей, полных файлов и т. д.) с набором виртуальных проецируемых элементов. Если элемент отображается как в локальном, так и в проецируемых наборах, приоритет имеет локальный элемент. Если файл не существует, локальное состояние отсутствует, поэтому он будет отображаться в перечислении . Однако если этот элемент был удален, его появление в перечислении было бы неожиданным. Замена удаленного элемента на надгробие приводит к следующим последствиям:

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

Чтобы проиллюстрировать приведенные выше состояния, рассмотрим следующую последовательность, учитывая поставщик ProjFS с одним файлом "foo.txt", расположенным в корневом каталоге виртуализации C:\root.

• Приложение перечисляет C:\root. Он увидит виртуальный файл "foo.txt". Так как файл еще не был предоставлен доступ, файл не существует на диске.
• Приложение открывает дескриптор для C:\root\foo.txt. ProjFS сообщает поставщику, что нужно создать для него заполнитель.
• Приложение считывает содержимое файла. Поставщик предоставляет содержимое файла в ProjFS и кэшируется для C:\root\foo.txt. Файл теперь является гидратированным заполнителем.
• Приложение обновляет метку времени последнего изменения. Файл теперь является грязное гидратированным заполнителем.
• Приложение открывает дескриптор для доступа к файлу на запись. C:\root\foo.txt теперь является полным файлом.
• Приложение удаляет C:\root\foo.txt. ProjFS заменяет файл на надгробие. Теперь, когда приложение перечисляет C:\root, оно не видит foo.txt. Если он пытается открыть файл, открытие завершается сбоем с ERROR_FILE_NOT_FOUND.

Требования

Требование	Значение
Минимальная версия клиента	Windows 10, версия 1809 [только классические приложения]
Минимальная версия сервера	Windows Server [только классические приложения]
Целевая платформа	Windows
Header	projectedfslib.h