Freigeben über

CfUpdatePlaceholder-Funktion (cfapi.h)

  • Artikel

Diese API ändert die Merkmale eines vorhandenen Platzhalters. Die wahrscheinlichste Verwendung dieser API ist, wenn eine Datei in der Cloud geändert wurde und der Synchronisierungsanbieter die Auswirkungen dieser Änderung in einen Platzhalter integrieren möchte. Zur Unterstützung dieses Szenarios kann der Aufrufer neue Dateisystemmetadaten (Zeitstempel, Dateigröße usw.) für die Anwendung und/oder ein neues FileIdentity-Blob übergeben.

Syntax

HRESULT CfUpdatePlaceholder(
  [in]                HANDLE               FileHandle,
  [in, optional]      const CF_FS_METADATA *FsMetadata,
  [in, optional]      LPCVOID              FileIdentity,
  [in]                DWORD                FileIdentityLength,
  [in, optional]      const CF_FILE_RANGE  *DehydrateRangeArray,
  [in]                DWORD                DehydrateRangeCount,
  [in]                CF_UPDATE_FLAGS      UpdateFlags,
  [in, out, optional] USN                  *UpdateUsn,
  [in, out, optional] LPOVERLAPPED         Overlapped
);

Parameter

[in] FileHandle

FileHandle ist ein Handle für die Datei oder das Verzeichnis, dessen Metadaten aktualisiert werden sollen. Im Fall einer Datei 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.

[in, optional] FsMetadata

FsMetadata enthält Dateisystemmetadaten zum zu aktualisierenden Platzhalter, einschließlich aller Zeitstempel, Dateiattribute und Dateigröße (optional für Verzeichnisse). Dies ist ein optionales Feld. Wenn nicht angegeben, bleiben alle diese Felder nach dem Aufruf intakt.

  • Ein 0 Wert in einem Zeitstempelfeld (CreationTime, LastAccessTime, LastWriteTime und ChangeTime) bedeutet keine Änderung des aktuellen Zeitstempels für die Datei.
  • Ein 0 Wert in FileAttributes bedeutet keine Änderung der aktuellen Dateiattribute für die Datei.
  • In FileSize gibt es keinen besonderen Wert. ein 0 Wert in FileSize schneidet die Dateigröße auf 0ab.

[in, optional] FileIdentity

FileIdentity ist ein Benutzermoduspuffer, der die vom Aufrufer bereitgestellten undurchsichtigen Datei- oder Verzeichnisinformationen enthält. Das FileIdentity-Blob sollte die Größe von 4 KB nicht überschreiten. FileIdentity wird in allen Rückrufen an den Synchronisierungsanbieter zurückgegeben. Dies ist optional, wenn kein Update erforderlich ist oder wenn der Aufrufer das FileIdentity-Blob aus dem zu aktualisierenden Platzhalter entfernen möchte.

[in] FileIdentityLength

Länge des FileIdentity-Werts in Bytes.

[in, optional] DehydrateRangeArray

Dieses Array gibt Bereiche des vorhandenen Platzhalters an, die nach dem Update nicht mehr als gültig gelten.

Die einfachste Verwendung dieses Parameters besteht darin, einen einzelnen Bereich zu übergeben und der Plattform mitzuteilen, dass der gesamte Bytebereich von Daten jetzt ungültig ist. Eine komplexere Verwendung dieses Parameters besteht darin, eine Reihe diskreter Bereiche bereitzustellen, die als ungültig gelten. Dies bedeutet, dass der Synchronisierungsanbieter Änderungen auf Unterdateiebene unterscheiden kann. Alle Offsets und Längen sollten PAGE_SIZE ausgerichtet sein. Die Plattform stellt sicher, dass alle angegebenen Bereiche im Rahmen des Updates dehydriert werden. Wenn die Dehydrierung von Bereichen fehlschlägt, schlägt die API fehl, anstatt zu gerissenen Dateiinhalten zu führen.

Hinweis

Durch Das Übergeben eines einzelnen Bereichs mit Offset 0 und Length CF_EOF wird die gesamte Datei ungültig. Dies hat die gleiche Auswirkung wie das Übergeben des Flags CF_UPDATE_FLAG_DEHYDRATE stattdessen. Außerdem führt das Übergeben CF_UPDATE_FLAG_DEHYDRATE dazu, dass DehydrateRangeArray im Hintergrund gelöscht wird.

[in] DehydrateRangeCount

Die Anzahl einer Reihe diskreter DehydrateRangeArray-Partitionen von Platzhalterdaten.

[in] UpdateFlags

Aktualisieren sie Flags für Platzhalter. UpdateFlags kann auf die folgenden Werte festgelegt werden:

Flag Beschreibung
CF_UPDATE_FLAG_VERIFY_IN_SYNC Das Update schlägt fehl, wenn das attribut IN_SYNC derzeit nicht auf dem Platzhalter festgelegt ist. Dadurch soll verhindert werden, dass änderungen aus der Cloud mit einem lokalen Platzhalter synchronisiert werden und der Datenstrom des Platzhalters lokal geändert wird.
CF_UPDATE_FLAG_MARK_IN_SYNC Die Plattform markiert den Platzhalter nach einem erfolgreichen Aktualisierungsplatzhaltervorgang als synchron.
CF_UPDATE_FLAG_DEHYDRATE Gilt nur für Dateien. Bei Angabe dehydriert die Plattform die Datei, nachdem der Platzhalter erfolgreich aktualisiert 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_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION Gilt nur für Verzeichnisse. Wenn angegeben, markiert es das aktualisierte Platzhalterverzeichnis teilweise aufgefüllt, sodass jeder zukünftige Zugriff darauf zu einem FETCH_PLACEHOLDERS Rückruf führt, der an den Synchronisierungsanbieter gesendet wird.
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION Gilt nur für Verzeichnisse. Wenn angegeben, markiert es das aktualisierte Platzhalterverzeichnis vollständig aufgefüllt, sodass jeder zukünftige Zugriff darauf von der Plattform ohne Rückrufe an den Synchronisierungsanbieter verarbeitet wird.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY FileIdentity und FileIdentityLength werden ignoriert, und die Plattform entfernt das vorhandene Dateiidentitätsblob auf dem Platzhalter nach einem erfolgreichen Updateaufruf.
CF_UPDATE_FLAG_CLEAR_IN_SYNC Die Plattform markiert den Platzhalter bei einem erfolgreichen Updateplatzhaltervorgang als nicht synchron.
CF_UPDATE_FLAG_REMOVE_PROPERTY Die Plattform entfernt alle vorhandenen extrinsischen Eigenschaften auf dem Platzhalter.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA Die Plattform übergibt CF_FS_METADATA ohne Filterung an das Dateisystem. Andernfalls überspringt die Plattform das Festlegen von Feldern, deren Wert ist 0.
CF_UPDATE_FLAG_ALWAYS_FULL Gilt nur für Platzhalterdateien. Wenn angegeben, ist der zu aktualisierende Platzhalter immer voll markiert. Nach der Hydratisierung schlägt jeder Versuch, eine solche Platzhalterdatei zu dehydrieren, mit fehlercode ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED fehl.
CF_UPDATE_FLAG_ALLOW_PARTIAL Gilt nur für Platzhalterdateien. Wenn angegeben, wird der immer vollständige Zustand einer Platzhalterdatei gelöscht, sofern vorhanden, sodass sie erneut dehydriert werden kann. Es ist ungültig, dieses Flag zusammen mit CF_UPDATE_FLAG_ALWAYS_FULL und Fehlercode anzugeben , ERROR_CLOUD_FILE_INVALID_REQUEST daraufhin zurückgegeben werden.

[in, out, optional] UpdateUsn

Bei der Eingabe weist UpdateUsn die Plattform an, das Update nur auszuführen, wenn die Datei noch denselben USN-Wert wie der übergebene aufweist. Dies dient einem ähnlichen Zweck wie CF_UPDATE_FLAG_VERIFY_IN_SYNC umfasst aber auch lokale Metadatenänderungen. Das Übergeben eines Zeigers auf einen USN-Wert von 0 bei eingabe ist mit dem Übergeben eines NULL Zeigers identisch.

Bei der Rückgabe erhält UpdateUsn den endgültigen USN-Wert, nachdem Aktualisierungsaktionen 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 CfUpdatePlaceholder-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

So aktualisieren Sie einen Platzhalter:

  • Der zu aktualisierende Platzhalter muss in einer registrierten Synchronisierungsstammstruktur enthalten sein. Es kann sich um das Synchronisierungsstammverzeichnis selbst oder um ein beliebiges nachgeordnetes Verzeichnis handeln. Andernfalls tritt beim Aufruf ein Fehler mit HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT) auf.
  • 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, andernfalls tritt beim Aufruf ein Fehler mit HRESULT(ERROR_CLOUD_FILE_PINNED) auf.
  • Wenn Dehydrierung angefordert wird, muss der Platzhalter synchron sein, andernfalls tritt ein Fehler mit HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC) auf.
  • Der Aufrufer muss WRITE_DATA oder WRITE_DAC Zugriff auf den Platzhalter haben, um aktualisiert zu werden. 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

CF_UPDATE_FLAGS