Fungsi InitializeAcl (securitybaseapi.h)

Artikel
03/13/2024

Fungsi InitializeAcl menginisialisasi struktur ACL baru.

Sintaks

BOOL InitializeAcl(
  [out] PACL  pAcl,
  [in]  DWORD nAclLength,
  [in]  DWORD dwAclRevision
);

Parameter

[out] pAcl

Penunjuk ke struktur ACL yang akan diinisialisasi oleh fungsi ini. Alokasikan memori untuk pAcl sebelum memanggil fungsi ini.

[in] nAclLength

Panjangnya, dalam byte, dari buffer yang diacu oleh parameter pAcl . Nilai ini harus cukup besar untuk berisi header ACL dan semua entri kontrol akses (ACE) yang akan disimpan dalam ACL. Selain itu, nilai ini harus selaras dengan DWORD. Untuk informasi selengkapnya tentang menghitung ukuran ACL, lihat Keterangan.

[in] dwAclRevision

Tingkat revisi struktur ACL yang sedang dibuat.

Nilai ini dapat ACL_REVISION atau ACL_REVISION_DS. Gunakan ACL_REVISION_DS jika daftar kontrol akses (ACL) mendukung ACE khusus objek.

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan bukan nol.

Jika fungsi gagal, fungsi akan mengembalikan nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi InitializeAcl membuat struktur ACL kosong; ACL tidak berisi ACE. Menerapkan ACL kosong ke objek menolak semua akses ke objek tersebut.

Ukuran awal ACL tergantung pada jumlah ACE yang Anda rencanakan untuk ditambahkan ke ACL sebelum Anda menggunakannya. Misalnya, jika ACL berisi ACE untuk pengguna dan grup, Anda akan menginisialisasi ACL berdasarkan dua ACL. Untuk detail tentang memodifikasi ACL yang sudah ada, lihat Memodifikasi ACL Objek.

Untuk menghitung ukuran awal ACL, tambahkan yang berikut ini bersama-sama, lalu ratakan hasilnya ke DWORD terdekat:

Ukuran struktur ACL .
Ukuran setiap struktur ACE yang akan dimuat ACL dikurangi anggota SidStart (DWORD) dari ACE.
Panjang SID yang akan dimuat oleh setiap ACE .

Contoh

Contoh berikut memanggil fungsi InitializeAcl . Ukuran ACL didasarkan pada tiga ACL akses izinkan. Sebagai opsi, Anda dapat menggunakan bahasa definisi deskriptor keamanan (SDDL) untuk membuat ACL. Untuk detailnya, lihat Membuat DACL.

Contohnya juga menghilangkan langkah untuk penyederhanaan. Untuk informasi selengkapnya, lihat contoh Mengambil Kepemilikan Objek . Anda harus memanggil fungsi FreeSid di akhir kode contoh karena memanggil fungsi AllocateAndInitializeSid .

#include <windows.h>
#include <Winbase.h>
#pragma comment(lib, "duser.lib")

#define NUM_OF_ACES 3

void main()
{
    PACL pAcl = NULL;
    DWORD cbAcl = 0;
    PSID psids[NUM_OF_ACES];

    // Allocate and initialize SIDs.
    // Step omitted - See Taking Object Ownership example.

    // Add the SID for each ACE to psids. 
    cbAcl = sizeof(ACL) + 
        ((sizeof(ACCESS_ALLOWED_ACE)) * NUM_OF_ACES);
    for (int i = 0; i < NUM_OF_ACES; i++)
    {
        cbAcl += GetLengthSid(psids[i]) - sizeof(DWORD);
    }

    // Align cbAcl to a DWORD.
    cbAcl = (cbAcl + (sizeof(DWORD) - 1)) & 0xfffffffc;

    pAcl = (ACL*)LocalAlloc(LPTR, cbAcl);
    if (pAcl)
    {
        if (InitializeAcl(pAcl, cbAcl, ACL_REVISION))
        {

            // Add the ACEs to the ACL.
            // Add the ACL to the object's security descriptor.
        }
        else
        {

            // Handle error.
        }
    }
    {

        // Handle error.
    }

    // Free pAcl when finished.
    // Call FreeSid when finished.
}

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