Fungsi CfRegisterSyncRoot (cfapi.h)

Melakukan pendaftaran akar sinkronisasi satu kali, memungkinkan penyedia sinkronisasi untuk mengklaim seluruh struktur pohon direktori, yang berakar di SyncRootPath, sebagai milik mereka sendiri untuk dikelola.

Sintaks

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

Parameter

[in] SyncRootPath

Jalur ke akar sinkronisasi yang akan didaftarkan.

[in] Registration

Berisi informasi tentang penyedia sinkronisasi dan akar sinkronisasi yang akan didaftarkan.

ProviderName dan ProviderVersion adalah string yang dihadapi pengguna akhir dengan panjang maksimum masing-masing 255 karakter.

SyncRootIdentity dan FileIdentity bersifat opsional dan ketika tidak disediakan panjang buffer yang sesuai juga harus diatur ke0. Mereka adalah cara bagi penyedia sinkronisasi untuk terus mengaitkan data arbitrer dengan akar sinkronisasi.

Platform ini akan menyediakan SyncRootIdentity kembali ke penyedia sinkronisasi dalam panggilan balik apa pun ke penyedia sinkronisasi. Blob FileIdentity akar sinkronisasi hanya akan disediakan ketika subjek panggilan balik adalah akar sinkronisasi itu sendiri.

Fasilitas ini disediakan hanya untuk kenyamanan penyedia sinkronisasi, dan kedua blob tidak memiliki arti khusus di luar penyedia sinkronisasi.

Panjang maksimum FileIdentity yang diizinkan adalah 4KB dan panjang maksimum syncRootIdentity yang diizinkan adalah 64KB. API gagal dengan ERROR_INVALID_PARAMETER ketika panjang maksimum terlampaui.

ProviderId adalah GUID yang dimaksudkan untuk mengidentifikasi penyedia sinkronisasi tertentu. Ini opsional. Jika tidak disediakan, platform menghasilkan GUID menggunakan hash MD5 dari string ProviderName . Informasi ini digunakan untuk telemetri sehingga platform dapat menghubungkan aktivitas dengan lebih baik dari penyedia sinkronisasi yang sama dengan lebih efisien dan lebih akurat bahkan jika penyedia sinkronisasi mendaftarkan akar sinkronisasi dengan string ProviderName yang berbeda. Disarankan agar penyedia sinkronisasi selalu menyediakan GUID yang sama untuk semua versi produk sinkronisasinya. Namun, penyedia sinkronisasi bebas memilih string ProviderName yang berbeda demi pengalaman pengguna terbaik.

[in] Policies

Kebijakan akar sinkronisasi yang akan didaftarkan.

[in] RegisterFlags

Bendera untuk mendaftarkan akar sinkronisasi sebelumnya dan baru.

Bendera	Deskripsi
CF_REGISTER_FLAG_UPDATE	Penyedia sinkronisasi dapat meneruskan CF_REGISTER_FLAG_UPDATE untuk mendaftarkan ulang identitas dan kebijakan akar sinkronisasi yang terdaftar sebelumnya.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	Perilaku populasi direktori/folder sesuai permintaan dikendalikan secara global oleh kebijakan populasi. Bendera ini memungkinkan penyedia sinkronisasi untuk menolak perilaku populasi sesuai permintaan hanya untuk akar sinkronisasi itu sendiri sambil menjaga populasi sesuai permintaan untuk semua direktori lain di bawah akar sinkronisasi. Ini berguna ketika penyedia sinkronisasi ingin mengisi file/direktori anak langsung dari akar sinkronisasi.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Bendera ini memungkinkan penyedia sinkronisasi untuk menandai akar sinkronisasi untuk didaftarkan secara bersamaan pada waktu pendaftaran. Alternatifnya adalah memanggil CfSetInSyncState pada akar sinkronisasi nanti.

Menampilkan nilai

Jika fungsi ini berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.

Keterangan

Ini dapat digunakan pada waktu penginstalan penyedia sinkronisasi, pertama kali disiapkan untuk pengguna individual, atau ketika pengguna mengonfigurasi akar sinkronisasi lain (jika skenario ini didukung).

Catatan

Tidak ada dua pohon akar sinkronisasi yang diizinkan untuk tumpang tindih. Karena tautan keras direktori dilarang oleh sistem file, satu-satunya cara bagi dua akar sinkronisasi untuk tumpang tindih adalah jika mereka memiliki hubungan leluhur/keturunan langsung. Platform ini bertanggung jawab untuk terus mengingat semua akar sinkronisasi yang terdaftar pada volume tertentu, dan gagal dalam upaya untuk membuat akar sinkronisasi yang tumpang tindih.

Penyedia sinkronisasi harus memiliki akses WRITE_DATA atau WRITE_DAC ke akar sinkronisasi yang akan didaftarkan atau pendaftaran akan gagal dengan ERROR_CLOUD_FILE_ACCESS_DENIED.

Penyedia sinkronisasi harus menyediakan catatan pendaftaran yang berisi berbagai identitas penyedia sinkronisasi itu sendiri dan akar sinkronisasi yang akan didaftarkan, serangkaian kebijakan yang digunakan platform untuk menyesuaikan perilakunya berdasarkan per-sync-root, dan serangkaian bendera pendaftaran yang memungkinkan kontrol operasi pendaftaran yang lebih halus oleh penyedia sinkronisasi.

Kecuali secara eksplisit dipanggil sebagai opsional, semua bidang wajib dan tidak menyediakannya akan mengakibatkan panggilan API gagal dengan kesalahan parameter yang tidak valid.

Semua struktur di mana ekstensi di masa mendatang diharapkan dimulai dengan bidang StructSize . Pemanggil bertanggung jawab atas akuntansi ukuran struktur yang akurat.

Platform saat ini mendukung lima jenis Kebijakan:

Kebijakan Hidrasi

Kebijakan hidrasi memungkinkan penyedia sinkronisasi untuk mengontrol bagaimana file tempat penampung harus dihidrasi oleh platform. Ini terdiri dari kebijakan utama dan serangkaian pengubah kebijakan.

Kebijakan hidrasi utama memiliki empat nilai yang berbeda:

Kebijakan	Deskripsi
ALWAYS_FULL	Platform akan gagal (dengan ERROR_CLOUD_FILE_INVALID_REQUEST) operasi tempat penampung apa pun yang dapat mengakibatkan tempat penampung yang tidak sepenuhnya terhidrasi, yang mencakup CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder dengan opsi dehidrasi, dan CfConvertToPlaceholder dengan opsi dehidrasi.
PENUH	Platform ini akan memungkinkan tempat penampung mengalami dehidrasi. Ketika platform mendeteksi akses ke tempat penampung yang didehidrasi, platform akan memastikan bahwa konten lengkap tempat penampung tersedia secara lokal sebelum menyelesaikan permintaan IO pengguna, bahkan jika permintaan hanya meminta 1 byte.
PROGRESIF	Platform ini akan memungkinkan tempat penampung mengalami dehidrasi. Ketika platform mendeteksi akses ke tempat penampung yang didehidrasi, platform akan menyelesaikan permintaan IO pengguna segera setelah menentukan bahwa data yang memadai diterima dari penyedia sinkronisasi. Namun, platform berjanji untuk terus meminta konten yang tersisa di tempat penampung dari penyedia sinkronisasi di latar belakang sampai konten lengkap tempat penampung tersedia secara lokal atau handel pengguna terakhir pada tempat penampung ditutup. Catatan: Penyedia sinkronisasi yang memilih PROGRESIF mungkin tidak mengasumsikan bahwa panggilan balik hidrasi tiba secara berurutan dari offset 0. Dengan kata lain, penyedia sinkronisasi dengan kebijakan PROGRESSIVE diharapkan dapat menangani pencarian acak pada tempat penampung.
PARSIAL	Kebijakan ini sangat mirip dengan PROGRESSIVE, dengan satu-satunya perbedaan adalah kurangnya hidrasi berkelanjutan di latar belakang.

Tiga pengubah kebijakan saat ini didukung. Secara umum, pengubah dapat dicampur dan dicocokkan dengan kebijakan utama dan pengubah kebijakan lainnya selama kombinasi tidak bertentangan sendiri.

Pengubah	Deskripsi
VALIDATION_REQUIRED	Pengubah kebijakan ini menawarkan dua jaminan kepada penyedia sinkronisasi. Pertama, ini menjamin bahwa data yang dikembalikan oleh penyedia sinkronisasi selalu disimpan ke disk sebelum dikembalikan ke aplikasi pengguna. Kedua, ini memungkinkan penyedia sinkronisasi untuk mengambil data yang sama yang telah dikembalikan sebelumnya ke platform dan memvalidasi integritasnya. Hanya setelah konfirmasi integritas yang berhasil oleh penyedia sinkronisasi, platform akan menyelesaikan permintaan IO pengguna. Pengubah ini membantu mendukung integritas data end-to-end dengan biaya IO disk tambahan.
STREAMING_ALLOWED	Pengubah kebijakan ini memberi platform izin untuk tidak menyimpan data apa pun yang dikembalikan oleh penyedia sinkronisasi pada disk lokal. Pengubah kebijakan ini saling eksklusif dengan VALIDATION_REQUIRED. API gagal dengan ERROR_INVALID_PARAMETER ketika kedua bendera ditentukan.
AUTO_DEHYDRATION_ALLOWED	Pengubah kebijakan ini memberi platform izin untuk mendehidrasi tempat penampung file cloud dalam sinkronisasi tanpa bantuan penyedia sinkronisasi. Tanpa bendera ini, platform tidak diizinkan untuk memanggil CfDehydratePlaceholder secara langsung. Sebaliknya, satu-satunya cara yang didukung untuk mendehidrasi tempat penampung file cloud adalah dengan menghapus atribut file yang disematkan dan mengatur atribut file yang tidak disematkan dan kemudian dehidrasi aktual akan dilakukan secara asinkron oleh mesin sinkronisasi setelah menerima pemberitahuan perubahan direktori pada dua atribut. Ketika bendera ini ditentukan, platform akan diizinkan untuk memanggil CfDehydratePlaceholder langsung pada tempat penampung file cloud dalam sinkronisasi. Disarankan bagi penyedia sinkronisasi untuk mendukung dehidrasi otomatis.

