PrjUpdateFileIfNeeded, fonction (projectedfslib.h)

Permet à un fournisseur de mettre à jour un élément mis en cache sur le système de fichiers local.

Syntaxe

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

Paramètres

[in] namespaceVirtualizationContext

Handle opaque pour l’instance de virtualisation.

[in] destinationFileName

Chaîne Unicode terminée par null spécifiant le chemin d’accès, par rapport à la racine de virtualisation, au fichier ou au répertoire à mettre à jour.

[in] placeholderInfo

Pointeur vers une mémoire tampon PRJ_PLACEHOLDER_INFO contenant les métadonnées mises à jour pour le fichier ou le répertoire.

Si placeholderInfo-VersionInfo.ContentID> contient un identificateur de contenu identique à l’identificateur de contenu déjà sur le fichier/répertoire, l’appel réussit et aucune mise à jour n’a lieu. Sinon, si l’appel réussit, placeholderInfo-VersionInfo.ContentID> remplace l’identificateur de contenu existant sur le fichier.

[in] placeholderInfoSize

Taille en octets de la mémoire tampon pointée par placeholderInfo.

[in, optional] updateFlags

Indicateurs pour contrôler les mises à jour.

Si l’élément est un espace réservé sale, un fichier complet ou une pierre tombstone et que le fournisseur ne spécifie pas les indicateurs appropriés, cette routine ne parvient pas à mettre à jour l’espace réservé.

[out, optional] failureReason

Pointeur facultatif pour recevoir un code décrivant la raison pour laquelle une mise à jour a échoué.

Valeur retournée

Si une erreur HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION) est retournée, la mise à jour a échoué en raison de l’état de l’élément et de la valeur de updateFlags. failureReason, s’il est spécifié, décrit la raison de l’échec.

Remarques

Le fournisseur utilise cette routine pour mettre à jour un élément dans le système de fichiers local si les informations de l’élément ont changé dans le magasin de stockage du fournisseur et que les mises à jour doivent être reflétées dans les éléments mis en cache dans le système de fichiers local.

Cette routine ne peut pas être appelée sur un fichier/répertoire virtuel. Si le fichier/répertoire à mettre à jour est dans un état autre que « espace réservé », le fournisseur doit spécifier une combinaison appropriée de valeurs d’PRJ_UPDATE_TYPES dans le paramètre updateFlags. Cela permet de se protéger contre la perte accidentelle de données, car lors du retour réussi de cette routine, l’élément devient un espace réservé avec les métadonnées mises à jour ; toutes les métadonnées qui avaient été modifiées depuis la création de l’espace réservé, ou toutes les données de fichier qu’elle contenait sont ignorées.

Le fournisseur utilise le système de fichiers local comme cache des éléments qu’il gère. Un élément (fichier ou répertoire) peut se trouver dans l’un des six états du système de fichiers local.

Virtual : l’élément n’existe pas localement sur le disque. Il est projeté, c’est-à-dire synthétisé, pendant les énumérations de son répertoire parent. Les éléments virtuels sont fusionnés avec tous les éléments qui peuvent exister sur le disque pour présenter le contenu complet du répertoire parent.

Espace réservé - Pour les fichiers : le contenu du fichier (flux de données principal) n’est pas présent sur le disque. Les métadonnées du fichier (nom, taille, horodatages, attributs, etc.) sont mises en cache sur le disque. Pour les répertoires : Certains ou tous les descendants immédiats du répertoire (les fichiers et répertoires du répertoire) ne sont pas présents sur le disque, c’est-à-dire qu’ils sont toujours virtuels. Les métadonnées du répertoire (nom, horodatages, attributs, etc.) sont mises en cache sur le disque.

Espace réservé hydraté - Pour les fichiers : le contenu et les métadonnées du fichier ont été mis en cache sur le disque. Également appelé « fichier partiel ». Pour les répertoires : les répertoires ne sont jamais hydratés. Un répertoire créé sur le disque en tant qu’espace réservé ne devient jamais un répertoire d’espace réservé hydraté. Cela permet au fournisseur d’ajouter ou de supprimer des éléments du répertoire dans son magasin de stockage et de refléter ces modifications dans le cache local.

Espace réservé sale (hydraté ou non) : les métadonnées de l’élément ont été modifiées localement et ne sont plus un cache de son état dans le magasin du fournisseur. Notez que la création ou la suppression d’un fichier ou d’un répertoire sous un répertoire d’espace réservé entraîne la sale mise en place du répertoire d’espace réservé.

Fichier/répertoire complet : pour les fichiers : le contenu du fichier (flux de données principal) a été modifié. Le fichier n’est plus un cache de son état dans le magasin du fournisseur. Les fichiers créés sur le système de fichiers local (c’est-à-dire qui n’existent pas dans le magasin du fournisseur du tout) sont également considérés comme des fichiers complets. Pour les répertoires : les répertoires créés sur le système de fichiers local (c’est-à-dire qui n’existent pas dans le magasin du fournisseur) sont considérés comme des répertoires complets. Un répertoire créé sur le disque en tant qu’espace réservé ne devient jamais un répertoire complet.

Tombstone : espace réservé masqué spécial qui représente un élément qui a été supprimé du système de fichiers local. Lorsqu’un répertoire est énuméré, ProjFS fusionne l’ensemble d’éléments locaux (espaces réservés, fichiers complets, etc.) avec l’ensemble d’éléments projetés virtuels. Si un élément apparaît à la fois dans les ensembles locaux et projetés, l’élément local est prioritaire. S’il n’existe pas de fichier, il n’existe pas d’état local. Il apparaît donc dans l’énumération. Toutefois, si cet élément avait été supprimé, son affichage dans l’énumération serait inattendu. Le remplacement d’un élément supprimé par une pierre tombstone entraîne les effets suivants :

• Énumérations pour ne pas révéler l’élément
• Le fichier s’ouvre et s’attend à ce que l’élément existe échoue, par exemple « fichier introuvable ».
• Le fichier crée qui s’attend à réussir uniquement si l’élément n’existe pas ; ProjFS supprime la pierre tombale dans le cadre de l’opération.

Pour illustrer les états ci-dessus, tenez compte de la séquence suivante, en fonction d’un fournisseur ProjFS qui a un seul fichier «foo.txt» situé dans la racine de virtualisation C :\root.

• Une application énumère C :\root. Il voit le fichier virtuel «foo.txt». Étant donné que le fichier n’a pas encore été accédé, le fichier n’existe pas sur le disque.
• L’application ouvre un handle pour C:\root\foo.txt. ProjFS indique au fournisseur de créer un espace réservé pour celui-ci.
• L’application lit le contenu du fichier. Le fournisseur fournit le contenu du fichier à ProjFS et il est mis en cache sur C:\root\foo.txt. Le fichier est maintenant un espace réservé hydraté.
• L’application met à jour l’horodatage Last Modified. Le fichier est maintenant un espace réservé hydraté sale.
• L’application ouvre un handle pour l’accès en écriture au fichier. C:\root\foo.txt est maintenant un fichier complet.
• L’application supprime C:\root\foo.txt. ProjFS remplace le fichier par une pierre tombstone. À présent, lorsque l’application énumère C:\root it does not see foo.txt. S’il tente d’ouvrir le fichier, l’ouverture échoue avec ERROR_FILE_NOT_FOUND.

Spécifications