Fungsi GetGPOListW (userenv.h)

Fungsi GetGPOList mengambil daftar GPO untuk pengguna atau komputer yang ditentukan. Fungsi ini dapat dipanggil dengan dua cara: pertama, Anda dapat menggunakan token untuk pengguna atau komputer, atau, kedua, Anda dapat menggunakan nama pengguna atau komputer dan nama pengendali domain.

Sintaksis

USERENVAPI BOOL GetGPOListW(
  [in]  HANDLE                hToken,
  [in]  LPCWSTR               lpName,
  [in]  LPCWSTR               lpHostName,
  [in]  LPCWSTR               lpComputerName,
  [in]  DWORD                 dwFlags,
  [out] PGROUP_POLICY_OBJECTW *pGPOList
);

Parameter

[in] hToken

Token untuk pengguna atau komputer, dikembalikan dariLogonUser , createRestrictedToken, duplikatToken, openProcessToken, atau fungsi OpenThreadToken. Token ini harus memiliki akses TOKEN_IMPERSONATE dan TOKEN_QUERY. Untuk informasi selengkapnya, lihat Hak Akses untuk Objek Access-Token dan bagian Keterangan berikut.

Jika parameter ini null, Anda harus menyediakan nilai untuk parameter lpName dan lpHostName.

[in] lpName

Penunjuk ke nama pengguna atau komputer, dalam format nama khusus yang sepenuhnya memenuhi syarat (misalnya, "CN=pengguna, OU= pengguna, DC=contoso, DC=com").

Jika parameter hToken tidak null, parameter ini harus NULL.

[in] lpHostName

Nama domain DNS (lebih disukai) atau nama pengendali domain. Nama pengendali domain dapat diambil menggunakan fungsi DsGetDcName, menentukan DS_DIRECTORY_SERVICE_REQUIRED dalam parameter bendera .

Jika parameter hToken tidak null, parameter ini harus NULL.

[in] lpComputerName

Penunjuk ke nama komputer yang digunakan untuk menentukan lokasi situs. Format nama adalah "\\computer_name". Jika parameter ini null, nama komputer lokal digunakan.

[in] dwFlags

Nilai yang menentukan bendera tambahan yang digunakan untuk mengontrol pengambilan informasi. Jika Anda menentukan GPO_LIST_FLAG_MACHINE, fungsi mengambil informasi kebijakan untuk komputer. Jika Anda tidak menentukan GPO_LIST_FLAG_MACHINE, fungsi mengambil informasi kebijakan untuk pengguna.

Jika Anda menentukan GPO_LIST_FLAG_SITEONLY fungsi hanya mengembalikan informasi situs untuk komputer atau pengguna.

[out] pGPOList

Pointer yang menerima daftar struktur GPO. Untuk informasi selengkapnya, lihat GROUP_POLICY_OBJECT.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

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

Komentar

Fungsi GetGPOList dimaksudkan untuk digunakan oleh layanan yang bertindak atas nama pengguna atau komputer. Layanan memanggil fungsi ini untuk mendapatkan daftar GPO, lalu memeriksa setiap GPO untuk kebijakan khusus layanan.

Memanggil fungsi ini dengan token menyediakan daftar yang paling akurat. Sistem dapat melakukan pemeriksaan akses untuk pengguna atau komputer. Memanggil fungsi ini dengan nama pengguna atau komputer dan nama pengendali domain lebih cepat daripada memanggilnya dengan token. Namun, jika token tidak ditentukan, sistem menggunakan akses keamanan pemanggil, yang berarti bahwa daftar mungkin tidak benar sepenuhnya untuk pengguna atau komputer yang dimaksudkan.

Untuk mendapatkan daftar GPO yang paling akurat untuk komputer saat memanggil GetGPOList, pemanggil harus memiliki akses baca ke setiap unit organisasi dan situs di domain komputer, dan juga membaca dan menerapkan akses Kebijakan Grup ke semua GPO yang ditautkan ke situs, domain, atau OU domain tersebut. Contoh pemanggil adalah layanan yang berjalan di komputer yang namanya ditentukan dalam parameter lpName. Metode alternatif untuk mendapatkan daftar GPO adalah dengan memanggil metode RsopCreateSession dari RsopPlanningModeProvider kelas WMI. Metode ini dapat menghasilkan data kebijakan yang dihasilkan untuk komputer atau akun pengguna dalam skenario hipotetis.

Panggil fungsi FreeGPOList untuk membebaskan daftar GPO setelah Anda selesai memprosesnya.

Umumnya, Anda harus memanggil GetGPOList dengan token saat mengambil daftar GPO untuk pengguna seperti yang ditunjukkan dalam contoh kode berikut.

LPGROUP_POLICY_OBJECT  pGPOList;
      if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
      {
//        Perform processing here. 
//
//        Free the GPO list when you finish processing.
          FreeGPOList (pGPOList);
      }

Biasanya, untuk mengambil daftar GPO untuk komputer, Anda dapat memanggil GetGPOList dengan nama komputer dan nama pengendali domain seperti yang ditunjukkan dalam cuplikan kode berikut.

LPGROUP_POLICY_OBJECT  pGPOList;
      if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName, GPO_LIST_FLAG_MACHINE, &pGPOList))
      {
//        Perform processing here. 
//
//        Free the GPO list when you finish processing.
          FreeGPOList (pGPOList);
      }

Untuk mengambil daftar GPO yang diterapkan untuk pengguna atau komputer dan ekstensi tertentu, panggil fungsi GetAppliedGPOList.

Catatan

Header userenv.h mendefinisikan GetGPOList sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosem 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 Vista
server minimum yang didukung	Windows Server 2008
Platform Target	Windows
Header	userenv.h
Pustaka	Userenv.lib
DLL	Userenv.dll

Lihat juga

DsGetDcName

FreeGPOList

GROUP_POLICY_OBJECT

Fungsi Kebijakan Grup

Gambaran Umum Kebijakan Grup