Fonction CfConvertToPlaceholder (cfapi.h)

Convertit un fichier ou un répertoire sans espace réservé existant dans une arborescence de répertoire racine de synchronisation en espace réservé. Cela est utile, par exemple, lorsqu’un nouveau fichier ou répertoire local s’affiche sur un client et que le fournisseur de synchronisation a terminé sa synchronisation avec le cloud. Notez qu’il n’existe aucun paramètre pour la transmission des métadonnées du système de fichiers (horodatages, taille de fichier, etc.) ; celles-ci sont extraites textuellement du fichier local.

Syntaxe

HRESULT CfConvertToPlaceholder(
  [in]                HANDLE           FileHandle,
  [in, optional]      LPCVOID          FileIdentity,
  [in]                DWORD            FileIdentityLength,
  [in]                CF_CONVERT_FLAGS ConvertFlags,
  [out, optional]     USN              *ConvertUsn,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

Paramètres

[in] FileHandle

Gérez le fichier ou le répertoire à convertir.

[in, optional] FileIdentity

Mémoire tampon en mode utilisateur qui contient les informations de fichier ou de répertoire opaques fournies par l’appelant. Facultatif si l’appelant ne déshydrat pas le fichier en même temps ou si l’appelant convertit un répertoire. FileIdentity est renvoyé au fournisseur de synchronisation dans tous les rappels. Ne peut pas dépasser 4 Ko.

[in] FileIdentityLength

Longueur, en octets, de FileIdentity.

[in] ConvertFlags

Indicateurs de conversion d’espace réservé. ConvertFlags peut être défini sur les valeurs suivantes :

[out, optional] ConvertUsn

Lorsqu’elle est spécifiée, il s’agit de la valeur USN finale après l’exécution des actions de conversion.

[in, out, optional] Overlapped

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

Si ce n’est pas spécifié, 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

Dans le cas du 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, sinon 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.

Pour convertir un espace réservé :

• Le fichier ou le répertoire à convertir doit être contenu dans une arborescence racine de synchronisation inscrite ; il peut s’agir du répertoire racine de synchronisation lui-même ou d’un répertoire descendant ; sinon, l’appel avec a échoué 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 avec a échoué avec HRESULT(ERROR_CLOUD_FILE_PINNED).
• Si la déshydratation est demandée, l’espace réservé doit être synchronisé ou l’appel avec a échoué avec HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
• L’appelant doit disposer d’un accès WRITE_DATA ou WRITE_DAC au fichier ou au répertoire à convertir. 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 du chevauchement asynchrone, l’appelant peut attendre à l’aide de GetOverlappedResult.

Configuration requise

Voir aussi

CfOpenFileWithOplock

GetOverlappedResult