Función PrjUpdateFileIfNeeded (projectedfslib.h)

Permite a un proveedor actualizar un elemento almacenado en caché en el sistema de archivos local.

Sintaxis

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
);

Parámetros

[in] namespaceVirtualizationContext

Identificador opaco para la instancia de virtualización.

[in] destinationFileName

Cadena Unicode terminada en null que especifica la ruta de acceso, relativa a la raíz de virtualización, al archivo o directorio que se va a actualizar.

[in] placeholderInfo

Puntero a un búfer de PRJ_PLACEHOLDER_INFO que contiene los metadatos actualizados para el archivo o directorio.

Si placeholderInfo-VersionInfo.ContentID> contiene un identificador de contenido que es el mismo que el identificador de contenido que ya está en el archivo o directorio, la llamada se realiza correctamente y no se realiza ninguna actualización. De lo contrario, si la llamada se realiza correctamente, placeholderInfo-VersionInfo.ContentID> reemplaza el identificador de contenido existente en el archivo.

[in] placeholderInfoSize

Tamaño en bytes del búfer al que apunta placeholderInfo.

[in, optional] updateFlags

Marcas para controlar las actualizaciones.

Si el elemento es un marcador de posición sucio, un archivo completo o una lápida, y el proveedor no especifica las marcas adecuadas, esta rutina no podrá actualizar el marcador de posición.

[out, optional] failureReason

Puntero opcional para recibir un código que describa el motivo por el que se produjo un error en la actualización.

Valor devuelto

Si se devuelve un error de HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION), se produjo un error en la actualización debido al estado del elemento y al valor de updateFlags. failureReason, si se especifica, describirá el motivo del error.

Comentarios

El proveedor usa esta rutina para actualizar un elemento en el sistema de archivos local si la información del elemento ha cambiado en el almacén de respaldo del proveedor y las actualizaciones deben reflejarse en los elementos almacenados en caché en el sistema de archivos local.

No se puede llamar a esta rutina en un archivo o directorio virtual. Si el archivo o directorio que se va a actualizar está en cualquier estado distinto de "marcador de posición", el proveedor debe especificar una combinación adecuada de PRJ_UPDATE_TYPES valores en el parámetro updateFlags. Esto ayuda a protegerse frente a la pérdida accidental de datos, ya que tras la devolución correcta de esta rutina, el elemento se convierte en un marcador de posición con los metadatos actualizados; los metadatos que se han cambiado desde que se creó el marcador de posición o los datos de archivo que contenía se descartan.

El proveedor usa el sistema de archivos local como una memoria caché de los elementos que administra. Un elemento (archivo o directorio) puede estar en uno de los seis estados del sistema de archivos local.

Virtual: el elemento no existe localmente en el disco. Se proyecta, es decir, sintetizado, durante las enumeraciones de su directorio primario. Los elementos virtuales se combinan con los elementos que pueden existir en el disco para presentar todo el contenido del directorio primario.

Marcador de posición: para los archivos: el contenido del archivo (flujo de datos principal) no está presente en el disco. Los metadatos del archivo (nombre, tamaño, marcas de tiempo, atributos, etc.) se almacenan en caché en el disco. Para directorios: algunos o todos los descendientes inmediatos del directorio (los archivos y directorios del directorio) no están presentes en el disco, es decir, siguen siendo virtuales. Los metadatos del directorio (nombre, marcas de tiempo, atributos, etc.) se almacenan en caché en el disco.

Marcador de posición hidratado: para los archivos: el contenido y los metadatos del archivo se han almacenado en caché en el disco. También se conoce como un "archivo parcial". Para directorios: los directorios nunca se hidratan los marcadores de posición. Un directorio que se creó en el disco como marcador de posición nunca se convierte en un directorio de marcador de posición hidratado. Esto permite al proveedor agregar o quitar elementos del directorio en su almacén de respaldo y hacer que esos cambios se reflejen en la memoria caché local.

Marcador de posición sucio (hidratado o no): los metadatos del elemento se han modificado localmente y ya no es una memoria caché de su estado en el almacén del proveedor. Tenga en cuenta que la creación o eliminación de un archivo o directorio en un directorio de marcador de posición hace que el directorio de marcador de posición se ensucie.

Archivo o directorio completo: para los archivos: se ha modificado el contenido del archivo (flujo de datos principal). El archivo ya no es una memoria caché de su estado en el almacén del proveedor. Los archivos creados en el sistema de archivos local (es decir, que no existen en el almacén del proveedor) también se consideran archivos completos. Para directorios: los directorios creados en el sistema de archivos local (es decir, que no existen en el almacén del proveedor) se consideran directorios completos. Un directorio que se creó en el disco como marcador de posición nunca se convierte en un directorio completo.

Tombstone: marcador de posición oculto especial que representa un elemento que se ha eliminado del sistema de archivos local. Cuando se enumera un directorio ProjFS combina el conjunto de elementos locales (marcadores de posición, archivos completos, etc.) con el conjunto de elementos proyectados virtuales. Si un elemento aparece en los conjuntos locales y proyectados, el elemento local tiene prioridad. Si un archivo no existe, no hay ningún estado local, por lo que aparecerá en la enumeración. Sin embargo, si ese elemento se hubiera eliminado, tenerlo en la enumeración sería inesperado. Reemplazar un elemento eliminado por una piedra de tumba da como resultado los siguientes efectos:

• Enumeraciones para no mostrar el elemento
• Se abre el archivo que espera que el elemento exista produce un error, por ejemplo, "archivo no encontrado".
• El archivo crea que espera que se realice correctamente solo si el elemento no existe correctamente; ProjFS quita la lápida como parte de la operación.

Para ilustrar los estados anteriores, tenga en cuenta la siguiente secuencia, dado un proveedor de ProjFS que tiene un único archivo "foo.txt" ubicado en la raíz de virtualización C:\root.

• Una aplicación enumera C:\root. Ve el archivo virtual "foo.txt". Puesto que aún no se ha accedido al archivo, el archivo no existe en el disco.
• La aplicación abre un identificador para C:\root\foo.txt. ProjFS indica al proveedor que cree un marcador de posición para él.
• La aplicación lee el contenido del archivo. El proveedor proporciona el contenido del archivo a ProjFS y se almacena en caché en C:\root\foo.txt. El archivo ahora es un marcador de posición hidratado.
• La aplicación actualiza la marca de tiempo Última modificación. El archivo ahora es un marcador de posición hidratado sucio.
• La aplicación abre un identificador para el acceso de escritura al archivo. C:\root\foo.txt ahora es un archivo completo.
• La aplicación elimina C:\root\foo.txt. ProjFS reemplaza el archivo por una lápida. Ahora, cuando la aplicación enumera C:\root, no ve foo.txt. Si intenta abrir el archivo, se produce un error en la apertura con ERROR_FILE_NOT_FOUND.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10, versión 1809 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	projectedfslib.h