Funzione PrjUpdateFileIfNeeded (projectedfslib.h)

Consente a un provider di aggiornare un elemento memorizzato nella cache nel file system locale.

Sintassi

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

Parametri

[in] namespaceVirtualizationContext

Handle opaco per l'istanza di virtualizzazione.

[in] destinationFileName

Stringa Unicode con terminazione Null che specifica il percorso, relativo alla radice di virtualizzazione, al file o alla directory da aggiornare.

[in] placeholderInfo

Puntatore a un buffer PRJ_PLACEHOLDER_INFO contenente i metadati aggiornati per il file o la directory.

Se placeholderInfo-VersionInfo.ContentID> contiene un identificatore di contenuto uguale all'identificatore di contenuto già presente nel file o nella directory, la chiamata ha esito positivo e non viene eseguito alcun aggiornamento. In caso contrario, se la chiamata ha esito positivo, placeholderInfo-VersionInfo.ContentID> sostituisce l'identificatore di contenuto esistente nel file.

[in] placeholderInfoSize

Dimensione in byte del buffer a cui punta placeholderInfo.

[in, optional] updateFlags

Flag per controllare gli aggiornamenti.

Se l'elemento è un segnaposto dirty, un file completo o una rimozione definitiva e il provider non specifica i flag appropriati, questa routine non riuscirà ad aggiornare il segnaposto

[out, optional] failureReason

Puntatore facoltativo per ricevere un codice che descrive il motivo per cui un aggiornamento non è riuscito.

Valore restituito

Se viene restituito un errore HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION), l'aggiornamento non è riuscito a causa dello stato dell'elemento e del valore di updateFlags. failureReason, se specificato, descriverà il motivo dell'errore.

Commenti

Il provider usa questa routine per aggiornare un elemento nel file system locale se le informazioni dell'elemento sono state modificate nell'archivio di backup del provider e gli aggiornamenti devono essere riflessi negli elementi memorizzati nella cache nel file system locale.

Questa routine non può essere chiamata in un file/directory virtuale. Se il file o la directory da aggiornare è in qualsiasi stato diverso da "segnaposto", il provider deve specificare una combinazione appropriata di PRJ_UPDATE_TYPES valori nel parametro updateFlags. Ciò consente di evitare la perdita accidentale di dati, poiché al corretto ritorno da questa routine l'elemento diventa un segnaposto con i metadati aggiornati; tutti i metadati modificati dopo la creazione del segnaposto o i dati del file contenuti vengono eliminati.

Il provider usa il file system locale come cache degli elementi gestiti. Un elemento (file o directory) può essere in uno dei sei stati nel file system locale.

Virtuale: l'elemento non esiste in locale sul disco. Viene proiettato, ovvero sintetizzato, durante le enumerazioni della directory padre. Gli elementi virtuali vengono uniti a tutti gli elementi che possono esistere su disco per presentare il contenuto completo della directory padre.

Segnaposto : per i file: il contenuto del file (flusso di dati primario) non è presente sul disco. I metadati del file (nome, dimensioni, timestamp, attributi e così via) vengono memorizzati nella cache sul disco. Per le directory: alcuni o tutti i discendenti immediati della directory (i file e le directory nella directory) non sono presenti sul disco, ad esempio sono ancora virtuali. I metadati della directory (nome, timestamp, attributi e così via) vengono memorizzati nella cache sul disco.

Segnaposto idratato : per i file: il contenuto e i metadati del file sono stati memorizzati nella cache sul disco. Detto anche "file parziale". Per le directory: le directory non sono mai segnaposto idratate. Una directory creata su disco come segnaposto non diventa mai una directory segnaposto idratata. In questo modo il provider può aggiungere o rimuovere elementi dalla directory nel relativo archivio di backup e fare in modo che tali modifiche vengano riflesse nella cache locale.

Segnaposto dirty (idratato o meno): i metadati dell'elemento sono stati modificati localmente e non sono più una cache dello stato nell'archivio del provider. Si noti che la creazione o l'eliminazione di un file o di una directory in una directory segnaposto fa sì che la directory segnaposto diventi dirty.

File/directory completo - Per i file: il contenuto del file (flusso di dati primario) è stato modificato. Il file non è più una cache dello stato nell'archivio del provider. Anche i file creati nel file system locale (ovvero che non esistono nell'archivio del provider) vengono considerati file completi. Per le directory: le directory create nel file system locale ,ovvero che non esistono nell'archivio del provider, vengono considerate directory complete. Una directory creata su disco come segnaposto non diventa mai una directory completa.

Rimozione definitiva: segnaposto nascosto speciale che rappresenta un elemento eliminato dal file system locale. Quando una directory viene enumerata ProjFS unisce il set di elementi locali (segnaposto, file completi e così via) con il set di elementi proiettati virtuali. Se un elemento viene visualizzato sia nei set locali che nei set proiettati, l'elemento locale ha la precedenza. Se un file non esiste, non esiste alcuno stato locale, quindi viene visualizzato nell'enumerazione . Tuttavia, se tale elemento è stato eliminato, la visualizzazione nell'enumerazione sarebbe imprevista. La sostituzione di un elemento eliminato con una rimozione definitiva comporta gli effetti seguenti:

• Enumerazioni per non visualizzare l'elemento
• Il file viene aperto che prevede che l'elemento esista non riesce, ad esempio "file non trovato".
• Il file crea l'esito positivo solo se l'elemento non esiste correttamente; ProjFS rimuove la pietra definitiva come parte dell'operazione.

Per illustrare gli stati precedenti, prendere in considerazione la sequenza seguente, dato un provider ProjFS con un singolo file "foo.txt" che si trova nella radice di virtualizzazione C:\root.

• Un'app enumera C:\root. Viene visualizzato il file virtuale "foo.txt". Poiché il file non è ancora stato eseguito, il file non esiste su disco.
• L'app apre un handle per C:\root\foo.txt. ProjFS indica al provider di creare un segnaposto.
• L'app legge il contenuto del file. Il provider fornisce il contenuto del file a ProjFS e viene memorizzato nella cache in C:\root\foo.txt. Il file è ora un segnaposto idratato.
• L'app aggiorna il timestamp dell'ultima modifica. Il file è ora un segnaposto idratato sporco.
• L'app apre un handle per l'accesso in scrittura al file. C:\root\foo.txt è ora un file completo.
• L'app elimina C:\root\foo.txt. ProjFS sostituisce il file con una rimozione definitiva. Ora quando l'app enumera C:\root non viene visualizzata foo.txt. Se tenta di aprire il file, l'apertura ha esito negativo con ERROR_FILE_NOT_FOUND.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10, versione 1809 [solo app desktop]
Server minimo supportato	Windows Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	projectedfslib.h