Функция NetGroupEnum (lmaccess.h)

Статья
08/24/2023

Функция NetGroupEnum извлекает сведения о каждой глобальной группе в базе данных безопасности, которая является базой данных диспетчера учетных записей безопасности (SAM) или, в случае контроллеров домена, Active Directory.

Функция NetQueryDisplayInformation предоставляет эффективный механизм перечисления глобальных групп. По возможности рекомендуется использовать NetQueryDisplayInformation вместо функции NetGroupEnum .

Синтаксис

NET_API_STATUS NET_API_FUNCTION NetGroupEnum(
  [in]      LPCWSTR    servername,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resume_handle
);

Параметры

[in] servername

Указатель на строку константы, указывающую DNS или NetBIOS-имя удаленного сервера, на котором выполняется функция. Если этот параметр имеет значение NULL, используется локальный компьютер.

[in] level

Задает уровень информации данных. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
0	Возвращает имя глобальной группы. Параметр bufptr указывает на массив GROUP_INFO_0 структур.
1	Возвращает имя глобальной группы и комментарий. Параметр bufptr указывает на массив GROUP_INFO_1 структур.
2	Возвращает подробные сведения о глобальной группе. Параметр bufptr указывает на массив GROUP_INFO_2 структур. Обратите внимание, что в Windows XP и более поздних версиях рекомендуется использовать GROUP_INFO_3 .
3	Возвращает подробные сведения о глобальной группе. Параметр bufptr указывает на массив GROUP_INFO_3 структур. Windows 2000: Этот уровень не поддерживается.

[out] bufptr

Указатель на буфер для получения структуры сведений о глобальной группе. Формат этих данных зависит от значения параметра level .

Система выделяет память для этого буфера. Чтобы освободить память, необходимо вызвать функцию NetApiBufferFree . Обратите внимание, что буфер необходимо освободить, даже если функция завершается сбоем с ERROR_MORE_DATA.

[in] prefmaxlen

Задает предпочтительную максимальную длину возвращаемых данных в байтах. Если указать MAX_PREFERRED_LENGTH, функция выделяет объем памяти, необходимый для хранения данных. Если указать другое значение в этом параметре, это может ограничить количество байтов, возвращаемых функцией. Если размер буфера недостаточен для хранения всех записей, функция возвращает ERROR_MORE_DATA. Дополнительные сведения см. в разделах Буферы функций управления сетью и Длина буфера функции управления сетью.

[out] entriesread

Указатель на значение, которое получает количество фактически перечисленных элементов.

[out] totalentries

Указатель на значение, которое получает общее количество записей, которые можно было бы перечислить из текущей позиции резюме. Общее количество записей является лишь указанием. Дополнительные сведения об определении точного количества записей см. в следующем разделе Примечаний.

[in, out] resume_handle

Указатель на переменную, содержащую дескриптор возобновления, используемый для продолжения перечисления глобальной группы. Дескриптор должен быть равен нулю при первом вызове и оставить без изменений для последующих вызовов. Если этот параметр имеет значение NULL, дескриптор возобновления не сохраняется.

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Пользователь не имеет доступа к запрошенной информации.
NERR_InvalidComputer	Недопустимое имя компьютера.
ERROR_MORE_DATA	Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей.

При программировании для Active Directory вы можете вызвать определенные методы интерфейса службы Active Directory (ADSI), чтобы достичь тех же функций, которые можно достичь, вызывая функции группы управления сетью. Дополнительные сведения см. в разделе IADsGroup.

Если вы вызываете эту функцию на контроллере домена под управлением Active Directory, доступ разрешен или запрещен на основе списка управления доступом (ACL) для защищаемого объекта. Список управления доступом по умолчанию позволяет просматривать сведения всем пользователям, прошедшим проверку подлинности, и членам группы "Доступ, совместимый с Windows 2000". Если вы вызываете эту функцию на рядовом сервере или рабочей станции, все пользователи, прошедшие проверку подлинности, смогут просматривать сведения. Сведения об анонимном доступе и ограничении анонимного доступа на этих платформах см. в разделе Требования к безопасности для функций управления сетью. Дополнительные сведения о списках управления доступом, ACE и маркерах доступа см. в разделе модель контроль доступа.

Функция возвращает только сведения, к которым вызывающий объект имеет доступ на чтение. Вызывающий объект должен иметь доступ к объекту Domain (Список содержимого) и Полный доступ к домену SAM в объекте SAM Server, расположенном в контейнере System.

Чтобы определить точное общее количество групп, необходимо перечислить все дерево, что может быть дорогостоящей операцией. Чтобы перечислить все дерево, используйте параметр resume_handle для продолжения перечисления для последовательных вызовов, а параметр entriesread — для накопления общего количества групп. Если приложение взаимодействует с контроллером домена, рекомендуется использовать поставщик ADSI LDAP для более эффективного извлечения данных этого типа. Поставщик LDAP ADSI реализует набор объектов ADSI, поддерживающих различные интерфейсы ADSI. Дополнительные сведения см. в разделе Поставщики служб ADSI.

Имена учетных записей пользователей могут содержать не более 20 символов, а имена групп — не более 256 символов. Кроме того, имена учетных записей не могут быть завершены точкой и не могут содержать запятые или любые из следующих печатных символов: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Имена также не могут содержать непечатаемые символы в диапазоне от 1 до 31.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	lmaccess.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll