Fungsi BuildSecurityDescriptorA (aclapi.h)

Artikel
02/23/2024

Fungsi BuildSecurityDescriptor mengalokasikan dan menginisialisasi deskriptor keamanan baru. Fungsi ini dapat menginisialisasi deskriptor keamanan baru dengan menggabungkan informasi keamanan tertentu dengan informasi dalam deskriptor keamanan yang ada. Jika Anda tidak menentukan deskriptor keamanan yang ada, fungsi ini menginisialisasi deskriptor keamanan baru berdasarkan informasi keamanan yang ditentukan.

Fungsi BuildSecurityDescriptor membuat deskriptor keamanan relatif mandiri. Format relatif mandiri membuat deskriptor keamanan cocok untuk menyimpan dalam aliran.

Sintaks

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

Parameter

[in, optional] pOwner

Penunjuk ke struktur TRUSTEE yang mengidentifikasi pemilik untuk deskriptor keamanan baru. Jika struktur menggunakan formulir TRUSTEE_IS_NAME, BuildSecurityDescriptor mencari pengidentifikasi keamanan (SID) yang terkait dengan nama wali yang ditentukan.

Jika parameter ini NULL, fungsi menggunakan SID pemilik dari deskriptor keamanan asli yang ditunjukkan oleh pOldSD. Jika pOldSDADALAH NULL, atau jika pemilik SID di pOldSDADALAH NULL, SID pemilik adalah NULL dalam deskriptor keamanan baru.

[in, optional] pGroup

Penunjuk ke struktur TRUSTEE yang mengidentifikasi SID grup utama untuk deskriptor keamanan baru. Jika struktur menggunakan formulir TRUSTEE_IS_NAME, BuildSecurityDescriptor mencari SID yang terkait dengan nama wali yang ditentukan.

Jika parameter ini NULL, fungsi menggunakan SID grup dari deskriptor keamanan asli yang ditunjukkan oleh pOldSD. Jika pOldSDADALAH NULL, atau jika grup SID di pOldSDNULL, grup SID adalah NULL dalam deskriptor keamanan baru.

[in] cCountOfAccessEntries

Jumlah struktur EXPLICIT_ACCESS dalam array pListOfAccessEntries .

[in, optional] pListOfAccessEntries

Penunjuk ke array struktur EXPLICIT_ACCESS yang menjelaskan informasi kontrol akses untuk daftar kontrol akses diskresi (DACL) deskriptor keamanan baru. Fungsi ini membuat DACL baru dengan menggabungkan informasi dalam array dengan DACL di pOldSD, jika ada. Jika pOldSDadalah NULL, atau jika DACL di pOldSDADALAH NULL, fungsi membuat DACL baru hanya berdasarkan informasi dalam array. Untuk deskripsi aturan untuk membuat ACL dari array struktur EXPLICIT_ACCESS , lihat fungsi SetEntriesInAcl .

Jika pListOfAccessEntriesADALAH NULL, deskriptor keamanan baru mendapatkan DACL dari pOldSD. Dalam hal ini, jika pOldSDadalah NULL, atau jika DACL di pOldSDNULL, DACL baru adalah NULL.

[in] cCountOfAuditEntries

Jumlah struktur EXPLICIT_ACCESS dalam array pListOfAuditEntries .

[in, optional] pListOfAuditEntries

Penunjuk ke array struktur EXPLICIT_ACCESS yang menjelaskan informasi kontrol audit untuk SACL deskriptor keamanan baru. Fungsi ini membuat SACL baru dengan menggabungkan informasi dalam array dengan SACL di pOldSD, jika ada. Jika pOldSDadalah NULL, atau SACL di pOldSD adalah NULL, fungsi membuat SACL baru hanya berdasarkan informasi dalam array.

Jika pListOfAuditEntriesADALAH NULL, deskriptor keamanan baru mendapatkan SACL dari pOldSD. Dalam hal ini, jika pOldSDADALAH NULL, atau SACL di pOldSDADALAH NULL, SACL baru adalah NULL.

[in, optional] pOldSD

Penunjuk ke struktur SECURITY_DESCRIPTOR relatif mandiri yang ada dan informasi keamanan terkait. Fungsi ini membangun deskriptor keamanan baru dengan menggabungkan informasi pemilik, grup, kontrol akses, dan kontrol audit yang ditentukan dengan informasi dalam deskriptor keamanan ini. Parameter ini bisa NULL.

[out] pSizeNewSD

Penunjuk ke variabel yang menerima ukuran, dalam byte, dari deskriptor keamanan.

[out] pNewSD

Penunjuk ke variabel yang menerima penunjuk ke deskriptor keamanan baru. Fungsi ini mengalokasikan memori untuk deskriptor keamanan baru. Anda harus memanggil fungsi LocalFree untuk membebaskan buffer yang dikembalikan.

Nilai kembali

Jika fungsi berhasil, fungsi akan mengembalikan ERROR_SUCCESS.

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

Keterangan

Fungsi BuildSecurityDescriptor ditujukan untuk server tepercaya yang mengimplementasikan atau mengekspos keamanan pada objek mereka sendiri. Fungsi ini menggunakan deskriptor keamanan relatif mandiri yang cocok untuk diserialisasikan ke dalam aliran dan menyimpan ke disk, seperti yang mungkin diperlukan server tepercaya.

Catatan

Header aclapi.h mendefinisikan BuildSecurityDescriptor sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	aclapi.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll