Funzione CfConvertToPlaceholder (cfapi.h)

Converte un file o una directory non segnaposto esistente in un albero della directory radice di sincronizzazione in un segnaposto. Ciò è utile, ad esempio, dopo la visualizzazione di un nuovo file o directory locale in un client e il provider di sincronizzazione ha terminato la sincronizzazione con il cloud. Si noti che non esistono parametri per passare i metadati del file system (timestamp, dimensioni del file e così via); vengono presi verbatim dal file locale.

Sintassi

HRESULT CfConvertToPlaceholder(
  [in]                HANDLE           FileHandle,
  [in, optional]      LPCVOID          FileIdentity,
  [in]                DWORD            FileIdentityLength,
  [in]                CF_CONVERT_FLAGS ConvertFlags,
  [out, optional]     USN              *ConvertUsn,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

Parametri

[in] FileHandle

Handle nel file o nella directory da convertire.

[in, optional] FileIdentity

Buffer in modalità utente che contiene il file opaco o le informazioni sulla directory fornite dal chiamante. Facoltativo se il chiamante non sta disidratando il file contemporaneamente o se il chiamante converte una directory. FileIdentity viene restituito al provider di sincronizzazione in tutti i callback. Non può superare le dimensioni di 4 KB.

[in] FileIdentityLength

Lunghezza, in byte, di FileIdentity.

[in] ConvertFlags

Flag di conversione segnaposto. ConvertFlags può essere impostato sui valori seguenti:

[out, optional] ConvertUsn

Se specificato, questo è il valore USN finale dopo l'esecuzione delle azioni di conversione.

[in, out, optional] Overlapped

Se specificato e combinato con un oggetto FileHandle asincrono, Overlapped consente alla piattaforma di eseguire la chiamata CfConvertToPlaceholder in modo asincrono. Per altri dettagli, vedere la sezione 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

Nel caso di 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'esclusività usando oplock appropriati (tramite CfOpenFileWithOplock) anziché usare un handle di condivisione-nothing.

Per convertire un segnaposto:

• Il file o la directory da convertire devono essere contenuti in un albero radice di sincronizzazione registrato; può essere la directory radice di sincronizzazione stessa o qualsiasi directory discendente; in caso contrario, la chiamata con non è 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 riesce con HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
• Se è richiesta la disidratazione, il segnaposto non deve essere aggiunto in locale o la chiamata con non è riuscita con HRESULT(ERROR_CLOUD_FILE_PINNED).
• Se è richiesta la disidratazione, il segnaposto deve essere sincronizzato o la chiamata con non è riuscita con HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
• Il chiamante deve avere WRITE_DATA o WRITE_DAC l'accesso al file o alla directory da convertire. 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 usando GetOverlappedResult.

Requisiti

Vedi anche

CfOpenFileWithOplock

GetOverlappedResult