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

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

  • Статья

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

Синтаксис

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

Параметры

[in] servername

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

[in] username

Указатель на константную строку, указывающую имя пользователя, для которого возвращаются сведения о членстве в локальной группе. Если строка имеет вид DomainName\UserName , имя пользователя должно быть найдено в этом домене. Если строка имеет форму UserName, имя пользователя должно быть найдено на сервере, указанном параметром servername . Дополнительные сведения см. в разделе «Примечания».

[in] level

Информационный уровень данных. Этот параметр может иметь следующее значение.

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

[in] flags

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

[out] bufptr

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

[in] prefmaxlen

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

[out] entriesread

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

[out] totalentries

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

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

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

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

Код возврата Описание
ERROR_ACCESS_DENIED
 У пользователя нет прав доступа к запрошенной информации. Эта ошибка также возвращается, если параметр servername имеет пустое значение.
ERROR_INVALID_LEVEL
 Неправильный уровень системного вызова. Эта ошибка возвращается, если параметр уровня не был указан как 0.
ERROR_INVALID_PARAMETER
 Неправильный параметр. Эта ошибка возвращается, если параметр flags содержит значение, отличное от LG_INCLUDE_INDIRECT.
ERROR_MORE_DATA
 Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей.
ERROR_NOT_ENOUGH_MEMORY
 Недостаточно памяти для завершения операции.
NERR_DCNotFound
 Не удалось найти контроллер домена.
NERR_UserNotFound
 Не удалось найти пользователя. Эта ошибка возвращается, если не удалось найти имя пользователя .
RPC_S_SERVER_UNAVAILABLE
 Сервер RPC недоступен. Эта ошибка возвращается, если не удалось найти параметр servername .

Комментарии

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

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

Дескриптор безопасности объекта Domain используется для выполнения проверка доступа для этой функции. Вызывающий объект должен иметь разрешение на чтение свойства для объекта Domain.

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

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

Примеры

В следующем примере кода показано, как получить список локальных групп, к которым принадлежит пользователь, с помощью вызова функции NetUserGetLocalGroups . Пример вызывает NetUserGetLocalGroups, указывая уровень информации 0 (LOCALGROUP_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[])
{
   LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
   DWORD dwLevel = 0;
   DWORD dwFlags = LG_INCLUDE_INDIRECT ;
   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 NetUserGetLocalGroups function 
   //  specifying information level 0.
   //
   //  The LG_INCLUDE_INDIRECT flag specifies that the 
   //   function should also return the names of the local 
   //   groups in which the user is indirectly a member.
   //
   nStatus = NetUserGetLocalGroups(argv[1],
                                   argv[2],
                                   dwLevel,
                                   dwFlags,
                                   (LPBYTE *) &pBuf,
                                   dwPrefMaxLen,
                                   &dwEntriesRead,
                                   &dwTotalEntries);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
      DWORD i;
      DWORD dwTotalCount = 0;

      if ((pTmpBuf = pBuf) != NULL)
      {
         fprintf(stderr, "\nLocal group(s):\n");
         //
         // Loop through the entries and 
         //  print the names of the local 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->lgrui0_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 memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Требования

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

См. также раздел

LOCALGROUP_USERS_INFO_0

NetUserGetGroups

Функции управления сетью

Общие сведения об управлении сетью

Пользовательские функции