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 .

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.

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

[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

Vedi anche

CfOpenFileWithOplock

CF_UPDATE_FLAGS