CfUpdatePlaceholder, fonction (cfapi.h)

Article
02/26/2024

Cette API modifie les caractéristiques d’un espace réservé existant. L’utilisation la plus probable de cette API est quand un fichier a été modifié dans le cloud et que le fournisseur de synchronisation souhaite incorporer les effets de cette modification dans un espace réservé. Pour prendre en charge ce scénario, l’appelant peut transmettre de nouvelles métadonnées de système de fichiers (horodatages, taille de fichier, etc.) à appliquer, et/ou un nouvel objet blob FileIdentity .

Syntaxe

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

Paramètres

[in] FileHandle

FileHandle est un handle du fichier ou du répertoire dont les métadonnées doivent être mises à jour. Dans le cas d’un fichier, l’appelant doit acquérir un handle exclusif pour le fichier s’il a également l’intention de déshydrater le fichier en même temps ou une altération des données peut se produire. Pour réduire l’impact sur les applications utilisateur, il est vivement recommandé que l’appelant obtienne l’exclusivité en utilisant des oplocks appropriés (via CfOpenFileWithOplock) au lieu d’utiliser un handle de partage sans partage.

[in, optional] FsMetadata

FsMetadata contient des métadonnées de système de fichiers sur l’espace réservé à mettre à jour, y compris tous les horodatages, attributs de fichier et taille de fichier (facultatif pour les répertoires). Ce champ est facultatif. S’ils ne sont pas fournis, tous ces champs restent intacts après l’appel.

Une 0 valeur dans un champ timestamp (CreationTime, LastAccessTime, LastWriteTime et ChangeTime) signifie qu’aucune modification n’est apportée à l’horodatage actuel sur le fichier.
Une 0 valeur dans FileAttributes signifie qu’aucune modification n’est apportée aux attributs de fichier actuels sur le fichier.
Il n’existe aucune valeur spéciale dans FileSize ; une 0 valeur dans FileSize tronque la taille du fichier en 0.

[in, optional] FileIdentity

FileIdentity est une mémoire tampon en mode utilisateur qui contient les informations de fichier ou de répertoire opaques fournies par l’appelant. La taille de l’objet blob FileIdentity ne doit pas dépasser 4 Ko. FileIdentity est repassé au fournisseur de synchronisation dans tous les rappels. Cela est facultatif si une mise à jour n’est pas nécessaire ou si l’appelant souhaite supprimer l’objet blob FileIdentity de l’espace réservé à mettre à jour.

[in] FileIdentityLength

Longueur, en octets, de FileIdentity.

[in, optional] DehydrateRangeArray

Ce tableau spécifie les plages de l’espace réservé existant qui ne seront plus considérées comme valides après la mise à jour.

L’utilisation la plus simple de ce paramètre consiste à passer une seule plage, en indiquant à la plateforme que la plage d’octets entière des données n’est désormais pas valide. Une utilisation plus complexe de ce paramètre consiste à fournir une série de plages discrètes à considérer comme non valides. Cela implique que le fournisseur de synchronisation peut distinguer les modifications au niveau d’un sous-fichier. Tous les décalages et longueurs doivent être PAGE_SIZE alignés. La plateforme garantit que toutes les plages spécifiées sont déshydratées dans le cadre de la mise à jour. En cas d’échec de la déshydratation de plages, l’API échoue au lieu d’entraîner une arrachée du contenu du fichier.

Notes

Le passage d’une plage unique avec offset 0 et Length CF_EOF invalide l’intégralité du fichier . Cela a le même effet que le passage de l’indicateur CF_UPDATE_FLAG_DEHYDRATE à la place. En outre, la transmission de CF_UPDATE_FLAG_DEHYDRATE entraîne la suppression silencieuse de DehydrateRangeArray

[in] DehydrateRangeCount

Nombre de partitions DehydrateRangeArray discrètes de données d’espace réservé.

[in] UpdateFlags

Mettre à jour les indicateurs pour les espaces réservés. UpdateFlags peut être défini sur les valeurs suivantes :

