Fonction PrjUpdateFileIfNeeded (projectedfslib.h)

Permet à un fournisseur de mettre à jour un élément qui a été 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 le instance de virtualisation.

[in] destinationFileName

Chaîne Unicode terminée par un caractère Null spécifiant le chemin d’accès, relatif à 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à présent 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 le ou 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 de l’échec d’une mise à jour.

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 répercuté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 PRJ_UPDATE_TYPES dans le paramètre updateFlags. Cela permet de vous protéger contre la perte accidentelle de données, car après un 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 ont été modifiées depuis la création de l’espace réservé, ou les données de fichier qu’elles contiennent 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.

Virtuel : l’élément n’existe pas localement sur le disque. Il est projeté, c’est-à-dire synthétisé, lors des é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 : une partie ou la totalité des 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 des espaces réservés hydratés. Un répertoire qui a été 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 d’afficher ces modifications dans le cache local.

Espace réservé incorrect (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 de ce répertoire.

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 qui ont été créés sur le système de fichiers local (c’est-à-dire qui n’existent pas du tout dans le magasin du fournisseur) 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 du tout 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 des é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 dans les jeux locaux et projetés, l’élément local est prioritaire. S’il n’existe pas de fichier, il n’y a 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 qui s’attend à ce que l’élément existe échoue avec, par exemple, « fichier introuvable ».
• Les créations de fichiers qui s’attendent à réussir uniquement si l’élément n’existe pas réussissent ; ProjFS supprime la pierre tombstone dans le cadre de l’opération.

Pour illustrer les états ci-dessus, considérez la séquence suivante, étant donné qu’un fournisseur ProjFS 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é consulté, il 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 pour C:\root\foo.txt. Le fichier est maintenant un espace réservé hydraté.
• L’application met à jour l’horodatage de la dernière modification. Le fichier est maintenant un espace réservé sale hydraté.
• 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, elle ne voit pas foo.txt. S’il tente d’ouvrir le fichier, l’ouverture échoue avec ERROR_FILE_NOT_FOUND.

Configuration requise