Bagikan melalui

Fungsi TreeSetNamedSecurityInfoA (aclapi.h)

  • Artikel

Versi fungsi ini tidak didukung. Versi karakter yang luas dari fungsi ini, TreeSetNamedSecurityInfoW, didukung.

Sintaks

DWORD TreeSetNamedSecurityInfoA(
  [in]           LPSTR                pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 pOwner,
  [in, optional] PSID                 pGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl,
  [in]           DWORD                dwAction,
  [in]           FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

Parameter

[in] pObjectName

Penunjuk ke string yang dihentikan null yang menentukan nama objek simpul akar untuk objek yang akan menerima informasi keamanan yang diperbarui. Objek yang didukung adalah kunci registri dan objek file. Untuk deskripsi format string untuk berbagai jenis objek, lihat SE_OBJECT_TYPE.

[in] ObjectType

Nilai enumerasi SE_OBJECT_TYPE yang menunjukkan jenis objek yang dinamai oleh parameter pObjectName . Nilai yang didukung masing-masing SE_REGISTRY_KEY dan SE_FILE_OBJECT, untuk kunci registri dan objek file.

[in] SecurityInfo

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

[in, optional] pOwner

Penunjuk ke struktur SID yang mengidentifikasi pemilik objek. SID harus salah satu yang dapat ditetapkan sebagai SID pemilik pendeskripsi keamanan. Parameter SecurityInfo harus menyertakan bendera OWNER_SECURITY_INFORMATION. Untuk mengatur pemilik, pemanggil harus memiliki akses WRITE_OWNER ke setiap objek, termasuk objek akar. Jika Anda tidak mengatur SID pemilik, parameter ini bisa NULL.

[in, optional] pGroup

Penunjuk ke struktur SID yang mengidentifikasi grup utama objek. Parameter SecurityInfo harus menyertakan bendera GROUP_SECURITY_INFORMATION. Untuk mengatur grup, pemanggil harus memiliki akses WRITE_OWNER ke setiap objek, termasuk objek akar. Jika Anda tidak mengatur SID grup utama, parameter ini bisa NULL.

[in, optional] pDacl

Penunjuk ke struktur daftar kontrol akses (ACL) yang mewakili DACL baru untuk objek yang direset. Parameter SecurityInfo harus menyertakan bendera DACL_SECURITY_INFORMATION. Pemanggil harus memiliki akses READ_CONTROL dan WRITE_DAC ke setiap objek, termasuk objek akar. Jika Anda tidak mengatur DACL, parameter ini bisa NULL.

[in, optional] pSacl

Penunjuk ke struktur ACL yang mewakili SACL baru untuk objek yang direset. Parameter SecurityInfo harus menyertakan salah satu bendera berikut: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION, atau BACKUP_SECURITY_INFORMATION. Jika mengatur SACL_SECURITY_INFORMATION atau SCOPE_SECURITY_INFORMATION, pemanggil harus mengaktifkan hak istimewa SE_SECURITY_NAME. Jika Anda tidak mengatur SACL, parameter ini bisa NULL.

[in] dwAction

Menentukan perilaku fungsi ini. Ini harus diatur ke salah satu nilai berikut, yang ditentukan dalam AccCtrl.h.

Nilai Makna
TREE_SEC_INFO_SET
0x00000001
 Informasi keamanan diatur pada objek yang ditentukan oleh parameter pObjectName dan pohon objek anak dari objek tersebut. Jika ACL ditentukan dalam parameter pDacl atau pSacl , deskriptor keamanan dikaitkan dengan objek . Deskriptor keamanan disebarkan ke pohon objek anak berdasarkan properti warisannya.
TREE_SEC_INFO_RESET
0x00000002
 Informasi keamanan diatur ulang pada objek yang ditentukan oleh parameter pObjectName dan pohon objek anak dari objek tersebut. Informasi keamanan yang ada dihapus dari semua objek di pohon.

Jika ada objek di pohon yang tidak memberikan izin yang sesuai kepada pemanggil untuk memodifikasi pendeskripsi keamanan pada objek, maka penyebaran informasi keamanan pada simpul pohon tertentu dan objeknya dilewati. Operasi berlanjut pada pohon lainnya di bawah objek yang ditentukan oleh parameter pObjectName .
TREE_SEC_INFO_RESET_KEEP_EXPLICIT
0x00000003
 Informasi keamanan diatur ulang pada objek yang ditentukan oleh parameter pObjectName dan pohon objek anak dari objek tersebut. Informasi keamanan yang diwariskan yang ada dihapus dari semua objek di pohon. Informasi keamanan yang secara eksplisit diatur pada objek di pohon tidak berubah.

Jika ada objek di pohon yang tidak memberikan izin yang sesuai kepada pemanggil untuk memodifikasi pendeskripsi keamanan pada objek, maka penyebaran informasi keamanan pada simpul pohon tertentu dan objeknya dilewati. Operasi berlanjut pada pohon lainnya di bawah objek yang ditentukan oleh parameter pObjectName .

[in] fnProgress

Penunjuk ke fungsi yang digunakan untuk melacak kemajuan fungsi TreeSetNamedSecurityInfo . Prototipe fungsi kemajuan adalah:

#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

typedef VOID (*FN_PROGRESS) (
  IN LPWSTR pObjectName,              // Name of object just processed
  IN DWORD Status,                    // Status of operation on object
  IN OUT PPROG_INVOKE_SETTING
                      pInvokeSetting, // When to set
  IN PVOID Args,                      // Caller specific data
  IN BOOL SecuritySet                 // Whether security was set
);

Fungsi kemajuan memberi pemanggil informasi kemajuan dan kesalahan ketika simpul diproses. Pemanggil menentukan fungsi kemajuan di fnProgress, dan selama operasi pohon, TreeSetNamedSecurityInfo meneruskan nama objek terakhir yang diproses, status kesalahan operasi tersebut, dan nilai PROG_INVOKE_SETTING saat ini. Pemanggil dapat mengubah nilai PROG_INVOKE_SETTING dengan menggunakan pInvokeSetting.

Jika tidak ada fungsi kemajuan yang akan digunakan, atur parameter ini ke NULL.

[in] ProgressInvokeSetting

Nilai enumerasi PROG_INVOKE_SETTING yang menentukan pengaturan awal untuk fungsi kemajuan.

[in, optional] Args

Penunjuk ke VOID untuk argumen fungsi kemajuan yang ditentukan oleh pemanggil.

Nilai kembali

Jika fungsi berhasil, fungsi akan mengembalikan ERROR_SUCCESS.

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

Keterangan

Mengatur pemilik NULL , grup, DACL, atau SACL tidak didukung oleh fungsi ini.

Jika penelepon tidak berisi hak istimewa dan izin yang tepat untuk mendukung pembaruan pemilik, grup, DACL, dan SACL yang diminta, maka tidak ada pembaruan yang dilakukan.

Fungsi ini menyediakan fungsionalitas yang sama dengan fungsi SetNamedSecurityInfo saat nilai parameter dwAction diatur ke TREE_SEC_INFO_SET, nilai parameter ProgressInvokeSetting diatur ke ProgressInvokePrePostError, dan fungsi yang ditunjukkan oleh parameter fnProgress menetapkan nilai parameter pInvokeSetting-nya ke ProgressInvokePrePostError.

Fungsi ini mirip dengan fungsi TreeResetNamedSecurityInfo :

  • Jika parameter dwActiontreeSetNamedSecurityInfo diatur ke TREE_SEC_INFO_RESET_KEEP_EXPLICIT, maka fungsinya setara dengan TreeResetNamedSecurityInfo dengan parameter KeepExplicit diatur ke TRUE.
  • Jika parameter dwActiontreeSetNamedSecurityInfo diatur ke TREE_SEC_INFO_RESET, maka fungsinya setara dengan TreeResetNamedSecurityInfo dengan parameter KeepExplicit diatur ke FALSE.

Catatan

Header aclapi.h mendefinisikan TreeSetNamedSecurityInfo 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 Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Target Platform Windows
Header aclapi.h
Pustaka Advapi32.lib
DLL Advapi32.dll