Функция GetGPOListA (userenv.h)

Статья
11/20/2024

Функция GetGPOList извлекает список объектов групповой политики для указанного пользователя или компьютера. Эта функция может вызываться двумя способами: во-первых, можно использовать маркер для пользователя или компьютера, а во-вторых, можно использовать имя пользователя или компьютера и имя контроллера домена.

Синтаксис

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 Rights for Access-Token Objects и в следующем разделе "Примечания".

Если этот параметр 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

Указатель, который получает список структур групповой политики. Дополнительные сведения см. в GROUP_POLICY_OBJECT.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение ненулевое.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Функция GetGPOList предназначена для использования службами от имени пользователя или компьютера. Служба вызывает эту функцию для получения списка объектов групповой политики, а затем проверяет каждый объект групповой политики для конкретной службы.

Вызов этой функции с маркером предоставляет самый точный список. Система может выполнять проверку доступа для пользователя или компьютера. Вызов этой функции с именем пользователя или компьютера и именем контроллера домена быстрее, чем вызов его маркером. Однако если маркер не указан, система использует доступ к вызывающей системе безопасности, что означает, что список может быть не полностью правильным для предполагаемого пользователя или компьютера.

Чтобы получить самый точный список объектов групповой политики для компьютера при вызове GetGPOList, вызывающий объект должен иметь доступ на чтение к каждому подразделению и сайту в домене компьютера, а также чтение и применение доступа к групповой политике ко всем объектам групповой политики, связанным с сайтами, доменами или подразделениями этого домена. Пример вызывающего объекта — служба, запущенная на компьютере, имя которого указано в параметре lpName. Альтернативный метод получения списка объектов групповой политики будет вызывать метод RsopCreateSession класса RsopPlanningModeProvider WMI. Этот метод может создавать результирующих данных политики для учетной записи компьютера или пользователя в гипотетическом сценарии.

Вызовите функцию FreeGPOList, чтобы освободить список групповой политики после завершения обработки.

Как правило, следует вызывать 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);
      }

Как правило, чтобы получить список объектов групповой политики для компьютера, можно вызвать 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);
      }

Чтобы получить список объектов групповой политики, примененных для определенного пользователя или компьютера и расширения, вызовите функцию GetAppliedGPOList.

Заметка

Заголовок userenv.h определяет GetGPOList в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
минимальный поддерживаемый сервер	Windows Server 2008
целевая платформа	Виндоус
заголовка	userenv.h
библиотеки	Userenv.lib
DLL	Userenv.dll

См. также

DsGetDcName

FreeGPOList

GROUP_POLICY_OBJECT

Функции групповой политики

Обзор групповой политики

Поделиться через