Kebijakan Populasi

Kebijakan populasi memungkinkan penyedia sinkronisasi untuk mengontrol bagaimana namespace layanan tempat penampung (direktori dan file) harus dibuat oleh platform. Saat ini ada tiga kebijakan utama tanpa pengubah yang ditentukan:

Kebijakan	Deskripsi
ALWAYS_FULL	Platform ini mengasumsikan bahwa ruang nama lengkap selalu tersedia secara lokal. Ini tidak akan pernah meneruskan permintaan enumerasi direktori apa pun ke penyedia sinkronisasi.
PENUH	Ketika platform mendeteksi akses pada direktori yang tidak sepenuhnya terisi, platform akan meminta penyedia sinkronisasi mengembalikan semua entri di bawah direktori sebelum menyelesaikan permintaan pengguna.
PARSIAL	Ketika platform mendeteksi akses pada direktori yang tidak sepenuhnya terisi, platform hanya akan meminta entri yang diperlukan oleh aplikasi pengguna dari penyedia sinkronisasi.

Kebijakan Pelacakan InSync

Kebijakan InSync memungkinkan penyedia sinkronisasi untuk mengontrol kapan platform harus menghapus status dalam sinkronisasi pada tempat penampung. Selain selalu menghapus sinkronisasi pada modifikasi data apa pun, platform saat ini dapat menghapus sinkronisasi pada perubahan kombinasi apa pun dari tiga atribut file (ReadOnly, System, dan Hidden) dan dua kali file (CreateTime dan LastWriteTime). Kebijakan ini dapat diterapkan ke file dan direktori secara terpisah.

Kebijakan Hardlink

Secara default, platform tidak mengizinkan tautan keras dibuat pada tempat penampung apa pun. Penyedia sinkronisasi yang mampu menangani tautan keras namun dapat menginstruksikan platform untuk mengaktifkan dukungan melalui kebijakan ALLOWED . Dengan kebijakan ini, aplikasi dapat membuat tautan keras sebanyak yang didukung sistem file selama tautan berada di bawah akar sinkronisasi yang sama atau tanpa akar sinkronisasi. Platform akan memaksa tempat penampung untuk dihidrasi ketika tautan out-of-sync-root pertama diperkenalkan dan mengembalikan tempat penampung ke file normal ketika tautan in-sync-root terakhirnya dihapus. Pembuatan hardlink yang tidak kompatibel dengan kebijakan akan gagal dengan STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. Operasi tempat penampung yang tidak kompatibel dengan kebijakan juga akan gagal dengan STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

Kebijakan Manajemen Tempat Penampung

Secara default, hanya penyedia sinkronisasi yang dapat melakukan operasi manajemen tempat penampung di akar sinkronisasi. Proses penyedia nonsinkron dapat melakukan operasi manajemen tempat penampung hanya jika akar sinkronisasi tidak aktif, yaitu, ketika akar sinkronisasi tidak terhubung ke oleh penyedia sinkronisasi apa pun. Kebijakan ini, ketika diaktifkan, memungkinkan proses penyedia nonsinkron untuk melakukan operasi manajemen tempat penampung masing-masing di akar sinkronisasi aktif. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT adalah kebijakan default yang hanya memungkinkan penyedia sinkronisasi yang terhubung untuk melakukan operasi manajemen tempat penampung apa pun. Kebijakan berikut dapat ditentukan dalam kombinasi apa pun:

Kebijakan	Deskripsi
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Ketika kebijakan ini ditentukan selama pendaftaran, proses apa pun dapat membuat tempat penampung dalam akar sinkronisasi aktif dengan memanggil CfCreatePlaceholders.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Ketika kebijakan ini ditentukan selama pendaftaran, proses apa pun dapat mengonversi file atau direktori dalam akar sinkronisasi aktif ke tempat penampung dengan memanggil CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Ketika kebijakan ini ditentukan selama pendaftaran, proses apa pun dapat memperbarui tempat penampung dalam akar sinkronisasi aktif dengan memanggil CfUpdatePlaceholder.

Catatan

Bendera ini hanya didukung jika PlatformVersion.IntegrationNumber yang diperoleh dari CfGetPlatformInfo adalah 0x310 atau lebih tinggi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10, versi 1709 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2016 [hanya aplikasi desktop]
Target Platform	Windows
Header	cfapi.h
Pustaka	CldApi.lib
DLL	CldApi.dll

Lihat juga

CfCreatePlaceholders

CfDehydratePlaceholder

CfUpdatePlaceholder

CfConvertToPlaceholder

CfGetPlatformInfo

CfSetInSyncState