CfCreatePlaceholders-Funktion (cfapi.h)

Erstellt eine oder mehrere neue Platzhalterdateien oder Verzeichnisse unter einer Synchronisierungsstammverzeichnisstruktur.

Syntax

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

Parameter

[in] BaseDirectoryPath

Pfad zum lokalen Verzeichnis, in dem die Platzhalter erstellt werden. Beachten Sie Folgendes, wenn Sie den Pfad angeben:

• Dieser Pfad muss in einer registrierten Synchronisierungsstammstruktur enthalten sein. Dabei kann es sich um das Synchronisierungsstammverzeichnis selbst oder um ein beliebiges nachfolgerfähiges Verzeichnis handeln. Andernfalls schlägt der Aufruf mit STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT fehl.
• Der Synchronisierungsstamm muss mit einer gültigen Flüssigkeitsrichtlinie registriert werden, die nicht CF_HYDRATION_POLICY_ALWAYS_FULL ist. Andernfalls schlägt der Aufruf mit STATUS_CLOUD_FILE_NOT_SUPPORTED fehl.
• Der Aufrufer muss WRITE_DATA oder WRITE_DAC Zugriff auf das Basisverzeichnis haben, unter dem der Platzhalter erstellt werden soll. Andernfalls tritt beim Vorgang ein Fehler mit STATUS_CLOUD_FILE_ACCESS_DENIED auf.

[in, out] PlaceholderArray

Bei erfolgreicher Erstellung enthält PlaceholderArray den endgültigen USN-Wert und eine STATUS_OK Meldung. Bei der Rückgabe enthält dieses Array einen HRESULT-Wert , der beschreibt, ob der Platzhalter erstellt wurde oder nicht. PlaceholderArray verweist auf ein Array von Platzhaltern, die erstellt werden sollen, relativ zu BaseDirectoryPath. Jeder Eintrag im Array enthält die folgenden Felder:

• RelativeFileName ist der Name des zu erstellenden untergeordneten Platzhalters( Datei und Verzeichnis).
• FsMetadata enthält Dateisystemmetadaten zum zu erstellenden Platzhalter, einschließlich aller Zeitstempel, Dateiattribute und Dateigröße (optional für Verzeichnisse).
• FileIdentity und FileIdentityLength beschreiben einen Benutzermoduspuffer, der die vom Synchronisierungsanbieter bereitgestellten undurchsichtigen Dateiinformationen enthält. Das FileIdentity-Blob sollte CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (definiert in 4 KB) nicht überschreiten. FileIdentity wird in allen Rückrufen an den Synchronisierungsanbieter zurückgegeben. Dies ist ein obligatorisches Feld für Dateien.

Ein Synchronisierungsanbieter kann die folgenden Flags oder eine Kombination davon pro Platzhalter auswählen:

• CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION : Dieses Flag gilt nur für ein untergeordnetes Platzhalterverzeichnis. Wenn das Flag vorhanden ist, wird davon ausgegangen, dass im neu erstellten untergeordneten Platzhalterverzeichnis alle untergeordneten Elemente lokal vorhanden sind, sodass der Zugriff darauf in Zukunft keinen FETCH_PLACEHOLDERS Rückruf auslöst. Wenn das Flag nicht vorhanden ist, wird das neu erstellte Platzhalterverzeichnis als teilweise betrachtet, und der zukünftige Zugriff wird FETCH_PLACEHOLDERS auslösen.
• CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC : Dieses Flag gilt sowohl für Platzhalterdateien als auch für Verzeichnisse. Wenn dieses Flag vorhanden ist, wird der neu erstellte Platzhalter im Rahmen des TRANSFER_PLACEHOLDERS-Vorgangs als synchron markiert.
• CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL : Dieses Flag wird nur für eine Platzhalterdatei erzwungen. Sie kann für ein Platzhalterverzeichnis festgelegt werden, hat aber keine Auswirkung. Wenn dieses Flag vorhanden ist, wird der neu erstellte Platzhalter als immer voll markiert. Nach der Aktivierung schlägt jeder Versuch, einen solchen Dateiplatzhalter zu deaktivieren, mit fehlercode ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED fehl.

[in] PlaceholderCount

Die Anzahl der Platzhalter in PlaceholderArray.

[in] CreateFlags

Flags zum Konfigurieren der Erstellung eines Platzhalters. CreateFlags kann auf die folgenden Werte festgelegt werden:

• CF_CREATE_FLAG_NONE ist der Standardmodus, in dem die API alle Einträge im Array verarbeitet, auch wenn Fehler auftreten.
• CF_CREATE_FLAG_STOP_ON_ERROR bewirkt, dass die API sofort zurückgegeben wird, wenn die Erstellung eines Platzhalters fehlschlägt. In diesem Fall gibt die API den Fehlercode zurück.

[out] EntriesProcessed

Die Anzahl der verarbeiteten Einträge, einschließlich fehlerhafter Einträge. Wenn CF_CREATE_FLAG_STOP_ON_ERROR in CreateFlags nicht angegeben wurde, gibt die API den ersten aufgetretenen Fehlercode zurück, setzt aber die Verarbeitung so vieler Einträge wie möglich fort. Der Aufrufer muss dann das Array untersuchen, um festzustellen, welche Platzhaltererstellung fehlgeschlagen ist.

Rückgabewert

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

Hinweise

Das Erstellen eines Platzhalters mit dieser Funktion wird gegenüber dem Erstellen einer neuen Datei mit CreateFile und dem anschließenden Konvertieren in einen Platzhalter mit CfConvertToPlaceholder bevorzugt. sowohl aus Effizienzgründen als auch, weil dadurch das Zeitfenster wegfällt, in dem die Datei kein Platzhalter ist. Die Funktion kann auch mehrere Dateien oder Verzeichnisse in einem Batch erstellen, was auch effizienter sein kann.

Diese Funktion ist nützlich, wenn Sie eine erste Synchronisierung von Dateien oder Verzeichnissen aus der Cloud mit dem Client durchführen oder wenn Sie eine neu erstellte einzelne Datei oder ein verzeichnis aus der Cloud synchronisieren.

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

CreateFile

CfConvertToPlaceholder