getGPOListW 函式 (userenv.h)

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=user， OU=users， DC=contoso， DC=com”) 。

如果 hToken 參數不是 NULL，此參數必須是 NULL。

[in] lpHostName

DNS 功能變數名稱 (慣用) 或域控制器名稱。 您可以使用 DsGetDcName 函式擷取域控制器名稱，並在 flags 參數中指定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 方法。 方法可以在假設案例中為計算機或用戶帳戶產生結果原則數據。

當您完成處理 GPO 清單時，請呼叫 FreeGPOList 函式以釋出 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 函式。

規格需求

另請參閱

DsGetDcName

FreeGPOList

GROUP_POLICY_OBJECT

群組原則 函式

群組原則概觀