Fungsi CfUpdatePlaceholder (cfapi.h)

API ini mengubah karakteristik tempat penampung yang ada. Penggunaan API ini yang paling mungkin adalah ketika file telah dimodifikasi di cloud, dan penyedia sinkronisasi ingin memasukkan efek modifikasi tersebut ke dalam tempat penampung. Untuk mendukung skenario ini, pemanggil dapat meneruskan metadata sistem file baru (tanda waktu, ukuran file, dll.) untuk diterapkan, dan/atau blob FileIdentity baru.

Sintaks

HRESULT CfUpdatePlaceholder(
  [in]                HANDLE               FileHandle,
  [in, optional]      const CF_FS_METADATA *FsMetadata,
  [in, optional]      LPCVOID              FileIdentity,
  [in]                DWORD                FileIdentityLength,
  [in, optional]      const CF_FILE_RANGE  *DehydrateRangeArray,
  [in]                DWORD                DehydrateRangeCount,
  [in]                CF_UPDATE_FLAGS      UpdateFlags,
  [in, out, optional] USN                  *UpdateUsn,
  [in, out, optional] LPOVERLAPPED         Overlapped
);

Parameter

[in] FileHandle

FileHandle adalah handel ke file atau direktori yang metadatanya akan diperbarui. Dalam kasus file, pemanggil harus memperoleh handel eksklusif ke file jika juga berniat untuk melakukan dehidrasi file pada saat yang sama atau kerusakan data dapat terjadi. Untuk meminimalkan dampak pada aplikasi pengguna, sangat disarankan agar pemanggil mendapatkan kekhususan menggunakan oplock yang tepat (melalui CfOpenFileWithOplock) dibandingkan dengan menggunakan handel share-nothing.

[in, optional] FsMetadata

FsMetadata berisi metadata sistem file tentang tempat penampung yang akan diperbarui, termasuk semua tanda waktu, atribut file, dan ukuran file (opsional untuk direktori). Ini langkah opsional. Jika tidak disediakan, semua bidang ini tetap utuh setelah panggilan.

Nilai 0 dalam bidang tanda waktu (CreationTime, LastAccessTime, LastWriteTime, dan ChangeTime) berarti tidak ada perubahan pada tanda waktu saat ini pada file.
Nilai 0 dalam FileAttributes berarti tidak ada perubahan pada atribut file saat ini pada file.
Tidak ada nilai khusus dalam FileSize; 0 nilai dalam FileSize memotong ukuran file menjadi 0.

[in, optional] FileIdentity

FileIdentity adalah buffer mode pengguna yang berisi file buram atau informasi direktori yang disediakan oleh pemanggil. Blob FileIdentity tidak boleh melebihi ukuran 4KB. FileIdentity akan diteruskan kembali ke penyedia sinkronisasi di semua panggilan balik. Ini opsional jika pembaruan tidak diperlukan atau jika pemanggil ingin menghapus blob FileIdentity dari tempat penampung yang akan diperbarui.

[in] FileIdentityLength

Panjang, dalam byte, dari FileIdentity.

[in, optional] DehydrateRangeArray

Array ini menentukan rentang tempat penampung yang ada yang tidak akan lagi dianggap valid setelah pembaruan.

Penggunaan paling sederhana dari parameter ini adalah untuk melewati satu rentang, memberi tahu platform bahwa seluruh rentang byte data sekarang tidak valid. Penggunaan parameter ini yang lebih kompleks adalah menyediakan serangkaian rentang diskrit untuk dianggap tidak valid. Ini menyiratkan bahwa penyedia sinkronisasi dapat membedakan perubahan pada tingkat sub-file. Semua offset dan panjang harus PAGE_SIZE Selaras. Platform akan memastikan bahwa semua rentang yang ditentukan mengalami dehidrasi sebagai bagian dari pembaruan. Jika dehidrasi rentang apa pun gagal, API akan gagal daripada mengakibatkan konten file yang robek.

Catatan

Melewati satu rentang dengan Offset 0 dan Panjang CF_EOF akan membatalkan seluruh file - Ini memiliki efek yang sama seperti meneruskan bendera CF_UPDATE_FLAG_DEHYDRATE sebagai gantinya. Juga, melewati CF_UPDATE_FLAG_DEHYDRATE menyebabkan DehydrateRangeArray diam-diam dijatuhkan

[in] DehydrateRangeCount

Jumlah serangkaian partisi data tempat penampung DehydrateRangeArray diskrit.

[in] UpdateFlags

Perbarui bendera untuk tempat penampung. UpdateFlags dapat diatur ke nilai berikut:

Bendera	Deskripsi
CF_UPDATE_FLAG_VERIFY_IN_SYNC	Pembaruan akan gagal jika atribut IN_SYNC saat ini tidak diatur pada tempat penampung. Hal ini untuk mencegah perlombaan antara menyinkronkan perubahan dari cloud ke tempat penampung lokal dan aliran data tempat penampung dimodifikasi secara lokal.
CF_UPDATE_FLAG_MARK_IN_SYNC	Platform menandai tempat penampung sebagai tidak sinkron setelah operasi tempat penampung pembaruan berhasil.
CF_UPDATE_FLAG_DEHYDRATE	Hanya berlaku untuk file. Ketika ditentukan, platform melakukan dehidrasi file setelah memperbarui tempat penampung dengan sukses. Pemanggil harus memperoleh handel eksklusif ketika menentukan bendera atau kerusakan data ini dapat terjadi. Perhatikan bahwa platform tidak memvalidasi kerahasiaan handel.
CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION	Hanya berlaku untuk direktori. Ketika ditentukan, ini menandai direktori tempat penampung yang diperbarui yang diisi sebagian sed sehingga akses di masa mendatang ke direktori tersebut akan menghasilkan panggilan balik FETCH_PLACEHOLDERS yang dikirim ke penyedia sinkronisasi.
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION	Hanya berlaku untuk direktori. Ketika ditentukan, ini menandai direktori tempat penampung yang diperbarui sepenuhnya terisi sededih sehingga akses di masa mendatang ke dalamnya akan ditangani oleh platform tanpa panggilan balik ke penyedia sinkronisasi.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY	FileIdentity dan FileIdentityLength diabaikan dan platform akan menghapus blob identitas file yang ada pada tempat penampung setelah panggilan pembaruan berhasil.
CF_UPDATE_FLAG_CLEAR_IN_SYNC	Platform menandai tempat penampung sebagai tidak sinkron setelah operasi tempat penampung pembaruan berhasil.
CF_UPDATE_FLAG_REMOVE_PROPERTY	Platform ini menghapus semua properti ekstrinsik yang ada pada tempat penampung.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA	Platform meneruskan CF_FS_METADATA ke sistem file tanpa pemfilteran; jika tidak, platform melompati pengaturan bidang apa pun yang nilainya adalah `0`.
CF_UPDATE_FLAG_ALWAYS_FULL	Efektif hanya pada file tempat penampung. Ketika ditentukan, tempat penampung yang akan diperbarui ditandai selalu penuh. Setelah terhidrasi, setiap upaya untuk melakukan dehidrasi file tempat penampung seperti itu akan gagal dengan kode kesalahan ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_UPDATE_FLAG_ALLOW_PARTIAL	Efektif hanya pada file tempat penampung. Ketika ditentukan, status selalu penuh pada file tempat penampung, jika ada, dibersihkan sehingga memungkinkannya untuk didehidrasi lagi. Tidak valid untuk menentukan bendera ini bersama dengan CF_UPDATE_FLAG_ALWAYS_FULL dan kode kesalahan ERROR_CLOUD_FILE_INVALID_REQUEST akan dikembalikan sebagai hasilnya.

[in, out, optional] UpdateUsn

Pada input, UpdateUsn menginstruksikan platform untuk hanya melakukan pembaruan jika file masih memiliki nilai USN yang sama dengan yang diteruskan. Ini melayani tujuan yang sama dengan CF_UPDATE_FLAG_VERIFY_IN_SYNC tetapi juga mencakup perubahan metadata lokal. Meneruskan pointer ke nilai USN pada 0 input sama dengan meneruskan NULL pointer.

Saat kembali, UpdateUsn menerima nilai USN akhir setelah tindakan pembaruan dilakukan.

[in, out, optional] Overlapped

Ketika ditentukan dan dikombinasikan dengan FileHandle asinkron, Tumpang tindih memungkinkan platform untuk melakukan panggilan CfUpdatePlaceholder secara asinkron. Lihat Keterangan untuk detail selengkapnya.

Jika tidak ditentukan, platform akan melakukan panggilan API secara sinkron, terlepas dari bagaimana handel dibuat.

Nilai kembali

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

Keterangan

Untuk memperbarui tempat penampung:

Tempat penampung yang akan diperbarui harus terkandung dalam pohon akar sinkronisasi terdaftar; itu bisa menjadi direktori akar sinkronisasi itu sendiri, atau direktori turunan apa pun; jika tidak, panggilan akan gagal dengan HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
Jika dehidrasi diminta, akar sinkronisasi harus terdaftar dengan kebijakan hidrasi valid yang tidak CF_HYDRATION_POLICY_ALWAYS_FULL; jika tidak, panggilan akan gagal dengan HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
Jika dehidrasi diminta, tempat penampung tidak boleh disematkan secara lokal atau panggilan akan gagal dengan HRESULT(ERROR_CLOUD_FILE_PINNED).
Jika dehidrasi diminta, tempat penampung harus sinkron atau panggilan akan gagal dengan HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
Pemanggil harus memiliki akses WRITE_DATA atau WRITE_DAC ke tempat penampung yang akan diperbarui. Jika tidak, operasi akan gagal dengan HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

Jika API mengembalikan HRESULT_FROM_WIN32(ERROR_IO_PENDING) saat menggunakan Tumpang Tindih secara asinkron, pemanggil kemudian dapat menunggu menggunakan GetOverlappedResult.

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

CfOpenFileWithOplock

CF_UPDATE_FLAGS

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2023-03-28