Funzione CfRegisterSyncRoot (cfapi.h)

Articolo
04/06/2023

Esegue una registrazione radice di sincronizzazione una sola volta, consentendo a un provider di sincronizzazione di richiedere un'intera struttura ad albero della directory, radicata in SyncRootPath, come da gestire.

Sintassi

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

Parametri

[in] SyncRootPath

Percorso della radice di sincronizzazione da registrare.

[in] Registration

Contiene informazioni sul provider di sincronizzazione e sulla radice di sincronizzazione da registrare.

ProviderName e ProviderVersion sono stringhe di tipo end-user con lunghezza massima di 255 caratteri.

Sia SyncRootIdentity che FileIdentity sono facoltativi e quando non sono state specificate le relative lunghezze del buffer corrispondenti devono essere impostate anche su 0 . Sono un modo per un provider di sincronizzazione per associare in modo permanente i dati arbitrari a una radice di sincronizzazione.

La piattaforma fornirà SyncRootIdentity al provider di sincronizzazione in qualsiasi callback al provider di sincronizzazione. Il BLOB FileIdentity radice di sincronizzazione verrà fornito solo quando l'oggetto del callback è la radice di sincronizzazione stessa.

Questa funzionalità viene fornita esclusivamente per praticità del provider di sincronizzazione e entrambi i BLOB non hanno alcun significato speciale al di fuori del provider di sincronizzazione.

La lunghezza massima consentita di FileIdentity è 4 KB e la lunghezza massima consentita di SyncRootIdentity è 64 KB. L'API ha esito negativo con ERROR_INVALID_PARAMETER quando viene superata una lunghezza massima.

ProviderId è un GUID destinato a identificare un provider di sincronizzazione specifico. Questo passaggio è facoltativo. Se non specificato, la piattaforma genera un GUID usando l'hash MD5 della stringa ProviderName . Le informazioni vengono usate solo per i dati di telemetria in modo che la piattaforma possa correlare meglio le attività dello stesso provider di sincronizzazione in modo più efficiente e più accurato anche se il provider di sincronizzazione registra le radici di sincronizzazione con stringhe ProviderName diverse. È consigliabile che un provider di sincronizzazione fornisca sempre lo stesso GUID per tutte le versioni dei relativi prodotti di sincronizzazione. Tuttavia, i provider di sincronizzazione sono liberi di scegliere stringhe ProviderName diverse per il meglio dell'esperienza utente.

[in] Policies

Criteri della radice di sincronizzazione da registrare.

[in] RegisterFlags

Flag per la registrazione di radici precedenti e nuove di sincronizzazione.

Flag	Descrizione
CF_REGISTER_FLAG_UPDATE	Un provider di sincronizzazione può passare CF_REGISTER_FLAG_UPDATE per registrare nuovamente le identità e i criteri radice registrati in precedenza.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	Il comportamento della popolazione di directory/cartelle su richiesta è controllato a livello globale dai criteri di popolazione. Questo flag consente a un provider di sincronizzazione di rifiutare esplicitamente il comportamento della popolazione su richiesta solo per la radice di sincronizzazione stessa mantenendo la popolazione su richiesta per tutte le altre directory nella radice di sincronizzazione. Ciò è utile quando il provider di sincronizzazione vuole precompilare i file/directory figlio immediati della radice di sincronizzazione.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Questo flag consente a un provider di sincronizzazione di contrassegnare la radice di sincronizzazione da registrare contemporaneamente contemporaneamente al momento della registrazione. L'alternativa consiste nel chiamare CfSetInSyncState nella radice di sincronizzazione in un secondo momento.

Valore restituito

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

Commenti

Questa operazione può essere usata in un'ora di installazione del provider di sincronizzazione, prima volta configurata per un singolo utente o quando un utente configura un'altra radice di sincronizzazione (se questo scenario è supportato).

Nota

Non sono consentiti due alberi radice di sincronizzazione. Poiché i collegamenti rigidi della directory sono vietati dal file system, l'unico modo per due radici di sincronizzazione da sovrapporre è se hanno una relazione diretta predecessore/discendente. La piattaforma è responsabile della memorizzazione permanente di tutte le radici di sincronizzazione registrate in un determinato volume e non riesce a creare radici di sincronizzazione sovrapposte.

Un provider di sincronizzazione deve avere WRITE_DATA o WRITE_DAC l'accesso alla radice di sincronizzazione da registrare o la registrazione avrà esito negativo con ERROR_CLOUD_FILE_ACCESS_DENIED.

