PrjUpdateFileIfNeededed-Funktion (projectedfslib.h)

Ermöglicht es einem Anbieter, ein Element zu aktualisieren, das im lokalen Dateisystem zwischengespeichert wurde.

Syntax

HRESULT PrjUpdateFileIfNeeded(
  [in]            PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
  [in]            PCWSTR                               destinationFileName,
  [in]            const PRJ_PLACEHOLDER_INFO           *placeholderInfo,
  [in]            UINT32                               placeholderInfoSize,
  [in, optional]  PRJ_UPDATE_TYPES                     updateFlags,
  [out, optional] PRJ_UPDATE_FAILURE_CAUSES            *failureReason
);

Die Parameter

[in] namespaceVirtualizationContext

Undurchsichtiges Handle für die Virtualisierungsinstanz.

[in] destinationFileName

Eine mit Null beendete Unicode-Zeichenfolge, die den Pfad relativ zum Virtualisierungsstamm angibt, zu der Datei oder dem Verzeichnis, die aktualisiert werden soll.

[in] placeholderInfo

Ein Zeiger auf einen PRJ_PLACEHOLDER_INFO Puffer, der die aktualisierten Metadaten für die Datei oder das Verzeichnis enthält.

Wenn placeholderInfo-VersionInfo.ContentID> einen Inhaltsbezeichner enthält, der mit dem Inhaltsbezeichner identisch ist, der bereits in der Datei/im Verzeichnis enthalten ist, wird der Aufruf erfolgreich ausgeführt, und es erfolgt keine Aktualisierung. Andernfalls ersetzt placeholderInfo-VersionInfo.ContentID> den vorhandenen Inhaltsbezeichner in der Datei, wenn der Aufruf erfolgreich war.

[in] placeholderInfoSize

Die Größe in Byte des Puffers, auf den durch PlatzhalterInfo verwiesen wird.

[in, optional] updateFlags

Flags zum Steuern von Updates.

Wenn es sich bei dem Element um einen schmutzigen Platzhalter, eine vollständige Datei oder einen Grabstein handelt und der Anbieter nicht die entsprechenden Flags angibt, wird durch diese Routine der Platzhalter nicht aktualisiert.

[out, optional] failureReason

Optionaler Zeiger zum Empfangen eines Codes, der den Grund beschreibt, warum ein Update fehlgeschlagen ist.

Rückgabewert

Wenn ein HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION)-Fehler zurückgegeben wird, ist das Update aufgrund des Status des Elements und des Werts von updateFlags fehlgeschlagen. failureReason, falls angegeben, beschreibt den Grund für den Fehler.

Bemerkungen

Der Anbieter verwendet diese Routine, um ein Element im lokalen Dateisystem zu aktualisieren, wenn sich die Informationen des Elements im Sicherungsspeicher des Anbieters geändert haben und die Aktualisierungen in den im lokalen Dateisystem zwischengespeicherten Elementen widerzuspiegeln sind.

Diese Routine kann nicht für eine virtuelle Datei/ein virtuelles Verzeichnis aufgerufen werden. Wenn sich die zu aktualisierende Datei/das Verzeichnis in einem anderen Zustand als "Platzhalter" befindet, muss der Anbieter eine geeignete Kombination aus PRJ_UPDATE_TYPES Werten im Parameter updateFlags angeben. Dadurch können Sie vor versehentlichem Datenverlust schützen, da das Element bei erfolgreicher Rückgabe von dieser Routine zu einem Platzhalter mit den aktualisierten Metadaten wird; Alle Metadaten, die seit dem Erstellen des Platzhalters geändert wurden, oder alle darin enthaltenen Dateidaten werden verworfen.

Der Anbieter verwendet das lokale Dateisystem als Cache der von ihm verwalteten Elemente. Ein Element (Datei oder Verzeichnis) kann in einem von sechs Zuständen im lokalen Dateisystem vorhanden sein.

Virtuell – Das Element ist nicht lokal auf dem Datenträger vorhanden. Es wird projiziert, d. h. synthetisiert, während Enumerationen des übergeordneten Verzeichnisses. Virtuelle Elemente werden mit allen Elementen zusammengeführt, die auf dem Datenträger vorhanden sein können, um den vollständigen Inhalt des übergeordneten Verzeichnisses darzustellen.

Platzhalter – Für Dateien: Der Inhalt der Datei (primärer Datenstrom) ist auf dem Datenträger nicht vorhanden. Die Metadaten der Datei (Name, Größe, Zeitstempel, Attribute usw.) werden auf dem Datenträger zwischengespeichert. Für Verzeichnisse: Einige oder alle unmittelbaren Nachfolger des Verzeichnisses (die Dateien und Verzeichnisse im Verzeichnis) sind nicht auf dem Datenträger vorhanden, d. h. sie sind weiterhin virtuell. Die Metadaten des Verzeichnisses (Name, Zeitstempel, Attribute usw.) werden auf dem Datenträger zwischengespeichert.

Hydratierter Platzhalter – Für Dateien: Der Inhalt und die Metadaten der Datei wurden auf dem Datenträger zwischengespeichert. Wird auch als "Teildatei" bezeichnet. Für Verzeichnisse: Verzeichnisse sind niemals hydratisierte Platzhalter. Ein Verzeichnis, das auf dem Datenträger als Platzhalter erstellt wurde, wird nie zu einem hydratisierten Platzhalterverzeichnis. Dadurch kann der Anbieter Elemente aus dem Verzeichnis im Sicherungsspeicher hinzufügen oder entfernen und diese Änderungen im lokalen Cache anzeigen lassen.

Schmutziger Platzhalter (hydratisiert oder nicht) – Die Metadaten des Elements wurden lokal geändert und sind nicht mehr ein Cache des Zustands im Speicher des Anbieters. Beachten Sie, dass das Erstellen oder Löschen einer Datei oder eines Verzeichnisses unter einem Platzhalterverzeichnis dazu führt, dass das Platzhalterverzeichnis schmutzig wird.

Vollständige Datei/Verzeichnis – Für Dateien: Der Inhalt der Datei (primärer Datenstrom) wurde geändert. Die Datei ist kein Cache des Zustands im Speicher des Anbieters mehr. Dateien, die im lokalen Dateisystem erstellt wurden (d. h., die überhaupt nicht im Speicher des Anbieters vorhanden sind) gelten auch als vollständige Dateien. Bei Verzeichnissen: Verzeichnisse, die im lokalen Dateisystem erstellt wurden (d. h., die überhaupt nicht im Speicher des Anbieters vorhanden sind) gelten als vollständige Verzeichnisse. Ein Verzeichnis, das auf dem Datenträger als Platzhalter erstellt wurde, wird nie zu einem vollständigen Verzeichnis.

Tombstone – Ein spezieller ausgeblendeter Platzhalter, der ein Element darstellt, das aus dem lokalen Dateisystem gelöscht wurde. Wenn ein Verzeichnis aufgezählt wird, führt ProjFS den Satz lokaler Elemente (Platzhalter, vollständige Dateien usw.) mit der Gruppe der virtuellen projizierten Elemente zusammen. Wenn ein Element sowohl in den lokalen als auch in projizierten Sätzen angezeigt wird, hat das lokale Element Vorrang. Wenn keine Datei vorhanden ist, gibt es keinen lokalen Zustand, sodass sie in der Enumeration angezeigt wird. Wenn dieses Element jedoch gelöscht wurde, wäre es unerwartet, wenn es in der Enumeration angezeigt wurde. Das Ersetzen eines gelöschten Elements durch einen Grabstein führt zu den folgenden Effekten:

• Aufzählungen, um das Element nicht anzuzeigen
• Die Datei wird geöffnet, die erwartet, dass das Element vorhanden ist, schlägt fehl, z. B. "Datei nicht gefunden".
• Die Datei erstellt, die nur erfolgreich ist, wenn das Element nicht vorhanden ist; ProjFS entfernt den Grabstein als Teil des Vorgangs.

Um die obigen Zustände zu veranschaulichen, berücksichtigen Sie die folgende Sequenz, wenn ein ProjFS-Anbieter über eine einzelne Datei "foo.txt" verfügt, die sich im Virtualisierungsstamm C befindet:\root.

• Eine App listet C:\root auf. Sie sieht die virtuelle Datei "foo.txt". Da auf die Datei noch nicht zugegriffen wurde, ist die Datei nicht auf dem Datenträger vorhanden.
• Die App öffnet ein Handle zum C:\root\foo.txt. ProjFS teilt dem Anbieter mit, einen Platzhalter dafür zu erstellen.
• Die App liest den Inhalt der Datei. Der Anbieter stellt den Dateiinhalt projFS bereit und wird in C:\root\foo.txtzwischengespeichert. Die Datei ist jetzt ein hydratisierter Platzhalter.
• Die App aktualisiert den Zeitstempel der letzten Änderung. Die Datei ist jetzt ein schmutziger hydratisierter Platzhalter.
• Die App öffnet ein Handle zum Schreiben des Zugriffs auf die Datei. C:\root\foo.txt ist jetzt eine vollständige Datei.
• Die App löscht C:\root\foo.txt. ProjFS ersetzt die Datei durch einen Grabstein. Wenn die App jetzt C:\root it does not see foo.txtaufzählt. Wenn versucht wird, die Datei zu öffnen, schlägt das Öffnen mit ERROR_FILE_NOT_FOUND fehl.

Anforderungen