Fungsi AdjustTokenGroups (securitybaseapi.h)

Artikel
03/15/2023

Fungsi AdjustTokenGroups memungkinkan atau menonaktifkan grup yang sudah ada dalam token akses yang ditentukan. Akses ke TOKEN_ADJUST_GROUPS diperlukan untuk mengaktifkan atau menonaktifkan grup dalam token akses.

Sintaks

BOOL AdjustTokenGroups(
  [in]            HANDLE        TokenHandle,
  [in]            BOOL          ResetToDefault,
  [in, optional]  PTOKEN_GROUPS NewState,
  [in]            DWORD         BufferLength,
  [out, optional] PTOKEN_GROUPS PreviousState,
  [out, optional] PDWORD        ReturnLength
);

Parameter

[in] TokenHandle

Handel ke token akses yang berisi grup yang akan diaktifkan atau dinonaktifkan. Handel harus memiliki akses TOKEN_ADJUST_GROUPS ke token. Jika parameter PreviousState bukan NULL, handel juga harus memiliki akses TOKEN_QUERY.

[in] ResetToDefault

Nilai Boolean yang menunjukkan apakah grup akan diatur ke status default yang diaktifkan dan dinonaktifkan. Jika nilai ini TRUE, grup diatur ke status defaultnya dan parameter NewState diabaikan. Jika nilai ini FALSE, grup diatur sesuai dengan informasi yang diarahkan oleh parameter NewState .

[in, optional] NewState

Penunjuk ke struktur TOKEN_GROUPS yang berisi grup yang akan diaktifkan atau dinonaktifkan. Jika parameter ResetToDefaultadalah FALSE, fungsi mengatur setiap grup ke nilai atribut SE_GROUP_ENABLED grup tersebut dalam struktur TOKEN_GROUPS . Jika ResetToDefaultTRUE, parameter ini diabaikan.

[in] BufferLength

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 menerima struktur TOKEN_GROUPS yang berisi status sebelumnya dari grup apa pun yang dimodifikasi fungsi. Artinya, jika grup telah dimodifikasi oleh fungsi ini, grup dan status sebelumnya terkandung dalam struktur TOKEN_GROUPS yang direferensikan oleh PreviousState. Jika anggota GroupCountdari TOKEN_GROUPS adalah nol, maka tidak ada grup yang diubah oleh fungsi ini. Parameter ini bisa NULL.

Jika buffer ditentukan tetapi tidak berisi cukup ruang untuk menerima daftar lengkap grup yang dimodifikasi, tidak ada status grup yang diubah dan fungsi gagal. Dalam hal ini, fungsi mengatur variabel yang ditunjukkan oleh parameter ReturnLength ke jumlah byte yang diperlukan untuk menyimpan daftar lengkap grup yang dimodifikasi.

[out, optional] ReturnLength

Penunjuk ke variabel yang menerima jumlah byte aktual yang diperlukan untuk buffer yang diarahkan oleh parameter PreviousState . Parameter ini dapat berupa NULL dan diabaikan jika PreviousState adalah NULL.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Keterangan

Informasi yang diambil dalam parameter PreviousState diformat sebagai struktur TOKEN_GROUPS . Ini berarti penunjuk ke buffer dapat diteruskan sebagai parameter NewState dalam panggilan berikutnya ke fungsi AdjustTokenGroups , memulihkan status asli grup.

Parameter NewState dapat mencantumkan grup yang akan diubah yang tidak ada dalam token akses. Ini tidak memengaruhi modifikasi grup yang berhasil dalam token.

Fungsi AdjustTokenGroups tidak dapat menonaktifkan grup dengan atribut SE_GROUP_MANDATORY dalam struktur TOKEN_GROUPS . Gunakan CreateRestrictedToken sebagai gantinya.

Anda tidak dapat mengaktifkan grup yang memiliki atribut SE_GROUP_USE_FOR_DENY_ONLY.

Persyaratan


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