Funzione CfCreatePlaceholders (cfapi.h)
Crea uno o più nuovi file segnaposto o directory in un albero della directory radice di sincronizzazione.
Sintassi
HRESULT CfCreatePlaceholders(
[in] LPCWSTR BaseDirectoryPath,
[in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
[in] DWORD PlaceholderCount,
[in] CF_CREATE_FLAGS CreateFlags,
[out] PDWORD EntriesProcessed
);
Parametri
[in] BaseDirectoryPath
Percorso della directory locale in cui vengono creati i segnaposto. Tenere presente quanto segue quando si specifica il percorso:
- Questo percorso 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 avrà esito negativo con STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT.
- La radice di sincronizzazione deve essere registrata con un criterio di idratazione valido che non è CF_HYDRATION_POLICY_ALWAYS_FULL, altrimenti la chiamata avrà esito negativo con STATUS_CLOUD_FILE_NOT_SUPPORTED.
- Il chiamante deve avere WRITE_DATA o WRITE_DAC accesso alla directory di base in cui il segnaposto sta per essere creato. In caso contrario, l'operazione non sarà riuscita con STATUS_CLOUD_FILE_ACCESS_DENIED.
[in, out] PlaceholderArray
In fase di creazione riuscita, PlaceholderArray contiene il valore USN finale e un STATUS_OK messaggio. In caso contrario, questa matrice contiene un valore HRESULT che descrive se il segnaposto è stato creato o meno. SegnapostoArray punta a una matrice di segnaposto da creare, rispetto a BaseDirectoryPath. Ogni voce nella matrice include i campi seguenti:
- RelativeFileName è il nome del segnaposto figlio, sia file che directory, da creare.
- FsMetadata contiene metadati del file system sul segnaposto da creare, inclusi tutti i timestamp, gli attributi dei file e le dimensioni dei file (facoltativo per le directory).
- FileIdentity e FileIdentityLength descrivono un buffer in modalità utente che contiene le informazioni sul file opaco fornito dal provider di sincronizzazione. Il BLOB FileIdentity non deve superare CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (definito a 4 KB) in dimensioni. FileIdentity viene passato al provider di sincronizzazione in tutti i callback. Si tratta di un campo obbligatorio per i file.
Un provider di sincronizzazione può scegliere i flag seguenti o una combinazione di tali flag in base al segnaposto:
- CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION : questo flag è applicabile solo per una directory segnaposto figlio. Quando il flag è presente, la directory segnaposto figlio appena creata viene considerata avere tutti i relativi elementi figlio presenti localmente, quindi l'accesso in futuro non attiverà alcun callback FETCH_PLACEHOLDERS su di esso. Quando il flag è assente, la directory segnaposto appena creata viene considerata parziale e l'accesso futuro attiverà FETCH_PLACEHOLDERS.
- CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC : questo flag è applicabile sia per i file segnaposto che per le directory. Quando questo flag è presente, il segnaposto appena creato verrà contrassegnato come in-sync come parte dell'operazione di TRANSFER_PLACEHOLDERS .
- CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL : questo flag viene applicato solo a un file segnaposto. Può essere impostato su una directory segnaposto, ma non ha alcun effetto. Quando questo flag è presente, il segnaposto appena creato verrà contrassegnato come sempre pieno. Una volta idratato, qualsiasi tentativo di disidratazione di tale segnaposto file avrà esito negativo con codice di errore ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
[in] PlaceholderCount
Conteggio dei segnaposto nel segnapostoArray.
[in] CreateFlags
Flag per la configurazione della creazione di un segnaposto. CreateFlags può essere impostato sui valori seguenti:
- CF_CREATE_FLAG_NONE è la modalità predefinita in cui l'API elabora tutte le voci della matrice anche quando vengono rilevati errori.
- CF_CREATE_FLAG_STOP_ON_ERROR causa la restituzione immediata dell'API se la creazione di un segnaposto ha esito negativo. In questo caso, l'API restituisce il codice di errore.
[out] EntriesProcessed
Numero di voci elaborate, incluse le voci non riuscite. Se CF_CREATE_FLAG_STOP_ON_ERROR non è stato specificato in CreateFlags, l'API restituisce il primo codice di errore rilevato, ma continua a elaborare il maggior numero possibile di voci; il chiamante deve quindi controllare la matrice per verificare quali creazione segnaposto non è riuscita.
Valore restituito
Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .
Commenti
La creazione di un segnaposto con questa funzione è preferibile rispetto alla creazione di un nuovo file con CreateFile e quindi la conversione in un segnaposto con CfConvertToPlaceholder; sia per l'efficienza che perché elimina la finestra temporale in cui il file non è un segnaposto. La funzione può anche creare più file o directory in un batch, che può anche essere più efficiente.
Questa funzione è utile quando si esegue una sincronizzazione iniziale di file o directory dal cloud verso il basso al client o quando si sincronizza un singolo file o una directory appena creata dal cloud.
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 |