Fungsi AdjustTokenPrivileges (securitybaseapi.h)

Artikel
03/15/2023

Fungsi AdjustTokenPrivileges memungkinkan atau menonaktifkan hak istimewa dalam token akses yang ditentukan. Mengaktifkan atau menonaktifkan hak istimewa dalam token akses memerlukan akses TOKEN_ADJUST_PRIVILEGES.

Sintaks

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

Parameter

[in] TokenHandle

Handel ke token akses yang berisi hak istimewa yang akan dimodifikasi. Handel harus memiliki akses TOKEN_ADJUST_PRIVILEGES ke token. Jika parameter PreviousState bukan NULL, handel juga harus memiliki akses TOKEN_QUERY.

[in] DisableAllPrivileges

Menentukan apakah fungsi menonaktifkan semua hak istimewa token. Jika nilai ini TRUE, fungsi menonaktifkan semua hak istimewa dan mengabaikan parameter NewState . Jika FALSE, fungsi memodifikasi hak istimewa berdasarkan informasi yang diarahkan oleh parameter NewState .

[in, optional] NewState

Penunjuk ke struktur TOKEN_PRIVILEGES yang menentukan array hak istimewa dan atributnya. Jika parameter DisableAllPrivilegesadalah FALSE, fungsi AdjustTokenPrivileges mengaktifkan, menonaktifkan, atau menghapus hak istimewa ini untuk token. Tabel berikut menjelaskan tindakan yang diambil oleh fungsi AdjustTokenPrivileges , berdasarkan atribut hak istimewa.

Nilai	Makna
SE_PRIVILEGE_ENABLED	Fungsi ini memungkinkan hak istimewa.
SE_PRIVILEGE_REMOVED	Hak istimewa dihapus dari daftar hak istimewa dalam token. Hak istimewa lain dalam daftar diurutkan ulang agar tetap berdekatan. SE_PRIVILEGE_REMOVED menggantikan SE_PRIVILEGE_ENABLED. Karena hak istimewa telah dihapus dari token, upaya untuk mengaktifkan kembali hak istimewa menghasilkan peringatan ERROR_NOT_ALL_ASSIGNED seolah-olah hak istimewa tidak pernah ada. Mencoba menghapus hak istimewa yang tidak ada dalam token menghasilkan ERROR_NOT_ALL_ASSIGNED dikembalikan. Pemeriksaan hak istimewa untuk hak istimewa yang dihapus menghasilkan STATUS_PRIVILEGE_NOT_HELD. Audit pemeriksaan hak istimewa yang gagal terjadi seperti biasa. Penghapusan hak istimewa tidak dapat diubah, sehingga nama hak istimewa yang dihapus tidak disertakan dalam parameter PreviousState setelah panggilan ke AdjustTokenPrivileges. Windows XP dengan SP1: Fungsi tidak dapat menghapus hak istimewa. Nilai ini tidak didukung.
Tidak ada	Fungsi menonaktifkan hak istimewa.

Nilai

Makna

SE_PRIVILEGE_ENABLED

Fungsi ini memungkinkan hak istimewa.

SE_PRIVILEGE_REMOVED

Hak istimewa dihapus dari daftar hak istimewa dalam token. Hak istimewa lain dalam daftar diurutkan ulang agar tetap berdekatan.

SE_PRIVILEGE_REMOVED menggantikan SE_PRIVILEGE_ENABLED.

Karena hak istimewa telah dihapus dari token, upaya untuk mengaktifkan kembali hak istimewa menghasilkan peringatan ERROR_NOT_ALL_ASSIGNED seolah-olah hak istimewa tidak pernah ada.

Mencoba menghapus hak istimewa yang tidak ada dalam token menghasilkan ERROR_NOT_ALL_ASSIGNED dikembalikan.

Pemeriksaan hak istimewa untuk hak istimewa yang dihapus menghasilkan STATUS_PRIVILEGE_NOT_HELD. Audit pemeriksaan hak istimewa yang gagal terjadi seperti biasa.

