GetGPOList

The GetGPOList function retrieves the list of GPOs for the specified user or computer. This function can be called in two ways: by using the token for the user or computer, or by using the name of the user or computer and the name of the domain controller.

BOOL GetGPOList(
  HANDLE hToken, 
  LPCTSTR lpName, 
  LPCTSTR lpHostName,
  LPCTSTR lpComputerName,
  DWORD dwFlags,
  PGROUP_POLICY_OBJECT *pGPOList
);

Parameters

hToken

[in] Token for the user or computer, returned from the LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken, or OpenThreadToken function. This token must have TOKEN_IMPERSONATE and TOKEN_QUERY access.

If this parameter is NULL, you must supply values for the lpName and lpHostName parameters.

lpName

[in] Pointer to the user or computer name, in ADSI format (LDAP://cn=user, ou=users,dc=coname,dc=com).

If the hToken parameter is not NULL, this parameter must be NULL.

lpHostName

[in] Pointer to the DN or domain controller name. This name can be retrieved using the DsGetDcName function.

If the hToken parameter is not NULL, this parameter must be NULL.

lpComputerName

[in] Pointer to the name of the computer used to determine the site location. The format of the name is \\computer_name. If this parameter is NULL, the local computer name is used.

dwFlags

[in] Specifies additional flags for controlling information retrieval. This parameter can be one of the following values.

Value	Meaning
GPO_LIST_FLAG_MACHINE	Retrieves only computer policy information.
GPO_LIST_FLAG_SITEONLY	Retrieves only site policy information.

pGPOList

[out] Pointer that receives the list of GPO structures. For more information, see GROUP_POLICY_OBJECT.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetGPOList function is intended for use by services acting on behalf of a user or computer. The service calls this function to obtain a list of GPOs, then checks each GPO for service-specific policy.

Calling this function with a token provides the most accurate list. The system can perform access checking for the user or computer. Calling this function with the user or computer name and the domain controller name is faster than calling it with a token. However, if the token is not specified, the system uses the security access of the caller, which means that the list may not be completely correct for the intended user or computer.

Generally, you should call GetGPOList with a token when retrieving a list of GPOs for a user. To retrieve a list of GPOs for a computer, call GetGPOList with the computer name and domain controller name.

To free the list when you have finished, call the FreeGPOList function.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Userenv.h.
  Library: Use Userenv.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

Group Policy Overview, Group Policy Functions, DsGetDcName, FreeGPOList, GROUP_POLICY_OBJECT