Condividi tramite

Funzione CfUpdatePlaceholder (cfapi.h)

  • Articolo

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 .

Sintassi

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

Parametri

[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 in 0.

[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.

Valore restituito

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

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.

Requisiti

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

Vedi anche

CfOpenFileWithOplock

CF_UPDATE_FLAGS