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

Статья
08/24/2023

Функция NetUserGetGroups извлекает список глобальных групп, к которым принадлежит указанный пользователь.

Синтаксис

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

Параметры

[in] servername

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

[in] username

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

[in] level

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

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

[out] bufptr

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

[in] prefmaxlen

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

[out] entriesread

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

[out] totalentries

Указатель на значение, которое получает общее количество записей, которые могли быть извлечены.

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Пользователь не имеет прав доступа к запрошенной информации.
ERROR_BAD_NETPATH	Сетевой путь не найден". Эта ошибка возвращается, если не удалось найти параметр servername .
ERROR_INVALID_LEVEL	Неправильный уровень системного вызова. Эта ошибка возвращается, если параметр уровня был указан как значение, отличное от 0 или 1.
ERROR_INVALID_NAME	Неправильный синтаксис имени. Эта ошибка возвращается, если параметр servername содержит пробелы в начале или конце или содержит недопустимый символ.
ERROR_MORE_DATA	Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для завершения операции.
NERR_InternalError	Внутренняя ошибка.
NERR_UserNotFound	Не удалось найти пользователя. Эта ошибка возвращается, если не удалось найти имя пользователя .

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

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

Дескриптор безопасности объекта User используется для выполнения проверка доступа для этой функции.

Чтобы получить список локальных групп, к которым принадлежит пользователь, можно вызвать функцию NetUserGetLocalGroups . Сетевые группы отделены и отличаются от системных групп Windows NT.

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

Примеры

В следующем примере кода показано, как получить список глобальных групп, к которым принадлежит пользователь, с помощью вызова функции NetUserGetGroups . В примере вызывается NetUserGetGroups, указывая уровень сведений 0 ( GROUP_USERS_INFO_0). Код циклически просматривает записи и выводит имена глобальных групп, в которых пользователь имеет членство. В примере также выводится общее количество доступных записей и количество записей, которые фактически перечисляются, если они не совпадают. Наконец, пример кода освобождает память, выделенную для буфера.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <assert.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPGROUP_USERS_INFO_0 pBuf = NULL;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserGetGroups function, specifying level 0.
   //
   nStatus = NetUserGetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE*)&pBuf,
                              dwPrefMaxLen,
                              &dwEntriesRead,
                              &dwTotalEntries);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPGROUP_USERS_INFO_0 pTmpBuf;
      DWORD i;
      DWORD dwTotalCount = 0;

      if ((pTmpBuf = pBuf) != NULL)
      {
         fprintf(stderr, "\nGlobal group(s):\n");
         //
         // Loop through the entries; 
         //  print the name of the global groups 
         //  to which the user belongs.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }

            wprintf(L"\t-- %s\n", pTmpBuf->grui0_name);

            pTmpBuf++;
            dwTotalCount++;
         }
      }
      //
      // If all available entries were
      //  not enumerated, print the number actually 
      //  enumerated and the total number available.
      //
      if (dwEntriesRead < dwTotalEntries)
         fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
      //
      // Otherwise, just print the total.
      //
      printf("\nEntries enumerated: %d\n", dwTotalCount);
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Требования


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