Fungsi SetEntriesInAclA (aclapi.h)

Artikel
11/20/2024

Fungsi SetEntriesInAcl membuat daftar kontrol akses baru (ACL) dengan menggabungkan kontrol akses baru atau informasi kontrol audit ke dalam struktur ACL yang ada.

Sintaksis

DWORD SetEntriesInAclA(
  [in]           ULONG              cCountOfExplicitEntries,
  [in, optional] PEXPLICIT_ACCESS_A pListOfExplicitEntries,
  [in, optional] PACL               OldAcl,
  [out]          PACL               *NewAcl
);

Parameter

[in] cCountOfExplicitEntries

Jumlah struktur EXPLICIT_ACCESS dalam array pListOfExplicitEntries .

[in, optional] pListOfExplicitEntries

Penunjuk ke array struktur EXPLICIT_ACCESS yang menjelaskan informasi kontrol akses untuk digabungkan ke ACL yang ada.

[in, optional] OldAcl

Penunjuk ke ACL yang ada. Parameter ini dapat null, dalam hal ini, fungsi membuat ACL baru berdasarkan entri EXPLICIT_ACCESS.

[out] NewAcl

Penunjuk ke variabel yang menerima penunjuk ke ACL baru. Jika fungsi berhasil, Anda harus memanggil fungsi LocalFree untuk membebaskan buffer yang dikembalikan.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan ERROR_SUCCESS.

Jika fungsi gagal, fungsi mengembalikan kode kesalahan bukan nol yang ditentukan dalam WinError.h.

Komentar

Setiap entri dalam array struktur EXPLICIT_ACCESS menentukan kontrol akses atau informasi kontrol audit untuk wali yang ditentukan. Wali dapat menjadi pengguna, grup, atau nilai pengidentifikasi keamanan (SID) lainnya, seperti pengidentifikasi masuk atau jenis masuk (misalnya, layanan Windows atau pekerjaan batch). Anda dapat menggunakan nama atau SID untuk mengidentifikasi wali amanat.

Anda dapat menggunakan fungsi SetEntriesInAcl untuk mengubah daftar entri kontrol akses (ACE) dalam daftar kontrol akses diskresi (DACL) atau daftar kontrol akses sistem (SACL). Perhatikan bahwa SetEntriesInAcl tidak mencegah Anda mencampur kontrol akses dan informasi kontrol audit dalamACL yang sama; namun, ACL yang dihasilkan akan berisi entri yang tidak berarti.

Untuk DACL, grfAccessMode anggota struktur EXPLICIT_ACCESS menentukan apakah akan mengizinkan, menolak, atau mencabut hak akses bagi wali amanat. Anggota ini dapat menentukan salah satu nilai berikut:

GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS

Untuk informasi tentang nilai-nilai ini, lihat ACCESS_MODE.

Fungsi SetEntriesInAcl menempatkan ACE baru yang ditolak akses di awal daftar ACE untukACL baru. Fungsi ini menempatkan ACE baru yang diizinkan akses tepat sebelum ACE yang diizinkan akses yang ada.

Untuk SACL, anggota grfAccessMode dari struktur EXPLICIT_ACCESS dapat menentukan nilai berikut:

REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE dan SET_AUDIT_SUCCESS dapat digabungkan. Untuk informasi tentang nilai-nilai ini, lihat ACCESS_MODE.

Fungsi SetEntriesInAcl menempatkan ACL audit sistem baru di awal daftar ACE untuk ACL baru.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Memodifikasi ACL Objek atau Membuat Deskriptor Keamanan untuk Objek Baru atau Mengambil Kepemilikan Objek.

Nota

Header aclapi.h mendefinisikan SetEntriesInAcl sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praproscesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	aclapi.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll