Fonction CfRegisterSyncRoot (cfapi.h)

Article
04/06/2023

Effectue une inscription racine de synchronisation unique, ce qui permet à un fournisseur de synchronisation de revendiquer une arborescence d’annuaires entière, enracinée sur SyncRootPath, comme leur propre à gérer.

Syntaxe

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

Paramètres

[in] SyncRootPath

Chemin d’accès à la racine de synchronisation à inscrire.

[in] Registration

Contient des informations sur le fournisseur de synchronisation et la racine de synchronisation à inscrire.

ProviderName et ProviderVersion sont des chaînes orientées utilisateur avec une longueur maximale de 255 caractères chacune.

SyncRootIdentity et FileIdentity sont facultatifs et, lorsqu’ils ne sont pas fournis, leurs longueurs de mémoire tampon correspondantes doivent également être définies sur0. Il s’agit d’un moyen pour un fournisseur de synchronisation d’associer de manière permanente des données arbitraires à une racine de synchronisation.

La plateforme fournit SyncRootIdentity au fournisseur de synchronisation dans tous les rappels au fournisseur de synchronisation. L’objet blob FileIdentity racine de synchronisation est fourni uniquement lorsque l’objet du rappel est la racine de synchronisation elle-même.

Cette fonctionnalité est fournie uniquement pour la commodité du fournisseur de synchronisation, et les deux objets blob n’ont pas de signification particulière en dehors du fournisseur de synchronisation.

La longueur maximale autorisée de FileIdentity est de 4 Ko et la longueur maximale autorisée de SyncRootIdentity est de 64 Ko. L’API échoue avec ERROR_INVALID_PARAMETER lorsque la longueur maximale est dépassée.

ProviderId est un GUID destiné à identifier un fournisseur de synchronisation spécifique. Ce nom est facultatif. Si elle n’est pas fournie, la plateforme génère un GUID à l’aide du hachage MD5 de la chaîne ProviderName . Les informations ne sont utilisées que pour la télémétrie afin que la plateforme puisse mieux mettre en corrélation les activités du même fournisseur de synchronisation plus efficacement et plus précisément, même si le fournisseur de synchronisation inscrit des racines de synchronisation avec différentes chaînes ProviderName . Il est recommandé qu’un fournisseur de synchronisation fournisse toujours le même GUID pour toutes les versions de ses produits de synchronisation. Toutefois, les fournisseurs de synchronisation sont libres de choisir différentes chaînes ProviderName pour une expérience utilisateur optimale.

[in] Policies

Stratégies de la racine de synchronisation à inscrire.

[in] RegisterFlags

Indicateurs pour l’inscription des racines de synchronisation précédentes et nouvelles.

Indicateur	Description
CF_REGISTER_FLAG_UPDATE	Un fournisseur de synchronisation peut passer CF_REGISTER_FLAG_UPDATE pour réinscrire les identités et stratégies racines de synchronisation précédemment inscrites.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	Le comportement de la population de répertoires/dossiers à la demande est globalement contrôlé par la stratégie de population. Cet indicateur permet à un fournisseur de synchronisation de refuser le comportement de la population à la demande uniquement pour la racine de synchronisation elle-même, tout en conservant la population à la demande pour tous les autres répertoires sous la racine de synchronisation. Cela est utile lorsque le fournisseur de synchronisation souhaite préremplir les fichiers/répertoires enfants immédiats de la racine de synchronisation.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Cet indicateur permet à un fournisseur de synchronisation de marquer la racine de synchronisation pour qu’elle soit inscrite simultanément dans la synchronisation au moment de l’inscription. L’alternative consiste à appeler CfSetInSyncState à la racine de synchronisation ultérieurement.

Valeur retournée

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

Remarques

Il peut être utilisé au moment de l’installation d’un fournisseur de synchronisation, de la première configuration pour un utilisateur individuel ou lorsqu’un utilisateur configure une autre racine de synchronisation (si ce scénario est pris en charge).

Notes

Aucune arborescence racine de synchronisation n’est autorisée à se chevaucher. Étant donné que les liaisons matérielles de répertoire sont interdites par le système de fichiers, la seule façon pour deux racines de synchronisation de se chevaucher est si elles ont une relation directe ancêtre/descendant. La plateforme est responsable de la mémorisation permanente de toutes les racines de synchronisation inscrites sur un volume donné et de l’échec de toute tentative de création de racines de synchronisation qui se chevauchent.

Un fournisseur de synchronisation doit avoir WRITE_DATA ou WRITE_DAC accès à la racine de synchronisation à inscrire, sinon l’inscription échoue avec ERROR_CLOUD_FILE_ACCESS_DENIED.

