Freigeben über

CfConvertToPlaceholder-Funktion (cfapi.h)

  • Artikel

Konvertiert eine vorhandene Nicht-Platzhalterdatei oder ein vorhandenes Verzeichnis unter einer Synchronisierungsstammverzeichnisstruktur in einen Platzhalter. Dies ist beispielsweise nützlich, nachdem eine neue lokale Datei oder ein neues verzeichnis auf einem Client angezeigt wird und der Synchronisierungsanbieter die Synchronisierung mit der Cloud abgeschlossen hat. Beachten Sie, dass es keine Parameter für die Übergabe von Dateisystemmetadaten (Zeitstempel, Dateigröße usw.) gibt. diese werden wörtlich aus der lokalen Datei entnommen.

Syntax

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
);

Parameter

[in] FileHandle

Behandeln Sie die zu konvertierende Datei oder das Verzeichnis.

[in, optional] FileIdentity

Ein Benutzermoduspuffer, der die vom Aufrufer bereitgestellten undurchsichtigen Datei- oder Verzeichnisinformationen enthält. Optional, wenn der Aufrufer die Datei nicht gleichzeitig dehydriert oder der Aufrufer ein Verzeichnis konvertiert. FileIdentity wird in allen Rückrufen an den Synchronisierungsanbieter zurückgegeben. Darf die Größe von 4 KB nicht überschreiten.

[in] FileIdentityLength

Länge des FileIdentity-Werts in Bytes.

[in] ConvertFlags

Platzhalterkonvertierungsflags. ConvertFlags können auf die folgenden Werte festgelegt werden:

Flag Beschreibung
CF_CONVERT_FLAG_MARK_IN_SYNC Wenn dies angegeben ist, markiert die Plattform den konvertierten Platzhalter nach erfolgreicher Konvertierung der Datei als mit der Cloud synchronisiert.
CF_CONVERT_FLAG_DEHYDRATE Dies gilt nur für Dateien. Bei Angabe dehydriert die Plattform die Datei, nachdem sie erfolgreich in einen Platzhalter konvertiert wurde. Der Aufrufer muss ein exklusives Handle abrufen, wenn dieses Flag angegeben wird, da datenbeschädigungen auftreten können. Beachten Sie, dass die Plattform die Exklusivität des Handles nicht überprüft.
CF_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION Dies gilt nur für Verzeichnisse. Wenn angegeben, markiert es das konvertierte Platzhalterverzeichnis teilweise aufgefüllt, sodass jeder zukünftige Zugriff darauf zu einem FETCH_PLACEHOLDERS Rückruf an den Synchronisierungsanbieter gesendet wird.
CF_CONVERT_FLAG_ALWAYS_FULL Dies gilt nur für Platzhalterdateien. Sobald eine Datei in einen Platzhalter mit diesem Flag konvertiert wurde, wird der Platzhalter immer voll markiert. Jeder Versuch, einen solchen Platzhalter zu dehydrieren, schlägt mit fehlercode ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED fehl.
CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE Bei Angabe ermöglicht die Plattform einer Synchronisierungs-Engine das atomare Konvertieren eines Platzhalters für Nicht-Clouddateien (mit einem anderen Reparse-Tag/Daten) in einen Platzhalter für Clouddateien. Beachten Sie, dass bei der API normalerweise die Konvertierung einer Nicht-Platzhalterdatei in einen Platzhalter fehlschlägt.

Die Kombination (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | CF_CONVERT_FLAG_DEHYDRATE) ist besonders nützlich in Migrationsszenarien, wenn bestimmte Anbieter von einer anderen Plattform zur Clouddateiplattform migrieren und hydratisierte Platzhalter auf der älteren Plattform atomar in dehydrierte Platzhalter auf der Clouddateien-Plattform konvertieren möchten. Nur dieses Flag sollte zum Konvertieren vollständiger Platzhalter in Clouddateien-Platzhalter übergeben werden. Wenn die ältere Plattform vollständige Dateien als reguläre Dateien ohne Platzhalter implementiert, ist dieses Flag nicht erforderlich. Durch das Übergeben dieses Flags für ein Verzeichnis werden Auch Verzeichnisse in Clouddateien konvertiert, obwohl das DEHYDRATE-Flag nicht für Verzeichnisse gilt.

Selbst wenn die Richtlinie CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED mit CfRegisterSyncRoot angegeben wurde, dürfen nur Prozesse, die mit dem Synchronisierungsstamm der Clouddateien registriert/verbunden sind, dieses Flag angeben.

Hinweis: Das Flag wird nur unterstützt, wenn das PlatformVersion.IntegrationNumber von CfGetPlatformInfo abgerufene oder höher ist 0x500 .

[out, optional] ConvertUsn

Wenn angegeben, ist dies der endgültige USN-Wert, nachdem Konvertierungsaktionen ausgeführt wurden.

[in, out, optional] Overlapped

Bei Angabe und Kombination mit einem asynchronen FileHandle ermöglicht Overlapped der Plattform die asynchrone Ausführung des CfConvertToPlaceholder-Aufrufs . Weitere Informationen finden Sie in den Anmerkungen .

Falls nicht angegeben, führt die Plattform den API-Aufruf synchron aus, unabhängig davon, wie das Handle erstellt wurde.

Rückgabewert

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

Hinweise

Im Dateifall muss der Aufrufer ein exklusives Handle für die Datei abrufen, wenn die Datei gleichzeitig dehydriert werden soll oder datenbeschädigungen auftreten können. Um die Auswirkungen auf Benutzeranwendungen zu minimieren, wird dringend empfohlen, dass der Aufrufer die Exklusivität mithilfe geeigneter Oplocks (über CfOpenFileWithOplock) erhält, anstatt ein Freigabe-Nothing-Handle zu verwenden.

So konvertieren Sie einen Platzhalter:

  • Die zu konvertierende Datei oder das Verzeichnis muss in einer registrierten Synchronisierungsstammstruktur enthalten sein. Es kann sich um das Synchronisierungsstammverzeichnis selbst oder um ein beliebiges nachgeordnetes Verzeichnis handeln. andernfalls ist beim Aufruf mit HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT) ein Fehler aufgetreten.
  • Wenn Dehydrierung angefordert wird, muss der Synchronisierungsstamm mit einer gültigen Trinkrichtlinie registriert werden, die nicht CF_HYDRATION_POLICY_ALWAYS_FULL ist. andernfalls tritt beim Aufruf ein Fehler mit HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED) auf.
  • Wenn Dehydrierung angefordert wird, darf der Platzhalter nicht lokal angeheftet werden, oder der Aufruf mit ist mit HRESULT(ERROR_CLOUD_FILE_PINNED) fehlgeschlagen.
  • Wenn Dehydrierung angefordert wird, muss der Platzhalter synchron sein, oder der Aufruf mit ist mit HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC) fehlgeschlagen.
  • Der Aufrufer muss WRITE_DATA oder WRITE_DAC Zugriff auf die zu konvertierende Datei oder das Verzeichnis haben. Andernfalls tritt beim Vorgang ein Fehler mit HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED) auf.

Wenn die API bei asynchroner Verwendung von OverlappedHRESULT_FROM_WIN32(ERROR_IO_PENDING) zurückgibt, kann der Aufrufer mit GetOverlappedResult warten.

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

Weitere Informationen

CfOpenFileWithOplock

GetOverlappedResult