Fungsi AddAce (securitybaseapi.h)

Artikel
03/01/2024

Fungsi AddAce menambahkan satu atau beberapa entri kontrol akses (ACE) ke daftar kontrol akses (ACL) tertentu.

Sintaks

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Parameter

[in, out] pAcl

Penunjuk ke ACL. Fungsi ini menambahkan ACE ke ACL ini.

[in] dwAceRevision

Menentukan tingkat revisi ACL yang sedang dimodifikasi.

Nilai ini dapat ACL_REVISION atau ACL_REVISION_DS. Gunakan ACL_REVISION_DS jika ACL berisi ACE khusus objek. Nilai ini harus kompatibel dengan bidang AceType dari semua ACE di pAceList. Jika tidak, fungsi akan gagal dan mengatur kesalahan terakhir ke ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Menentukan posisi dalam daftar ACE ACL untuk menambahkan ACE baru. Nilai nol menyisipkan ACE di awal daftar. Nilai MAXDWORD menambahkan ACE ke akhir daftar.

[in] pAceList

Penunjuk ke daftar satu atau beberapa ACE yang akan ditambahkan ke ACL yang ditentukan. ACE dalam daftar harus disimpan secara berdampingan.

[in] nAceListLength

Menentukan ukuran, dalam byte, dari buffer input yang diacu oleh parameter pAceList .

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Berikut ini adalah kemungkinan nilai kesalahan.

Menampilkan kode	Deskripsi
ERROR_INSUFFICIENT_BUFFER	ACE baru tidak cocok dengan ACL. Buffer ACL yang lebih besar diperlukan.
ERROR_INVALID_PARAMETER	ACL yang ditentukan tidak terbentuk dengan benar.
ERROR_SUCCESS	ACE berhasil ditambahkan.

Keterangan

Aplikasi sering menggunakan fungsi FindFirstFreeAce dan GetAce saat menggunakan fungsi AddAce untuk memanipulasi ACL. Selain itu, struktur ACL_SIZE_INFORMATION yang diambil oleh fungsi GetAclInformation berisi ukuran ACL dan jumlah ACE yang dikandungnya.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Memulai Proses Klien Interaktif.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	securitybaseapi.h (termasuk Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll