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

Статья
08/24/2023

Функция NetLocalGroupEnum возвращает сведения о каждой учетной записи локальной группы на указанном сервере.

Синтаксис

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

Параметры

[in] servername

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

[in] level

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

Значение	Значение
0	Возвращает имена локальных групп. Параметр bufptr указывает на массив LOCALGROUP_INFO_0 структур.
1	Возвращает имена локальных групп и комментарий, связанный с каждой группой. Параметр bufptr указывает на массив LOCALGROUP_INFO_1 структур.

[out] bufptr

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

[in] prefmaxlen

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

[out] entriesread

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

[out] totalentries

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

[in, out] resumehandle

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

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

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

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

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

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

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

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

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

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

Требования


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