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 :
| Indicateur | Description |
|---|---|
| CF_CONVERT_FLAG_MARK_IN_SYNC | Si cela est spécifié, la plateforme marque l’espace réservé converti comme étant synchronisé avec le cloud lors d’une conversion réussie du fichier. |
| CF_CONVERT_FLAG_DEHYDRATE | Cela s’applique uniquement aux fichiers. Lorsqu’elle est spécifiée, la plateforme déshydrate le fichier après l’avoir converti en 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_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION | Cela s’applique uniquement aux répertoires. Lorsqu’il est spécifié, il marque le répertoire d’espace réservé converti partiellement rempli de sorte que tout accès futur à celui-ci entraîne un rappel FETCH_PLACEHOLDERS envoyé au fournisseur de synchronisation. |
| CF_CONVERT_FLAG_ALWAYS_FULL | Cela s’applique uniquement aux fichiers d’espace réservé. Une fois qu’un fichier est converti en espace réservé avec cet indicateur, l’espace réservé est toujours marqué plein. Toute tentative de déshydrater un tel espace réservé échoue avec le code d’erreur ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED. |
| CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | Lorsqu’elle est spécifiée, la plateforme permet à un moteur de synchronisation de convertir atomiquement un espace réservé de fichiers non cloud (avec une autre balise/données d’analyse) en espace réservé de fichiers cloud. Notez que l’API échoue normalement à convertir tout fichier sans espace réservé en espace réservé. Combinaison (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | CF_CONVERT_FLAG_DEHYDRATE) est particulièrement utile dans les scénarios de migration lorsque certains fournisseurs migrent d’une autre plateforme vers une plateforme de fichiers cloud et qu’ils ont l’intention de convertir atomiquement des espaces réservés hydratés sur l’ancienne plateforme en espaces réservés déshydratés sur la plateforme de fichiers cloud. Seul cet indicateur doit être passé pour convertir des espaces réservés complets en espaces réservés de fichiers cloud. Si l’ancienne plateforme implémente des fichiers complets en tant que fichiers ordinaires non réservés, cet indicateur n’est pas nécessaire. La transmission de cet indicateur sur un répertoire convertit également les répertoires en fichiers cloud, bien que l’indicateur DEHYDRATE ne s’applique pas aux répertoires. Même lorsque la stratégie CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED a été spécifiée avec CfRegisterSyncRoot, seuls les processus inscrits/connectés à la racine de synchronisation des fichiers cloud sont autorisés à spécifier cet indicateur. Note: L’indicateur est pris en charge uniquement si le PlatformVersion.IntegrationNumber obtenu à partir de CfGetPlatformInfo est 0x500 ou supérieur. |
[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
| 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 |