Il provider di sincronizzazione deve fornire un record di registrazione che contiene varie identità del provider di sincronizzazione stesso e la radice di sincronizzazione da registrare, un set di criteri usati dalla piattaforma per regolarne il comportamento in base alla radice di sincronizzazione e un set di flag di registrazione che consentono il controllo più corretto dell'operazione di registrazione dal provider di sincronizzazione.

A meno che non venga chiamato in modo esplicito come facoltativo, tutti i campi sono obbligatori e non vengono specificati in modo che la chiamata API non riesca con un errore di parametro non valido.

Tutte le strutture in cui sono previste estensioni future iniziano con un campo StructSize . Il chiamante è responsabile della contabilità accurata delle dimensioni della struttura.

La piattaforma supporta attualmente cinque tipi di Criteri:

Criteri di idratazione

Il criterio di idratazione consente a un provider di sincronizzazione di controllare il modo in cui i file segnaposto devono essere idratati dalla piattaforma. È costituito da criteri primari e da un set di modificatori di criteri.

I criteri di idratazione primaria hanno quattro valori diversi:

Criteri	Descrizione
ALWAYS_FULL	La piattaforma avrà esito negativo (con ERROR_CLOUD_FILE_INVALID_REQUEST) qualsiasi operazione segnaposto che potrebbe comportare un segnaposto non completamente idratato, che include CfCreatePlaceholder, CfDehydratePlaceholder, CfUpdatePlaceholder con l'opzione di disidratazione e CfConvertToPlaceholder con l'opzione di disidratazione.
FULL	La piattaforma permetterà a un segnaposto di essere disidratato. Quando la piattaforma rileva l'accesso a un segnaposto disidratato, garantisce che il contenuto completo del segnaposto sia disponibile in locale prima di completare la richiesta di I/O dell'utente, anche se la richiesta richiede solo 1 byte.
PROGRESSIVA	La piattaforma permetterà a un segnaposto di essere disidratato. Quando la piattaforma rileva l'accesso a un segnaposto disidratato, verrà completata la richiesta di I/O utente non appena determina che i dati sufficienti vengono ricevuti dal provider di sincronizzazione. Tuttavia, la piattaforma promette di continuare a richiedere il contenuto rimanente nel segnaposto dal provider di sincronizzazione in background fino a quando il contenuto completo del segnaposto è disponibile localmente o l'ultimo handle utente sul segnaposto viene chiuso. Nota: I provider di sincronizzazione che optano per PROGRESSIVE potrebbero non presumere che i callback di idratazione arrivino in sequenza dall'offset `0`. In altre parole, i provider di sincronizzazione con i criteri PROGRESSIVE devono gestire ricerche casuali sul segnaposto.
PARTIAL	Questa politica è molto simile a PROGRESSIVE, con la sola differenza che è la mancanza di idratazione continua in background.

Sono attualmente supportati tre modificatori di criteri. In generale, i modificatori possono essere misti e corrispondenti a qualsiasi criterio primario e altri modificatori di criteri, purché la combinazione non sia in conflitto.

Modificatore	Descrizione
VALIDATION_REQUIRED	Questo modificatore di criteri offre due garanzie a un provider di sincronizzazione. In primo luogo, garantisce che i dati restituiti dal provider di sincronizzazione vengano sempre mantenuti nel disco prima di essere restituiti all'applicazione utente. In secondo luogo, consente al provider di sincronizzazione di recuperare gli stessi dati restituiti in precedenza alla piattaforma e convalidarne l'integrità. Solo dopo aver completato la conferma dell'integrità dal provider di sincronizzazione, la piattaforma completa la richiesta di I/O dell'utente. Questo modificatore consente di supportare l'integrità dei dati end-to-end a costo di operazioni di I/O su disco aggiuntive.
STREAMING_ALLOWED	Questo modificatore di criteri concede alla piattaforma l'autorizzazione per non archiviare dati restituiti da un provider di sincronizzazione nei dischi locali. Questo modificatore di criteri si escludono a vicenda con VALIDATION_REQUIRED. L'API ha esito negativo con ERROR_INVALID_PARAMETER quando vengono specificati entrambi i flag.
AUTO_DEHYDRATION_ALLOWED	Questo modificatore di criteri concede alla piattaforma l'autorizzazione per la disidratazione dei segnaposto dei file cloud sincronizzati senza l'aiuto dei provider di sincronizzazione. Senza questo flag, la piattaforma non può chiamare direttamente CfDehydratePlaceholder . L'unico modo supportato per disidare un segnaposto file cloud consiste invece nel cancellare l'attributo aggiunto del file e impostare l'attributo non bloccato del file e quindi la effettiva disidratazione verrà eseguita in modo asincrono dal motore di sincronizzazione dopo aver ricevuto la notifica di modifica della directory sui due attributi. Quando viene specificato questo flag, la piattaforma sarà consentita per richiamare CfDehydratePlaceholder direttamente in qualsiasi segnaposto file cloud di sincronizzazione. È consigliabile che i provider di sincronizzazione supportino la disidratazione automatica.

