GetGPOListW 函式（userenv.h）

發行項
11/20/2024

GetGPOList 函式會擷取指定使用者或電腦的 GPO 清單。您可以透過兩種方式呼叫此函式：第一，您可以使用使用者或計算機的令牌，或第二種，您可以使用使用者或計算機的名稱和域控制器的名稱。

語法

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

參數

[in] hToken

使用者或計算機的令牌，從 LogonUser、CreateRestrictedToken、DuplicateToken、OpenProcessToken或 OpenThreadToken 函式傳回。此令牌必須具有 TOKEN_IMPERSONATE 和 TOKEN_QUERY 存取權。如需詳細資訊，請參閱 Access-Token 對象的訪問許可權和下列一節。

如果此參數 NULL，您必須提供 lpName 和 lpHostName 參數的值。

[in] lpName

使用者或計算機名稱的指標，格式為完整辨別名稱（例如，“CN=使用者，OU=使用者，DC=contoso，DC=com]。

如果 hToken 參數未 NULL，則此參數必須 NULL。

[in] lpHostName

DNS 功能變數名稱（慣用）或域控制器名稱。您可以使用 DsGetDcName 函式來擷取域控制器名稱，並在旗標參數中指定 DS_DIRECTORY_SERVICE_REQUIRED。

如果 hToken 參數未 NULL，則此參數必須 NULL。

[in] lpComputerName

用來判斷月臺位置之計算機名稱的指標。名稱的格式為 “\\computer_name”。如果此參數 NULL，則會使用本機計算機名稱。

[in] dwFlags

值，指定用來控制資訊擷取的其他旗標。如果您指定 GPO_LIST_FLAG_MACHINE，函式會擷取計算機的原則資訊。如果您未指定 GPO_LIST_FLAG_MACHINE，函式會擷取使用者的原則資訊。

如果您指定 GPO_LIST_FLAG_SITEONLY 函式只會傳回電腦或使用者的月臺資訊。

[out] pGPOList

接收 GPO 結構的指標。如需詳細資訊，請參閱 GROUP_POLICY_OBJECT。

傳回值

如果函式成功，則傳回值為非零值。

如果函式失敗，傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

GetGPOList 函式適用於代表使用者或電腦運作的服務。服務會呼叫此函式以取得 GPO 清單，然後檢查每個 GPO 是否有服務特定原則。

使用令牌呼叫此函式可提供最精確的清單。系統可以針對使用者或計算機執行存取檢查。使用使用者或計算機名稱呼叫此函式，而且域控制器名稱比使用令牌呼叫它更快。不過，如果未指定令牌，則系統會使用呼叫者的安全性存取權，這表示清單可能不適合預期的用戶或計算機。

若要在呼叫 GetGPOList時取得電腦最精確的 GPO 清單，呼叫端必須具有計算機網域中每個 OU 和網站的讀取許可權，並且讀取並套用組策略存取權，以連結至該網域的網站、網域或 OU 的所有 GPO。呼叫者的範例是在計算機上執行的服務，其名稱是在 lpName 參數中指定。取得 GPO 清單的替代方法是呼叫 RsopPlanningModeProvider WMI 類別的 RsopCreateSession 方法。方法可以在假設案例中產生計算機或用戶帳戶的結果原則數據。

呼叫 FreeGPOList 函式，以在您完成處理 GPO 清單時釋出 GPO 清單。

一般而言，當您擷取使用者的 GPO 清單時，應該使用令牌呼叫 GetGPOList，如下列程式代碼範例所示。

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);
      }

一般而言，若要擷取計算機的 GPO 清單，您可以使用電腦名稱和域控制器名稱呼叫 GetGPOList，如下列代碼段所示。

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);
      }

若要擷取針對特定使用者或計算機和擴充功能套用的 GPO 清單，請呼叫 getAppliedGPOList 函式。

注意

userenv.h 標頭會將 GetGPOList 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows Vista
支援的最低伺服器	Windows Server 2008
目標平臺	窗戶
標頭	userenv.h
連結庫	Userenv.lib
DLL	Userenv.dll