Le fournisseur de synchronisation doit fournir un enregistrement d’inscription qui contient différentes identités du fournisseur de synchronisation lui-même et de la racine de synchronisation à inscrire, un ensemble de stratégies que la plateforme utilise pour ajuster son comportement par racine de synchronisation et un ensemble d’indicateurs d’inscription qui permettent un contrôle plus fin de l’opération d’inscription par le fournisseur de synchronisation.

À moins d’être explicitement appelé comme facultatif, tous les champs sont obligatoires et le fait de ne pas les fournir entraîne l’échec de l’appel d’API avec une erreur de paramètre non valide.

Toutes les structures dans lesquelles les extensions futures sont attendues commencent par un champ StructSize . L’appelant est responsable de la comptabilité précise de la taille de la structure.

La plateforme prend actuellement en charge cinq types de stratégies :

Stratégie d’hydratation

La stratégie d’hydratation permet à un fournisseur de synchronisation de contrôler la façon dont les fichiers d’espace réservé doivent être hydratés par la plateforme. Il se compose d’une stratégie principale et d’un ensemble de modificateurs de stratégie.

La stratégie d’hydratation principale a quatre valeurs différentes :

Stratégie	Description
ALWAYS_FULL	La plateforme échouera (avec ERROR_CLOUD_FILE_INVALID_REQUEST) toute opération d’espace réservé qui pourrait aboutir à un espace réservé non entièrement hydraté, ce qui inclut CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder avec l’option déshydrater et CfConvertToPlaceholder avec l’option déshydrate.
FULL	La plateforme permet de déshydrater un espace réservé. Lorsque la plateforme détecte l’accès à un espace réservé déshydraté, elle garantit que le contenu complet de l’espace réservé est disponible localement avant de terminer la demande d’E/S de l’utilisateur, même si la demande ne demande que 1 octet.
PROGRESSIVE	La plateforme permet de déshydrater un espace réservé. Lorsque la plateforme détecte l’accès à un espace réservé déshydraté, elle termine la demande d’E/S de l’utilisateur dès qu’elle détermine que des données suffisantes sont reçues du fournisseur de synchronisation. Toutefois, la plateforme promet de continuer à demander le contenu restant dans l’espace réservé auprès du fournisseur de synchronisation en arrière-plan jusqu’à ce que le contenu complet de l’espace réservé soit disponible localement ou que le dernier handle utilisateur sur l’espace réservé soit fermé. Note: Les fournisseurs de synchronisation qui optent pour PROGRESSIVE peuvent ne pas supposer que les rappels d’hydratation arrivent séquentiellement à partir du décalage `0`. En d’autres termes, les fournisseurs de synchronisation avec la stratégie PROGRESSIVE sont censés gérer les recherches aléatoires sur l’espace réservé.
PARTIAL	Cette politique est très similaire à PROGRESSIVE, la seule différence étant l’absence d’hydratation continue en arrière-plan.

Trois modificateurs de stratégie sont actuellement pris en charge. En général, les modificateurs peuvent être mélangés et mis en correspondance avec toutes les stratégies primaires et autres modificateurs de stratégie tant que la combinaison n’est pas en conflit automatique.

Modificateur	Description
VALIDATION_REQUIRED	Ce modificateur de stratégie offre deux garanties à un fournisseur de synchronisation. Tout d’abord, il garantit que les données retournées par le fournisseur de synchronisation sont toujours conservées sur le disque avant d’être retournées à l’application utilisateur. Deuxièmement, il permet au fournisseur de synchronisation de récupérer les mêmes données qu’il a retournées précédemment à la plateforme et de valider son intégrité. Ce n’est qu’une fois l’intégrité confirmée par le fournisseur de synchronisation que la plateforme termine la demande d’E/S utilisateur. Ce modificateur permet de prendre en charge l’intégrité des données de bout en bout au prix d’E/S de disque supplémentaires.
STREAMING_ALLOWED	Ce modificateur de stratégie accorde à la plateforme l’autorisation de ne stocker aucune donnée retournée par un fournisseur de synchronisation sur des disques locaux. Ce modificateur de stratégie s’exclue mutuellement avec VALIDATION_REQUIRED. L’API échoue avec ERROR_INVALID_PARAMETER lorsque les deux indicateurs sont spécifiés.
AUTO_DEHYDRATION_ALLOWED	Ce modificateur de stratégie accorde à la plateforme l’autorisation de déshydrater les espaces réservés de fichiers cloud synchronisés sans l’aide de fournisseurs de synchronisation. Sans cet indicateur, la plateforme n’est pas autorisée à appeler CfDehydratePlaceholder directement. Au lieu de cela, la seule façon prise en charge de déshydrater un espace réservé de fichier cloud consiste à effacer l’attribut épinglé du fichier et à définir l’attribut non épinglé du fichier, puis la déshydratation réelle sera effectuée de manière asynchrone par le moteur de synchronisation après avoir reçu la notification de changement de répertoire sur les deux attributs. Lorsque cet indicateur est spécifié, la plateforme est autorisée à appeler CfDehydratePlaceholder directement sur n’importe quel espace réservé de fichier cloud dans la synchronisation. Il est recommandé pour les fournisseurs de synchronisation de prendre en charge la déshydratation automatique.

Politique de population

La stratégie de population permet à un fournisseur de synchronisation de contrôler la façon dont l’espace de noms d’espace réservé (répertoires et fichiers) doit être créé par la plateforme. Il existe actuellement trois stratégies principales sans modificateurs définis :

Stratégie	Description
ALWAYS_FULL	La plateforme suppose que l’espace de nom complet est toujours disponible localement. Il ne transfère jamais une demande d’énumération d’annuaire au fournisseur de synchronisation.
FULL	Lorsque la plateforme détecte l’accès sur un répertoire qui n’est pas entièrement rempli, elle demande au fournisseur de synchronisation de retourner toutes les entrées sous l’annuaire avant de terminer la demande utilisateur.
PARTIAL	Lorsque la plateforme détecte l’accès sur un annuaire non rempli, elle demande uniquement les entrées requises par l’application utilisateur auprès du fournisseur de synchronisation.

Stratégie de suivi InSync

La stratégie InSync permet à un fournisseur de synchronisation de contrôler quand la plateforme doit effacer l’état de synchronisation sur un espace réservé. En plus d’effacer toujours l’insynchronisation pour toute modification de données, la plateforme peut actuellement effacer les modifications insynchronisées de toutes les combinaisons de trois attributs de fichier (ReadOnly, System et Hidden) et deux fois de fichier (CreateTime et LastWriteTime). Ces stratégies peuvent être appliquées aux fichiers et aux répertoires séparément.

Stratégie de liaison matérielle

Par défaut, la plateforme n’autorise pas la création de liens durs sur un espace réservé. Les fournisseurs de synchronisation capables de gérer les liaisons matérielles peuvent toutefois demander à la plateforme d’activer la prise en charge via la stratégie AUTORISÉ . Avec cette stratégie, les applications peuvent créer autant de liens physiques que le système de fichiers prend en charge tant que les liens se trouvent sous la même racine de synchronisation ou sous aucune racine de synchronisation. La plateforme force l’hydratation d’un espace réservé lorsque le premier lien hors synchronisation-racine est introduit et rétablit un espace réservé au fichier normal lorsque son dernier lien racine de synchronisation est supprimé. La création de liaisons matérielles qui n’est pas compatible avec la stratégie échoue avec STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. Les opérations d’espace réservé qui ne sont pas compatibles avec la stratégie seront également échouées avec STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

Stratégie de gestion des espaces réservés

Par défaut, seul un fournisseur de synchronisation peut effectuer des opérations de gestion des espaces réservés dans une racine de synchronisation. Les processus de fournisseur non de synchronisation peuvent effectuer des opérations de gestion des espaces réservés uniquement si la racine de synchronisation est inactive, c’est-à-dire lorsque la racine de synchronisation n’est pas connectée à par un fournisseur de synchronisation. Lorsqu’elles sont activées, ces stratégies permettent aux processus du fournisseur non de synchronisation d’effectuer des opérations de gestion des espaces réservés respectives dans une racine de synchronisation active. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT est la stratégie par défaut qui autorise uniquement un fournisseur de synchronisation connecté à effectuer des opérations de gestion des espaces réservés. Les stratégies suivantes peuvent être spécifiées dans n’importe quelle combinaison :

Stratégie	Description
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Lorsque cette stratégie est spécifiée lors de l’inscription, n’importe quel processus peut créer un espace réservé au sein d’une racine de synchronisation active en appelant CfCreatePlaceholders.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Lorsque cette stratégie est spécifiée lors de l’inscription, n’importe quel processus peut convertir un fichier ou un répertoire au sein d’une racine de synchronisation active en espace réservé en appelant CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Lorsque cette stratégie est spécifiée lors de l’inscription, n’importe quel processus peut mettre à jour un espace réservé au sein d’une racine de synchronisation active en appelant CfUpdatePlaceholder.

Notes

Ces indicateurs sont pris en charge uniquement si PlatformVersion.IntegrationNumber obtenu à partir de CfGetPlatformInfo est ou supérieur 0x310 .

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