Fonction CfCreatePlaceholders (cfapi.h)

Crée un ou plusieurs fichiers ou répertoires d’espace réservé sous une arborescence de répertoires racine de synchronisation.

Syntaxe

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

Paramètres

[in] BaseDirectoryPath

Chemin d’accès au répertoire local dans lequel les espaces réservés sont créés. Gardez à l’esprit ce qui suit lorsque vous spécifiez le chemin d’accès :

• Ce chemin 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 échoue avec STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT.
• 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 STATUS_CLOUD_FILE_NOT_SUPPORTED.
• L’appelant doit avoir WRITE_DATA ou WRITE_DAC accès au répertoire de base sous lequel l’espace réservé est sur le point d’être créé. Sinon, l’opération échoue avec STATUS_CLOUD_FILE_ACCESS_DENIED.

[in, out] PlaceholderArray

En cas de création réussie, placeholderArray contient la valeur USN finale et un STATUS_OK message. Au retour, ce tableau contient une valeur HRESULT indiquant si l’espace réservé a été créé ou non. PlaceholderArray pointe vers un tableau d’espaces réservés à créer, par rapport à BaseDirectoryPath. Chaque entrée du tableau comprend les champs suivants :

• RelativeFileName est le nom de l’espace réservé enfant, à la fois fichier et répertoire, à créer.
• FsMetadata contient des métadonnées de système de fichiers sur l’espace réservé à créer, y compris tous les horodatages, attributs de fichier et taille de fichier (facultatif pour les répertoires).
• FileIdentity et FileIdentityLength décrivent une mémoire tampon en mode utilisateur qui contient les informations de fichier opaques fournies par le fournisseur de synchronisation. La taille de l’objet blob FileIdentity ne doit pas dépasser CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (définie à 4 Ko). FileIdentity est renvoyé au fournisseur de synchronisation dans tous les rappels. Il s’agit d’un champ obligatoire pour les fichiers.

Un fournisseur de synchronisation peut choisir les indicateurs suivants ou une combinaison d’entre eux par espace réservé :

• CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION : cet indicateur s’applique uniquement à un répertoire d’espace réservé enfant. Lorsque l’indicateur est présent, le répertoire d’espace réservé enfant nouvellement créé est considéré comme ayant tous ses enfants présents localement, l’accès à celui-ci à l’avenir ne déclenchera aucun rappel FETCH_PLACEHOLDERS . Lorsque l’indicateur est absent, le répertoire d’espace réservé nouvellement créé est considéré comme partiel et l’accès futur déclenchera FETCH_PLACEHOLDERS.
• CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC : cet indicateur s’applique à la fois aux fichiers d’espace réservé et aux répertoires. Lorsque cet indicateur est présent, l’espace réservé nouvellement créé est marqué comme étant synchronisé dans le cadre de l’opération de TRANSFER_PLACEHOLDERS .
• CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL : cet indicateur est appliqué uniquement à un fichier d’espace réservé. Il peut être défini sur un répertoire d’espace réservé, mais il n’a aucun effet. Lorsque cet indicateur est présent, l’espace réservé nouvellement créé est marqué comme toujours plein. Une fois hydratée, toute tentative de déshydrater un tel espace réservé de fichier échoue avec le code d’erreur ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.

[in] PlaceholderCount

Nombre d’espaces réservés dans l’espace réservéArray.

[in] CreateFlags

Indicateurs pour la configuration de la création d’un espace réservé. CreateFlags peut être défini sur les valeurs suivantes :

• CF_CREATE_FLAG_NONE est le mode par défaut où l’API traite toutes les entrées dans le tableau, même lorsque des erreurs sont rencontrées.
• CF_CREATE_FLAG_STOP_ON_ERROR provoque le retour immédiat de l’API si la création d’un espace réservé échoue. Dans ce cas, l’API retourne le code d’échec.

[out] EntriesProcessed

Nombre d’entrées traitées, y compris les entrées ayant échoué. Si CF_CREATE_FLAG_STOP_ON_ERROR n’a pas été spécifié dans CreateFlags, l’API retourne le premier code d’échec rencontré, mais continue de traiter autant d’entrées que possible ; l’appelant doit ensuite inspecter le tableau pour voir quelle(s) création(s) d’espace réservé a échoué.

Valeur retournée

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

Remarques

La création d’un espace réservé avec cette fonction est préférable à la création d’un fichier avec CreateFile , puis à sa conversion en espace réservé avec CfConvertToPlaceholder ; à la fois pour l’efficacité et parce qu’il élimine la fenêtre de temps où le fichier n’est pas un espace réservé. La fonction peut également créer plusieurs fichiers ou répertoires dans un lot, ce qui peut également être plus efficace.

Cette fonction est utile lors de l’exécution d’une synchronisation initiale de fichiers ou de répertoires du cloud vers le client, ou lors de la synchronisation d’un fichier ou d’un répertoire unique nouvellement créé à partir du cloud.

Configuration requise

Voir aussi

CreateFile

CfConvertToPlaceholder