CfUpdatePlaceholder-Funktion (cfapi.h)
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
0Wert in einem Zeitstempelfeld (CreationTime, LastAccessTime, LastWriteTime und ChangeTime) bedeutet keine Änderung des aktuellen Zeitstempels für die Datei. - Ein
0Wert in FileAttributes bedeutet keine Änderung der aktuellen Dateiattribute für die Datei. - In FileSize gibt es keinen besonderen Wert. ein
0Wert in FileSize schneidet die Dateigröße auf0ab.
[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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für