Fungsi GetNamedSecurityInfoA (aclapi.h)

Artikel
03/14/2023

Fungsi GetNamedSecurityInfo mengambil salinan deskriptor keamanan untuk objek yang ditentukan berdasarkan nama.

Sintaks

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parameter

[in] pObjectName

Penunjuk ke string yang dihentikan null yang menentukan nama objek untuk mengambil informasi keamanan. Untuk deskripsi format string untuk berbagai jenis objek, lihat SE_OBJECT_TYPE.

[in] ObjectType

Menentukan nilai dari enumerasi SE_OBJECT_TYPE yang menunjukkan jenis objek yang dinamai oleh parameter pObjectName .

[in] SecurityInfo

Sekumpulan bendera bit yang menunjukkan jenis informasi keamanan yang akan diambil. Parameter ini bisa menjadi kombinasi dari bendera bit SECURITY_INFORMATION .

[out, optional] ppsidOwner

Penunjuk ke variabel yang menerima pointer ke SID pemilik di deskriptor keamanan yang dikembalikan di ppSecurityDescriptor atau NULL jika deskriptor keamanan tidak memiliki SID pemilik. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera OWNER_SECURITY_INFORMATION. Selain itu, parameter ini bisa null jika Anda tidak memerlukan SID pemilik.

[out, optional] ppsidGroup

Penunjuk ke variabel yang menerima penunjuk ke SID grup utama di deskriptor keamanan yang dikembalikan atau NULL jika pendeskripsi keamanan tidak memiliki SID grup. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera GROUP_SECURITY_INFORMATION. Selain itu, parameter ini bisa NULL jika Anda tidak memerlukan SID grup.

[out, optional] ppDacl

Penunjuk ke variabel yang menerima pointer ke DACL di deskriptor keamanan yang dikembalikan atau NULL jika pendeskripsi keamanan tidak memiliki DACL. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera DACL_SECURITY_INFORMATION. Selain itu, parameter ini bisa NULL jika Anda tidak memerlukan DACL.

[out, optional] ppSacl

Penunjuk ke variabel yang menerima pointer ke SACL di deskriptor keamanan yang dikembalikan atau NULL jika deskriptor keamanan tidak memiliki SACL. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera SACL_SECURITY_INFORMATION. Selain itu, parameter ini bisa NULL jika Anda tidak memerlukan SACL.

[out, optional] ppSecurityDescriptor

Penunjuk ke variabel yang menerima penunjuk ke pendeskripsi keamanan objek. Setelah Anda selesai menggunakan penunjuk, bebaskan buffer yang dikembalikan dengan memanggil fungsi LocalFree .

Parameter ini diperlukan jika salah satu parameter ppsidOwner, ppsidGroup, ppDacl, atau ppSacl bukan NULL.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan bukan nol yang ditentukan dalam WinError.h.

Keterangan

Jika salah satu parameter ppsidOwner, ppsidGroup, ppDacl, atau ppSacl bukan NULL, dan parameter SecurityInfo menentukan bahwa parameter tersebut diambil dari objek , parameter tersebut akan menunjuk ke parameter yang sesuai dalam deskriptor keamanan yang dikembalikan dalam ppSecurityDescriptor. Jika deskriptor keamanan tidak berisi informasi yang diminta, parameter yang sesuai akan diatur ke NULL.

Untuk membaca pemilik, grup, atau DACL dari deskriptor keamanan objek, DACL objek harus memberikan akses READ_CONTROL ke pemanggil, atau penelepon harus menjadi pemilik objek.

Untuk membaca daftar kontrol akses sistem objek, hak istimewa SE_SECURITY_NAME harus diaktifkan untuk proses panggilan. Untuk informasi tentang implikasi keamanan untuk mengaktifkan hak istimewa, lihat Menjalankan dengan Hak Istimewa.

Anda dapat menggunakan fungsi GetNamedSecurityInfo dengan jenis objek berikut:

File atau direktori lokal atau jarak jauh pada sistem file NTFS
Printer lokal atau jarak jauh
Layanan Windows lokal atau jarak jauh
Berbagi jaringan
Kunci registri
Semaphores, peristiwa, mutex, dan timer yang dapat diantisipasi
Objek pemetaan file
Objek layanan direktori

Fungsi ini tidak menangani kondisi balapan. Jika utas Anda memanggil fungsi ini pada perkiraan waktu alur lain mengubah deskriptor keamanan objek, maka fungsi ini bisa gagal.

Fungsi ini mentransfer informasi dalam teks biasa. Informasi yang ditransfer oleh fungsi ini ditandatangani kecuali penandatanganan telah dimatikan untuk sistem, tetapi tidak ada enkripsi yang dilakukan.

Untuk informasi selengkapnya tentang mengontrol akses ke objek melalui akun pengguna, akun grup, atau sesi masuk, lihat Cara DACL Mengontrol Akses ke Objek.

Contoh

Untuk contoh yang menggunakan GetNamedSecurityInfo, lihat Memodifikasi ACL Objek.

Catatan

Header aclapi.h mendefinisikan GetNamedSecurityInfo 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 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	aclapi.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll