Fungsi GetNamedSecurityInfoA (aclapi.h)

Artikel
2024-11-20

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

Sintaksis

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 bernama dengan parameter pObjectName.

[in] SecurityInfo

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

[out, optional] ppsidOwner

Penunjuk ke variabel yang menerima pointer ke SID pemilik di deskriptor keamanan dikembalikan dalam 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 dapat 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 deskriptor keamanan tidak memiliki SID grup. Penunjuk yang dikembalikan hanya valid jika Anda mengatur bendera GROUP_SECURITY_INFORMATION. Selain itu, parameter ini dapat NULL jika Anda tidak memerlukan SID grup.

[out, optional] ppDacl

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

[out, optional] ppSacl

Penunjuk ke variabel yang menerima penunjuk 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 dapat NULL jika Anda tidak memerlukan SACL.

[out, optional] ppSecurityDescriptor

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

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

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai pengembalian adalah kode kesalahan nonzero yang ditentukan dalam WinError.h.

Komentar

Jika salah satuppsidOwner , ppsidGroup, ppDacl, atau parameter ppSacl non-NULL, dan parameter SecurityInfo menentukan bahwa mereka diambil dari objek, parameter tersebut akan menunjuk ke parameter yang sesuai dalam deskriptor keamanan 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 pemanggil 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 mengaktifkan hak istimewa, lihat Berjalan dengan Hak Istimewa khusus.

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 di tunggu
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 Bagaimana DACL Mengontrol Akses ke Objek.

Contoh

Untuk contoh yang menggunakan GetNamedSecurityInfo, lihat Memodifikasi ACL Objek.

Nota

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

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