CfRegisterSyncRoot-Funktion (cfapi.h)

Artikel
02/26/2024

Führt eine einmalige Synchronisierungsstammregistrierung aus, sodass ein Synchronisierungsanbieter eine gesamte Verzeichnisstruktur, die in SyncRootPath verwurzelt ist, als eigene zu verwaltende Struktur beanspruchen kann.

Syntax

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

Parameter

[in] SyncRootPath

Der Pfad zum zu registrierenden Synchronisierungsstamm.

[in] Registration

Enthält Informationen zum Synchronisierungsanbieter und Synchronisierungsstamm, der registriert werden soll.

ProviderName und ProviderVersion sind endbenutzerseitige Zeichenfolgen mit einer maximalen Länge von jeweils 255 Zeichen.

Sowohl SyncRootIdentity als auch FileIdentity sind optional, und wenn nicht angegeben, sollten auch die entsprechenden Pufferlängen auf 0 festgelegt werden. Sie sind eine Möglichkeit für einen Synchronisierungsanbieter, beliebige Daten dauerhaft einem Synchronisierungsstamm zuzuordnen.

Die Plattform stellt SyncRootIdentity in allen Rückrufen an den Synchronisierungsanbieter zurück an den Synchronisierungsanbieter bereit. Das FileIdentity-Stammblob für die Synchronisierung wird nur bereitgestellt, wenn der Betreff des Rückrufs der Synchronisierungsstamm selbst ist.

Diese Funktion wird ausschließlich zur Vereinfachung des Synchronisierungsanbieters bereitgestellt, und beide Blobs haben keine besondere Bedeutung außerhalb des Synchronisierungsanbieters.

Die maximal zulässige Länge von FileIdentity beträgt 4 KB und die maximal zulässige Länge von SyncRootIdentity beträgt 64 KB. Die API schlägt mit ERROR_INVALID_PARAMETER fehl, wenn die maximale Länge überschritten wird.

ProviderId ist eine GUID, die einen bestimmten Synchronisierungsanbieter identifizieren soll. Der Vorgang ist optional. Falls nicht angegeben, generiert die Plattform eine GUID mithilfe des MD5-Hashs der ProviderName-Zeichenfolge . Die Informationen werden nur für Telemetriedaten verwendet, sodass die Plattform Aktivitäten desselben Synchronisierungsanbieters effizienter und genauer korrelieren kann, selbst wenn der Synchronisierungsanbieter Synchronisierungswurzeln mit verschiedenen ProviderName-Zeichenfolgen registriert. Es wird empfohlen, dass ein Synchronisierungsanbieter immer dieselbe GUID für alle Versionen seiner Synchronisierungsprodukte bereitstellt. Synchronisierungsanbieter können jedoch verschiedene ProviderName-Zeichenfolgen auswählen, um die beste Benutzererfahrung zu gewährleisten.

[in] Policies

Die Richtlinien des zu registrierenden Synchronisierungsstamms.

[in] RegisterFlags

Flags zum Registrieren vorheriger und neuer Synchronisierungsstammelemente.

Flag	Beschreibung
CF_REGISTER_FLAG_UPDATE	Ein Synchronisierungsanbieter kann CF_REGISTER_FLAG_UPDATE übergeben, um zuvor registrierte Synchronisierungsstammidentitäten und -richtlinien erneut zu registrieren.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	Das Bedarfsgesteuerte Verzeichnis-/Ordnerauffüllungsverhalten wird global durch die Auffüllungsrichtlinie gesteuert. Dieses Flag ermöglicht es einem Synchronisierungsanbieter, das On-Demand-Auffüllungsverhalten nur für den Synchronisierungsstamm selbst zu deaktivieren, während die Bedarfsauffüllung für alle anderen Verzeichnisse unter dem Synchronisierungsstamm aktiviert bleibt. Dies ist nützlich, wenn der Synchronisierungsanbieter die unmittelbar untergeordneten Dateien/Verzeichnisse des Synchronisierungsstamms vorab auffüllen möchte.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Dieses Flag ermöglicht es einem Synchronisierungsanbieter, den Synchronisierungsstamm gleichzeitig zum Zeitpunkt der Registrierung zu registrieren. Alternativ können Sie CfSetInSyncState später im Synchronisierungsstamm aufrufen.

Rückgabewert

Wenn diese Funktion erfolgreich ist, wird zurückgegeben S_OK. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Dies kann bei der Installation eines Synchronisierungsanbieters, beim ersten Einrichten für einen einzelnen Benutzer oder beim Konfigurieren eines anderen Synchronisierungsstamms verwendet werden (sofern dieses Szenario unterstützt wird).

Hinweis

Zwei Synchronisierungsstammstrukturen dürfen sich nicht überlappen. Da feste Verzeichnisverknüpfungen vom Dateisystem verboten sind, können sich zwei Synchronisierungswurzeln nur überschneiden, wenn sie eine direkte Vorgänger-/Nachfolgerbeziehung haben. Die Plattform ist dafür verantwortlich, alle Synchronisierungsstämme, die auf einem bestimmten Volume registriert sind, dauerhaft zu speichern und zu versuchen, sich überlappende Synchronisierungswurzeln zu erstellen.

Ein Synchronisierungsanbieter sollte WRITE_DATA oder WRITE_DAC Zugriff auf den zu registrierenden Synchronisierungsstamm haben, andernfalls schlägt die Registrierung mit ERROR_CLOUD_FILE_ACCESS_DENIED fehl.

Der Synchronisierungsanbieter sollte einen Registrierungsdatensatz bereitstellen, der verschiedene Identitäten des Synchronisierungsanbieters selbst und des zu registrierenden Synchronisierungsstamms enthält, eine Reihe von Richtlinien, die die Plattform verwendet, um ihr Verhalten pro Sync-Root-Basis anzupassen, und eine Reihe von Registrierungsflags, die eine präzisere Kontrolle des Registrierungsvorgangs durch den Synchronisierungsanbieter ermöglichen.

Sofern nicht explizit als optional aufgerufen, sind alle Felder obligatorisch, und wenn sie nicht bereitgestellt werden, führt dies dazu, dass der API-Aufruf mit einem ungültigen Parameterfehler fehlschlägt.

Alle Strukturen, in denen zukünftige Erweiterungen erwartet werden, beginnen mit einem StructSize-Feld . Der Aufrufer ist für die genaue Abrechnung der Strukturgröße verantwortlich.

Die Plattform unterstützt derzeit fünf Arten von Richtlinien:

Hydrierungsrichtlinie

Mit der Hydrierungsrichtlinie kann ein Synchronisierungsanbieter steuern, wie Platzhalterdateien von der Plattform aktiviert werden sollen. Sie besteht aus einer primären Richtlinie und einer Reihe von Richtlinienmodifizierern.

Die primäre Hydrierungsrichtlinie weist vier verschiedene Werte auf:

Richtlinie	BESCHREIBUNG
ALWAYS_FULL	Die Plattform schlägt (mit ERROR_CLOUD_FILE_INVALID_REQUEST) jeden Platzhaltervorgang fehl, der zu einem nicht vollständig aktivierten Platzhalter führen könnte, der CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder mit der Dehydrierungsoption und CfConvertToPlaceholder mit der Dehydrierungsoption umfasst.
FULL	Die Plattform ermöglicht es, einen Platzhalter zu dehydrieren. Wenn die Plattform den Zugriff auf einen dehydrierten Platzhalter erkennt, stellt sie sicher, dass der vollständige Inhalt des Platzhalters lokal verfügbar ist, bevor die E/A-Anforderung des Benutzers abgeschlossen wird, auch wenn die Anforderung nur 1 Byte fordert.
PROGRESSIVE	Die Plattform ermöglicht es, einen Platzhalter zu dehydrieren. Wenn die Plattform den Zugriff auf einen dehydrierten Platzhalter erkennt, schließt sie die E/A-Anforderung des Benutzers ab, sobald sie feststellt, dass genügend Daten vom Synchronisierungsanbieter empfangen werden. Die Plattform verspricht jedoch, den verbleibenden Inhalt im Platzhalter weiterhin vom Synchronisierungsanbieter im Hintergrund anzufordern, bis entweder der vollständige Inhalt des Platzhalters lokal verfügbar ist oder das letzte Benutzerhandle für den Platzhalter geschlossen wird. Hinweis: Synchronisierungsanbieter, die PROGRESSIVE verwenden, gehen möglicherweise nicht davon aus, dass Hydrationsrückrufe sequenziell aus dem Offset `0`eingehen. Anders ausgedrückt: Von Synchronisierungsanbietern mit progressiver Richtlinie wird erwartet, dass sie zufällige Suchvorgänge auf dem Platzhalter verarbeiten.
PARTIAL	Diese Richtlinie ist PROGRESSIVE sehr ähnlich, wobei der einzige Unterschied darin besteht, dass keine kontinuierliche Flüssigkeit im Hintergrund vorhanden ist.

Derzeit werden drei Richtlinienmodifizierer unterstützt. Im Allgemeinen können Modifizierer gemischt und mit allen primären Richtlinien und anderen Richtlinienmodifizierern abgeglichen werden, solange die Kombination nicht selbst in Konflikt steht.

Modifizierer	BESCHREIBUNG
VALIDATION_REQUIRED	Dieser Richtlinienmodifizierer bietet zwei Garantien für einen Synchronisierungsanbieter. Erstens wird sichergestellt, dass die vom Synchronisierungsanbieter zurückgegebenen Daten immer auf dem Datenträger gespeichert werden, bevor sie an die Benutzeranwendung zurückgegeben werden. Zweitens ermöglicht es dem Synchronisierungsanbieter, die gleichen Daten abzurufen, die er zuvor an die Plattform zurückgegeben hat, und deren Integrität zu überprüfen. Erst nach einer erfolgreichen Bestätigung der Integrität durch den Synchronisierungsanbieter führt die Plattform die E/A-Anforderung des Benutzers aus. Dieser Modifizierer unterstützt die End-to-End-Datenintegrität auf Kosten zusätzlicher Datenträger-IOs.
STREAMING_ALLOWED	Dieser Richtlinienmodifizierer gewährt der Plattform die Berechtigung, keine von einem Synchronisierungsanbieter zurückgegebenen Daten auf lokalen Datenträgern zu speichern. Dieser Richtlinienmodifizierer schließt sich mit VALIDATION_REQUIRED gegenseitig aus. Die API schlägt mit ERROR_INVALID_PARAMETER fehl, wenn beide Flags angegeben sind.
AUTO_DEHYDRATION_ALLOWED	Dieser Richtlinienmodifizierer gewährt der Plattform die Berechtigung, in der Synchronisierung cloudbasierte Dateiplatzhalter ohne Hilfe von Synchronisierungsanbietern zu deaktivieren. Ohne dieses Flag darf die Plattform CfDehydratePlaceholder nicht direkt aufrufen. Stattdessen besteht die einzige unterstützte Möglichkeit zum Deaktivieren eines Clouddateiplatzhalters darin, das angeheftete Attribut der Datei zu löschen und das nicht angeheftete Attribut der Datei festzulegen. Die eigentliche Dehydrierung wird dann asynchron von der Synchronisierungs-Engine ausgeführt, nachdem die Verzeichnisänderungsbenachrichtigung für die beiden Attribute empfangen wurde. Wenn dieses Flag angegeben ist, kann die Plattform CfDehydratePlaceholder direkt für jeden platzhalter für synchronisierte Clouddateien aufrufen. Es wird für Synchronisierungsanbieter empfohlen, um die automatische Dehydrierung zu unterstützen.

Bevölkerungsrichtlinie

Mit der Auffüllungsrichtlinie kann ein Synchronisierungsanbieter steuern, wie der Platzhalternamespace (sowohl Verzeichnisse als auch Dateien) von der Plattform erstellt werden soll. Derzeit gibt es drei primäre Richtlinien, für die keine Modifizierer definiert sind:

Richtlinie	BESCHREIBUNG
ALWAYS_FULL	Die Plattform geht davon aus, dass der vollständige Namensraum immer lokal verfügbar ist. Es wird niemals eine Verzeichnisenumerationsanforderung an den Synchronisierungsanbieter weitergeleitet.
FULL	Wenn die Plattform den Zugriff auf ein nicht vollständig ausgefülltes Verzeichnis erkennt, fordert sie den Synchronisierungsanbieter auf, alle Einträge unter dem Verzeichnis zurückzugeben, bevor die Benutzeranforderung abgeschlossen wird.
PARTIAL	Wenn die Plattform den Zugriff auf ein nicht vollständig ausgefülltes Verzeichnis erkennt, fordert sie nur die für die Benutzeranwendung erforderlichen Einträge vom Synchronisierungsanbieter an.

