Fungsi CfCreatePlaceholders (cfapi.h)

2023-04-06

Membuat satu atau beberapa file atau direktori tempat penampung baru di bawah pohon direktori akar sinkronisasi.

Sintaks

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

Parameter

[in] BaseDirectoryPath

Jalur ke direktori lokal tempat tempat penampung dibuat. Ingatlah hal-hal berikut saat menentukan jalur:

Jalur ini harus terkandung dalam pohon akar sinkronisasi terdaftar. Ini bisa menjadi direktori akar sinkronisasi itu sendiri, atau direktori turunan apa pun. Jika tidak, panggilan akan gagal dengan STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT.
Akar sinkronisasi harus didaftarkan dengan kebijakan hidrasi valid yang tidak CF_HYDRATION_POLICY_ALWAYS_FULL, jika tidak, panggilan akan gagal dengan STATUS_CLOUD_FILE_NOT_SUPPORTED.
Pemanggil harus memiliki akses WRITE_DATA atau WRITE_DAC ke direktori dasar tempat tempat penampung akan dibuat. Jika tidak, operasi akan gagal dengan STATUS_CLOUD_FILE_ACCESS_DENIED.

[in, out] PlaceholderArray

Pada pembuatan yang berhasil, PlaceholderArray berisi nilai USN akhir dan pesan STATUS_OK . Saat dikembalikan, array ini berisi nilai HRESULT yang menjelaskan apakah tempat penampung dibuat atau tidak. PlaceholderArray menunjuk ke array tempat penampung yang akan dibuat, relatif terhadap BaseDirectoryPath. Setiap entri dalam array menyertakan bidang berikut:

RelativeFileName adalah nama tempat penampung anak, baik file maupun direktori, yang akan dibuat.
FsMetadata berisi metadata sistem file tentang tempat penampung yang akan dibuat, termasuk semua tanda waktu, atribut file, dan ukuran file (opsional untuk direktori).
FileIdentity dan FileIdentityLength menjelaskan buffer mode pengguna yang berisi informasi file buram yang disediakan oleh penyedia sinkronisasi. Blob FileIdentity tidak boleh melebihi ukuran CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (didefinisikan hingga 4KB). FileIdentity akan diteruskan kembali ke penyedia sinkronisasi di semua panggilan balik. Ini adalah bidang wajib untuk file.

Penyedia sinkronisasi dapat memilih bendera berikut atau kombinasinya berdasarkan per tempat penampung:

CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION - Bendera ini hanya berlaku untuk direktori tempat penampung anak. Ketika bendera ada, direktori tempat penampung anak yang baru dibuat dianggap memiliki semua anaknya yang hadir secara lokal sehingga mengaksesnya di masa depan tidak akan memicu panggilan balik FETCH_PLACEHOLDERS di atasnya. Ketika bendera tidak ada, direktori tempat penampung yang baru dibuat dianggap parsial dan akses di masa mendatang akan memicu FETCH_PLACEHOLDERS.
CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC - Bendera ini berlaku untuk file tempat penampung dan direktori. Ketika bendera ini ada, tempat penampung yang baru dibuat akan ditandai sebagai sinkron sebagai bagian dari operasi TRANSFER_PLACEHOLDERS .
CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL - Bendera ini diberlakukan hanya pada file tempat penampung. Ini dapat diatur pada direktori tempat penampung, tetapi tidak berpengaruh. Ketika bendera ini ada, tempat penampung yang baru dibuat akan ditandai sebagai selalu penuh. Setelah terhidrasi, setiap upaya untuk mendehidrasi tempat penampung file seperti itu akan gagal dengan kode kesalahan ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.

[in] PlaceholderCount

Jumlah tempat penampung di PlaceholderArray.

[in] CreateFlags

Bendera untuk mengonfigurasi pembuatan tempat penampung. CreateFlags dapat diatur ke nilai berikut:

CF_CREATE_FLAG_NONE adalah mode default di mana API memproses semua entri dalam array bahkan ketika kesalahan ditemui.
CF_CREATE_FLAG_STOP_ON_ERROR menyebabkan API segera kembali jika pembuatan tempat penampung gagal. Dalam hal ini, API mengembalikan kode kegagalan.

[out] EntriesProcessed

Jumlah entri yang diproses, termasuk entri yang gagal. Jika CF_CREATE_FLAG_STOP_ON_ERROR tidak ditentukan dalam CreateFlags, API mengembalikan kode kegagalan pertama yang ditemui, tetapi terus memproses entri sebanyak mungkin; pemanggil kemudian harus memeriksa array untuk melihat pembuatan tempat penampung mana yang gagal.

Nilai kembali

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

Keterangan

Membuat tempat penampung dengan fungsi ini lebih disukai dibandingkan dengan membuat file baru dengan CreateFile lalu mengonversinya menjadi tempat penampung dengan CfConvertToPlaceholder; baik untuk efisiensi maupun karena menghilangkan jendela waktu di mana file bukan tempat penampung. Fungsi ini juga dapat membuat beberapa file atau direktori dalam batch, yang juga bisa lebih efisien.

Fungsi ini berguna saat melakukan sinkronisasi awal file atau direktori dari cloud ke klien, atau saat menyinkronkan satu file atau direktori yang baru dibuat dari cloud.

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

CreateFile

CfConvertToPlaceholder

Bagikan melalui