getGPOListA 函式 (userenv.h)

GetGPOList函式會擷取指定使用者或電腦的 GPO 清單。 您可以透過兩種方式呼叫此函式：首先，您可以使用使用者或電腦的權杖，或者，您也可以使用使用者或電腦的名稱和網域控制站的名稱。

語法

USERENVAPI BOOL GetGPOListA(
  [in]  HANDLE                hToken,
  [in]  LPCSTR                lpName,
  [in]  LPCSTR                lpHostName,
  [in]  LPCSTR                lpComputerName,
  [in]  DWORD                 dwFlags,
  [out] PGROUP_POLICY_OBJECTA *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

群組原則函式

群組原則概觀