CfUpdatePlaceholder, fonction (cfapi.h)

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.

[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 :

[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

Voir aussi

CfOpenFileWithOplock

CF_UPDATE_FLAGS