InSync-Nachverfolgungsrichtlinie

Mit der InSync-Richtlinie kann ein Synchronisierungsanbieter steuern, wann die Plattform den In-Sync-Status auf einem Platzhalter löschen soll. Zusätzlich zur immer erfolgten Synchronisierung bei jeder Datenänderung kann die Plattform derzeit änderungen einer beliebigen Kombination aus drei Dateiattributen (ReadOnly, System und Ausgeblendet) und zwei Dateizeiten (CreateTime und LastWriteTime) in der Synchronisierung löschen. Diese Richtlinien können separat auf Dateien und Verzeichnisse angewendet werden.

Hardlinkrichtlinie

Standardmäßig lässt die Plattform das Erstellen von Hardlinks auf keinem Platzhalter zu. Synchronisierungsanbieter, die hardlinks verarbeiten können, können die Plattform jedoch anweisen, den Support über die ALLOWED-Richtlinie zu aktivieren. Mit dieser Richtlinie können Anwendungen so viele Hardlinks erstellen, wie das Dateisystem unterstützt, solange sich die Links entweder unter demselben Synchronisierungsstamm oder ohne Synchronisierungsstamm befinden. Die Plattform erzwingt, dass ein Platzhalter hydratisiert wird, wenn der erste Out-of-Sync-Root-Link eingeführt wird, und rückgängig machen einen Platzhalter auf eine normale Datei, wenn der letzte In-Sync-Root-Link entfernt wird. Bei der Erstellung von Hardlinks, die nicht mit der Richtlinie kompatibel sind, tritt ein Fehler mit STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS auf. Platzhaltervorgänge, die nicht mit der Richtlinie kompatibel sind, treten auch bei STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS ein Fehler auf.

Platzhalterverwaltungsrichtlinie

Standardmäßig kann nur ein Synchronisierungsanbieter Platzhalterverwaltungsvorgänge in einem Synchronisierungsstamm ausführen. Nicht-Synchronisierungsanbieterprozesse können Platzhalterverwaltungsvorgänge nur ausführen, wenn der Synchronisierungsstamm inaktiv ist, d. h. wenn der Synchronisierungsstamm von keinem Synchronisierungsanbieter verbunden ist. Wenn diese Richtlinien aktiviert sind, können Nichtsynchronisierungsanbieterprozesse entsprechende Platzhalterverwaltungsvorgänge in einem aktiven Synchronisierungsstamm ausführen. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT ist die Standardrichtlinie, die es nur einem verbundenen Synchronisierungsanbieter ermöglicht, Platzhalterverwaltungsvorgänge auszuführen. Die folgenden Richtlinien können in beliebiger Kombination angegeben werden:

Richtlinie	BESCHREIBUNG
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Wenn diese Richtlinie während der Registrierung angegeben wird, kann jeder Prozess einen Platzhalter in einem aktiven Synchronisierungsstamm erstellen, indem CfCreatePlaceholders aufgerufen wird.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Wenn diese Richtlinie während der Registrierung angegeben wird, kann jeder Prozess eine Datei oder ein Verzeichnis innerhalb eines aktiven Synchronisierungsstamms in einen Platzhalter konvertieren, indem CfConvertToPlaceholder aufgerufen wird.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Wenn diese Richtlinie während der Registrierung angegeben wird, kann jeder Prozess einen Platzhalter in einem aktiven Synchronisierungsstamm aktualisieren, indem CfUpdatePlaceholder aufgerufen wird.

Hinweis

Diese Flags werden nur unterstützt, wenn PlatformVersion.IntegrationNumber , die von CfGetPlatformInfo abgerufen wurde, oder höher ist 0x310 .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10, Version 1709 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2016 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	cfapi.h
Bibliothek	CldApi.lib
DLL	CldApi.dll