Penghapusan hak istimewa tidak dapat diubah, sehingga nama hak istimewa yang dihapus tidak disertakan dalam parameter PreviousState setelah panggilan ke AdjustTokenPrivileges.

Windows XP dengan SP1: Fungsi tidak dapat menghapus hak istimewa. Nilai ini tidak didukung.

Tidak ada

Fungsi menonaktifkan hak istimewa.

Jika DisableAllPrivilegesTRUE, fungsi akan mengabaikan parameter ini.

[in] BufferLength

Menentukan ukuran, dalam byte, dari buffer yang diarahkan oleh parameter PreviousState . Parameter ini bisa menjadi nol jika parameter PreviousState adalah NULL.

[out, optional] PreviousState

Penunjuk ke buffer yang diisi fungsi dengan struktur TOKEN_PRIVILEGES yang berisi status sebelumnya dari hak istimewa apa pun yang dimodifikasi fungsi. Artinya, jika hak istimewa telah dimodifikasi oleh fungsi ini, hak istimewa dan status sebelumnya terkandung dalam struktur TOKEN_PRIVILEGES yang direferensikan oleh PreviousState. Jika anggota PrivilegeCountdari TOKEN_PRIVILEGES adalah nol, maka tidak ada hak istimewa yang diubah oleh fungsi ini. Parameter ini bisa NULL.

Jika Anda menentukan buffer yang terlalu kecil untuk menerima daftar lengkap hak istimewa yang dimodifikasi, fungsi gagal dan tidak menyesuaikan hak istimewa apa pun. Dalam hal ini, fungsi mengatur variabel yang ditunjukkan oleh parameter ReturnLength ke jumlah byte yang diperlukan untuk menyimpan daftar lengkap hak istimewa yang dimodifikasi.

[out, optional] ReturnLength

Penunjuk ke variabel yang menerima ukuran yang diperlukan, dalam byte, dari buffer yang ditunjukkan oleh parameter PreviousState . Parameter ini bisa NULL jika PreviousState adalah NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol. Untuk menentukan apakah fungsi menyesuaikan semua hak istimewa yang ditentukan, panggil GetLastError, yang mengembalikan salah satu nilai berikut saat fungsi berhasil:

Menampilkan kode	Deskripsi
ERROR_SUCCESS	Fungsi menyesuaikan semua hak istimewa yang ditentukan.
ERROR_NOT_ALL_ASSIGNED	Token tidak memiliki satu atau beberapa hak istimewa yang ditentukan dalam parameter NewState . Fungsi dapat berhasil dengan nilai kesalahan ini meskipun tidak ada hak istimewa yang disesuaikan. Parameter PreviousState menunjukkan hak istimewa yang disesuaikan.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi AdjustTokenPrivileges tidak dapat menambahkan hak istimewa baru ke token akses. Ini hanya dapat mengaktifkan atau menonaktifkan hak istimewa token yang ada. Untuk menentukan hak istimewa token, panggil fungsi GetTokenInformation .

Parameter NewState dapat menentukan hak istimewa yang tidak dimiliki token, tanpa menyebabkan fungsi gagal. Dalam hal ini, fungsi menyesuaikan hak istimewa yang memang memiliki token dan mengabaikan hak istimewa lainnya sehingga fungsi berhasil. Panggil fungsi GetLastError untuk menentukan apakah fungsi menyesuaikan semua hak istimewa yang ditentukan. Parameter PreviousState menunjukkan hak istimewa yang disesuaikan.

Parameter PreviousState mengambil struktur TOKEN_PRIVILEGES yang berisi status asli hak istimewa yang disesuaikan. Untuk memulihkan status asli, lewati penunjuk PreviousState sebagai parameter NewState dalam panggilan berikutnya ke fungsi AdjustTokenPrivileges .

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Mengaktifkan dan Menonaktifkan Hak Istimewa.

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