Funzione CfUpdatePlaceholder (cfapi.h)
Questa API modifica le caratteristiche di un segnaposto esistente. L'uso più probabile di questa API è quando un file è stato modificato nel cloud e il provider di sincronizzazione vuole incorporare gli effetti di tale modifica in un segnaposto. Per supportare questo scenario, il chiamante può passare nuovi metadati del file system (timestamp, dimensioni file e così via) da applicare e/o un nuovo BLOB fileIdentity .
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
);
[in] FileHandle
FileHandle è un handle per il file o la directory i cui metadati devono essere aggiornati. Nel caso di un file, il chiamante deve acquisire un handle esclusivo per il file se intende anche disidratare il file contemporaneamente o il danneggiamento dei dati. Per ridurre al minimo l'impatto sulle applicazioni utente, è consigliabile che il chiamante ottenga l'esclusiva tramite oplock appropriati (tramite CfOpenFileWithOplock) anziché usare un handle share-nothing.
[in, optional] FsMetadata
FsMetadata contiene metadati del file system relativi al segnaposto da aggiornare, inclusi tutti i timestamp, gli attributi dei file e le dimensioni dei file (facoltativi per le directory). È un campo facoltativo. Se non specificato, tutti questi campi rimangono intatti dopo la chiamata.
- Un
0
valore in un campo timestamp (CreationTime, LastAccessTime, LastWriteTime e ChangeTime) non indica alcuna modifica al timestamp corrente nel file. - Un
0
valore in FileAttributes indica che nessuna modifica agli attributi di file correnti nel file. - Non esiste alcun valore speciale in FileSize; un
0
valore in FileSize tronca le dimensioni del file in0
.
[in, optional] FileIdentity
FileIdentity è un buffer in modalità utente contenente il file opaco o le informazioni sulla directory fornite dal chiamante. Il BLOB FileIdentity non deve superare i 4 KB di dimensioni. FileIdentity viene passato al provider di sincronizzazione in tutti i callback. Questo è facoltativo se un aggiornamento non è necessario o se il chiamante vuole rimuovere il BLOB fileIdentity dal segnaposto da aggiornare.
[in] FileIdentityLength
Lunghezza, in byte, di FileIdentity.
[in, optional] DehydrateRangeArray
Questa matrice specifica gli intervalli del segnaposto esistente che non verranno più considerati validi dopo l'aggiornamento.
L'uso più semplice di questo parametro consiste nel passare un singolo intervallo, dicendo alla piattaforma che l'intero intervallo di byte di dati non è ora valido. Un uso più complesso di questo parametro consiste nel fornire una serie di intervalli discreti da considerare non validi. Ciò implica che il provider di sincronizzazione può distinguere le modifiche a livello di file secondario. Tutti gli offset e le lunghezze devono essere PAGE_SIZE Allineati. La piattaforma garantisce che tutti gli intervalli specificati vengano disidratati come parte dell'aggiornamento. Se la disidratazione di qualsiasi intervallo ha esito negativo, l'API avrà esito negativo anziché genera contenuto di file strappati.
Nota
Il passaggio di un singolo intervallo con Offset 0 e Length CF_EOF invaliderà l'intero file: questo ha lo stesso effetto del passaggio del flag CF_UPDATE_FLAG_DEHYDRATE . Inoltre, passando CF_UPDATE_FLAG_DEHYDRATE causa l'eliminazione in modo silenzioso di DehydrateRangeArray
[in] DehydrateRangeCount
Conteggio di una serie di partizioni DisidratateArray discrete di dati segnaposto.
[in] UpdateFlags
Aggiornare i flag per i segnaposto. UpdateFlags può essere impostato sui valori seguenti:
Flag | Descrizione |
---|---|
CF_UPDATE_FLAG_VERIFY_IN_SYNC | L'aggiornamento avrà esito negativo se l'attributo IN_SYNC non è attualmente impostato sul segnaposto. Si tratta di impedire una corsa tra le modifiche di sincronizzazione dal cloud verso il basso a un segnaposto locale e il flusso di dati del segnaposto che viene modificato in locale. |
CF_UPDATE_FLAG_MARK_IN_SYNC | La piattaforma contrassegna il segnaposto come in-sync dopo un'operazione segnaposto di aggiornamento riuscita. |
CF_UPDATE_FLAG_DEHYDRATE | Applicabile solo per i file. Se specificato, la piattaforma disidrata il file dopo aver aggiornato correttamente il segnaposto. Il chiamante deve acquisire un handle esclusivo quando si specifica questo flag o danneggiamento dei dati può verificarsi. Si noti che la piattaforma non convalida l'esclusiva dell'handle. |
CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION | Applicabile solo per le directory. Se specificato, contrassegna la directory segnaposto aggiornata parzialmente popolata in modo che qualsiasi accesso futuro a esso comporterà un callback FETCH_PLACEHOLDERS inviato al provider di sincronizzazione. |
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION | Applicabile solo per le directory. Se specificato, contrassegna la directory segnaposto aggiornata completamente popolata in modo che qualsiasi accesso futuro a esso verrà gestito dalla piattaforma senza alcun callback al provider di sincronizzazione. |
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY | FileIdentity e FileIdentityLength vengono ignorati e la piattaforma rimuoverà il BLOB di identità file esistente nel segnaposto dopo una chiamata di aggiornamento riuscita. |
CF_UPDATE_FLAG_CLEAR_IN_SYNC | La piattaforma contrassegna il segnaposto come non sincronizzato dopo un'operazione segnaposto di aggiornamento riuscita. |
CF_UPDATE_FLAG_REMOVE_PROPERTY | La piattaforma rimuove tutte le proprietà extrinsiche esistenti sul segnaposto. |
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA | La piattaforma passa CF_FS_METADATA al file system senza alcun filtro; in caso contrario, la piattaforma ignora l'impostazione di tutti i campi il cui valore è 0 . |
CF_UPDATE_FLAG_ALWAYS_FULL | Efficace solo nei file segnaposto. Se specificato, il segnaposto da aggiornare è contrassegnato sempre completo. Una volta idratato, qualsiasi tentativo di disidratazione di tale file segnaposto avrà esito negativo con codice di errore ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED. |
CF_UPDATE_FLAG_ALLOW_PARTIAL | Efficace solo nei file segnaposto. Se specificato, lo stato completo sempre in un file segnaposto, se presente, viene cancellato, consentendo così di essere nuovamente disidratato. Non è valido specificare questo flag insieme a CF_UPDATE_FLAG_ALWAYS_FULL e codice di errore ERROR_CLOUD_FILE_INVALID_REQUEST verrà restituito di conseguenza. |
[in, out, optional] UpdateUsn
In input UpdateUsn indica alla piattaforma di eseguire l'aggiornamento solo se il file ha ancora lo stesso valore USN di quello passato. Questo serve uno scopo simile a CF_UPDATE_FLAG_VERIFY_IN_SYNC ma include anche modifiche dei metadati locali. Il passaggio di un puntatore a un valore USN di su input corrisponde al passaggio di 0
un NULL
puntatore.
In caso di ritorno , UpdateUsn riceve il valore USN finale dopo l'esecuzione delle azioni di aggiornamento.
[in, out, optional] Overlapped
Se specificato e combinato con un FileHandle asincrono, La sovrapposizione consente alla piattaforma di eseguire la chiamata CfUpdatePlaceholder in modo asincrono. Per altri dettagli, vedere le osservazioni .
Se non specificato, la piattaforma eseguirà la chiamata API in modo sincrono, indipendentemente dalla modalità di creazione dell'handle.
Se questa funzione ha esito positivo, restituisce S_OK
. In caso contrario, restituisce un codice di errore HRESULT .
Per aggiornare un segnaposto:
- Il segnaposto da aggiornare deve essere contenuto in un albero radice di sincronizzazione registrato; può essere la directory radice di sincronizzazione stessa o qualsiasi directory discendente; in caso contrario, la chiamata non sarà riuscita con HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
- Se è richiesta la disidratazione, la radice di sincronizzazione deve essere registrata con un criterio di idratazione valido che non è CF_HYDRATION_POLICY_ALWAYS_FULL; in caso contrario, la chiamata non sarà riuscita con HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
- Se viene richiesta la disidratazione, il segnaposto non deve essere aggiunto in locale o la chiamata non sarà riuscita con HRESULT(ERROR_CLOUD_FILE_PINNED).
- Se viene richiesta la disidratazione, il segnaposto deve essere sincronizzato o la chiamata non riesce con HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
- Il chiamante deve avere WRITE_DATA o WRITE_DAC accesso al segnaposto da aggiornare. In caso contrario, l'operazione non sarà riuscita con HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).
Se l'API restituisce HRESULT_FROM_WIN32(ERROR_IO_PENDING) quando si usa Sovrapposizione in modo asincrono, il chiamante può attendere l'uso di GetOverlappedResult.
Requisito | Valore |
---|---|
Client minimo supportato | Windows 10 versione 1709 [solo app desktop] |
Server minimo supportato | Windows Server 2016 [solo app desktop] |
Piattaforma di destinazione | Windows |
Intestazione | cfapi.h |
Libreria | CldApi.lib |
DLL | CldApi.dll |