Indicateur	Description
CF_UPDATE_FLAG_VERIFY_IN_SYNC	La mise à jour échoue si l’attribut IN_SYNC n’est pas actuellement défini sur l’espace réservé. Cela permet d’éviter une concurrence entre la synchronisation des modifications du cloud vers un espace réservé local et la modification locale du flux de données de l’espace réservé.
CF_UPDATE_FLAG_MARK_IN_SYNC	La plateforme marque l’espace réservé comme étant synchronisé lors d’une opération d’espace réservé de mise à jour réussie.
CF_UPDATE_FLAG_DEHYDRATE	Applicable aux fichiers uniquement. Quand elle est spécifiée, la plateforme déshydrate le fichier après la mise à jour de l’espace réservé. L’appelant doit acquérir un handle exclusif lors de la spécification de cet indicateur ou des altérations de données peuvent se produire. Notez que la plateforme ne valide pas l’exclusivité du handle.
CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION	Applicable aux répertoires uniquement. Lorsqu’il est spécifié, il marque le répertoire d’espace réservé mis à jour partiellement rempli de sorte que tout accès ultérieur à celui-ci entraîne un rappel FETCH_PLACEHOLDERS envoyé au fournisseur de synchronisation.
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION	Applicable aux répertoires uniquement. Quand il est spécifié, il marque le répertoire d’espace réservé mis à jour entièrement rempli de sorte que tout accès futur à celui-ci soit géré par la plateforme sans aucun rappel au fournisseur de synchronisation.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY	FileIdentity et FileIdentityLength sont ignorés et la plateforme supprime l’objet blob d’identité de fichier existant sur l’espace réservé lors d’un appel de mise à jour réussi.
CF_UPDATE_FLAG_CLEAR_IN_SYNC	La plateforme marque l’espace réservé comme non synchronisé lors d’une opération d’espace réservé de mise à jour réussie.
CF_UPDATE_FLAG_REMOVE_PROPERTY	La plateforme supprime toutes les propriétés extrinsèques existantes sur l’espace réservé.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA	La plateforme transmet CF_FS_METADATA au système de fichiers sans filtrage ; sinon, la plateforme ignore la définition des champs dont la valeur est `0`.
CF_UPDATE_FLAG_ALWAYS_FULL	Effective sur les fichiers d’espace réservé uniquement. Quand il est spécifié, l’espace réservé à mettre à jour est marqué toujours plein. Une fois hydraté, toute tentative de déshydrater un tel fichier d’espace réservé échoue avec le code d’erreur ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_UPDATE_FLAG_ALLOW_PARTIAL	Effective sur les fichiers d’espace réservé uniquement. Quand il est spécifié, l’état toujours complet d’un fichier d’espace réservé, s’il est présent, est effacé, ce qui lui permet d’être à nouveau déshydraté. Il n’est pas valide de spécifier cet indicateur, ainsi que CF_UPDATE_FLAG_ALWAYS_FULL et le code d’erreur ERROR_CLOUD_FILE_INVALID_REQUEST seront retournés en conséquence.

[in, out, optional] UpdateUsn

Lors de l’entrée, UpdateUsn indique à la plateforme d’effectuer la mise à jour uniquement si le fichier a toujours la même valeur USN que celle passée. Cela sert un objectif similaire à CF_UPDATE_FLAG_VERIFY_IN_SYNC , mais englobe également les modifications de métadonnées locales. Le passage d’un pointeur vers une valeur USN de lors de 0 l’entrée est identique à la transmission d’un NULL pointeur.

Au retour, UpdateUsn reçoit la valeur USN finale après l’exécution des actions de mise à jour.

[in, out, optional] Overlapped

Lorsqu’il est spécifié et combiné avec un FileHandle asynchrone, le chevauchement permet à la plateforme d’effectuer l’appel CfUpdatePlaceholder de manière asynchrone. Pour plus d’informations, consultez les remarques .

Si elle n’est pas spécifiée, la plateforme effectue l’appel d’API de manière synchrone, quelle que soit la façon dont le handle a été créé.

Valeur retournée

Si cette fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Pour mettre à jour un espace réservé :

L’espace réservé à mettre à jour doit être contenu dans une arborescence racine de synchronisation inscrite ; il peut s’agir du répertoire racine de synchronisation lui-même ou de n’importe quel répertoire descendant ; sinon, l’appel échoue avec HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
Si la déshydratation est demandée, la racine de synchronisation doit être inscrite avec une stratégie d’hydratation valide qui n’est pas CF_HYDRATION_POLICY_ALWAYS_FULL ; sinon, l’appel échoue avec HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
Si la déshydratation est demandée, l’espace réservé ne doit pas être épinglé localement ou l’appel échoue avec HRESULT(ERROR_CLOUD_FILE_PINNED).
Si la déshydratation est demandée, l’espace réservé doit être synchronisé ou l’appel échoue avec HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
L’appelant doit disposer d’un accès WRITE_DATA ou WRITE_DAC à l’espace réservé à mettre à jour. Sinon, l’opération échoue avec HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

Si l’API retourne HRESULT_FROM_WIN32(ERROR_IO_PENDING) lors de l’utilisation asynchrone de Chevauchement , l’appelant peut alors attendre à l’aide de GetOverlappedResult.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10, version 1709 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2016 (applications de bureau uniquement)
Plateforme cible	Windows
En-tête	cfapi.h
Bibliothèque	CldApi.lib
DLL	CldApi.dll

Voir aussi

CfOpenFileWithOplock

CF_UPDATE_FLAGS

Partager via