Criteri di popolazione

I criteri di popolamento consentono a un provider di sincronizzazione di controllare la modalità di creazione dello spazio dei nomi segnaposto (sia directory che file) dalla piattaforma. Attualmente sono presenti tre criteri primari senza modificatori definiti:

Criteri	Descrizione
ALWAYS_FULL	La piattaforma presuppone che lo spazio completo del nome sia sempre disponibile in locale. Non inoltra mai alcuna richiesta di enumerazione directory al provider di sincronizzazione.
FULL	Quando la piattaforma rileva l'accesso in una directory non completamente popolata, richiederà al provider di sincronizzazione di restituire tutte le voci nella directory prima di completare la richiesta utente.
PARTIAL	Quando la piattaforma rileva l'accesso in una directory non completamente popolata, richiederà solo le voci richieste dall'applicazione utente dal provider di sincronizzazione.

Criteri di rilevamento InSync

Il criterio InSync consente a un provider di sincronizzazione di controllare quando la piattaforma deve cancellare lo stato di sincronizzazione in un segnaposto. Oltre a cancellare sempre la sincronizzazione in qualsiasi modifica dei dati, la piattaforma attualmente può cancellare le modifiche delle combinazioni di tre attributi di file (ReadOnly, System e Hidden) e due volte di file (CreateTime e LastWriteTime). Questi criteri possono essere applicati separatamente ai file e alle directory.

Criteri di collegamento rigido

Per impostazione predefinita, la piattaforma non consente la creazione di collegamenti rigidi su qualsiasi segnaposto. I provider di sincronizzazione in grado di gestire i collegamenti rigidi possono tuttavia indicare alla piattaforma di abilitare il supporto tramite i criteri CONSENTITI . Con questo criterio, le applicazioni possono creare tutti i collegamenti rigidi supportati dal file system, purché i collegamenti si trovino nella stessa radice di sincronizzazione o nella stessa radice di sincronizzazione. La piattaforma forza l'idratazione di un segnaposto quando viene introdotto il primo collegamento out-of-sync-root e ripristina un segnaposto al normale file quando viene rimosso l'ultimo collegamento radice di sincronizzazione. La creazione di hardlink non compatibile con i criteri non sarà riuscita con STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. Le operazioni segnaposto non compatibili con i criteri non saranno riuscite anche con STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

Criteri di gestione segnaposto

Per impostazione predefinita, solo un provider di sincronizzazione può eseguire operazioni di gestione segnaposto in una radice di sincronizzazione. I processi del provider di sincronizzazione possono eseguire operazioni di gestione segnaposto solo se la radice di sincronizzazione è inattiva, ad esempio quando la radice di sincronizzazione non è connessa da alcun provider di sincronizzazione. Questi criteri, se abilitati, consentono ai processi del provider di sincronizzazione di eseguire le rispettive operazioni di gestione segnaposto in una radice di sincronizzazione attiva. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT è il criterio predefinito che consente solo a un provider di sincronizzazione connesso di eseguire qualsiasi operazione di gestione segnaposto. I criteri seguenti possono essere specificati in qualsiasi combinazione:

Criteri	Descrizione
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Quando questo criterio viene specificato durante la registrazione, qualsiasi processo può creare un segnaposto all'interno di una radice di sincronizzazione attiva chiamando CfCreatePlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Quando questo criterio viene specificato durante la registrazione, qualsiasi processo può convertire un file o una directory all'interno di una radice di sincronizzazione attiva in un segnaposto chiamando CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Quando questo criterio viene specificato durante la registrazione, qualsiasi processo può aggiornare un segnaposto all'interno di una radice di sincronizzazione attiva chiamando CfUpdatePlaceholder.

Nota

Questi flag sono supportati solo se PlatformVersion.IntegrationNumber ottenuto da CfGetPlatformInfo è 0x310 o superiore.

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