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

Статья
03/09/2023

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

Синтаксис

NET_API_STATUS NET_API_FUNCTION NetUserSetGroups(
  [in] LPCWSTR servername,
  [in] LPCWSTR username,
  [in] DWORD   level,
  [in] LPBYTE  buf,
  [in] DWORD   num_entries
);

Параметры

[in] servername

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

[in] username

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

[in] level

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

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

[in] buf

Указатель на буфер, указывающий данные. Дополнительные сведения см. в разделе Буферы функций управления сетью.

[in] num_entries

Количество записей, содержащихся в массиве, на который указывает параметр buf .

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	У пользователя нет доступа к запрошенной информации.
ERROR_INVALID_LEVEL	Неправильный уровень системного вызова. Эта ошибка возвращается, если параметр уровня был указан как значение, отличное от 0 или 1.
ERROR_INVALID_PARAMETER	Переданный параметр был недопустимым. Эта ошибка возвращается, если параметр num_entries был недопустимым.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для завершения операции.
NERR_InvalidComputer	Недопустимое имя компьютера.
NERR_NotPrimary	Операция разрешена только на основном контроллере домена.
NERR_GroupNotFound	Имя группы, указанное grui0_name в структуре GROUP_USERS_INFO_0 или член grui1_name в структуре GROUP_USERS_INFO_1 , на которую указывает параметр buf , не существует.
NERR_InternalError	Внутренняя ошибка.
NERR_UserNotFound	Не удалось найти имя пользователя.

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

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

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

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

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

Примеры

В следующем примере кода показано, как задать членство в глобальных группах для учетной записи пользователя с помощью вызова функции NetUserSetGroups . Пример кода заполняет grui0_name элемент структуры GROUP_USERS_INFO_0 и вызывает NetUserSetGroups, указывая уровень информации 0.

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

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

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   GROUP_USERS_INFO_0 gi;
   NET_API_STATUS nStatus;

   if (argc != 4)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName GroupName\n", argv[0]);
      exit(1);
   }
   //
   // Fill in the GROUP_USERS_INFO_0 structure member.
   //
   gi.grui0_name = argv[3];
   //
   // Call the NetUserSetGroups function; specify level 0.
   //
   nStatus = NetUserSetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE)&gi,
                              1);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Group membership has been successful for %s\n", argv[2]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

Требования


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