Função NetUserSetGroups (lmaccess.h)

Artigo
03/09/2023

A função NetUserSetGroups define associações de grupo global para uma conta de usuário especificada.

Sintaxe

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

Parâmetros

[in] servername

Um ponteiro para uma cadeia de caracteres constante que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

[in] username

Um ponteiro para uma cadeia de caracteres constante que especifica o nome do usuário para o qual definir associações de grupo global. Para obter mais informações, consulte a seção Comentários.

[in] level

O nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
0	O parâmetro buf aponta para uma matriz de estruturas de GROUP_USERS_INFO_0 que especifica nomes de grupo globais.
1	O parâmetro buf aponta para uma matriz de estruturas de GROUP_USERS_INFO_1 que especifica nomes de grupo globais com atributos.

[in] buf

Um ponteiro para o buffer que especifica os dados. Para obter mais informações, consulte Buffers de função de gerenciamento de rede.

[in] num_entries

O número de entradas contidas na matriz apontada pelo parâmetro buf .

Valor retornado

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O usuário não tem acesso às informações solicitadas.
ERROR_INVALID_LEVEL	O nível de chamada do sistema não está correto. Esse erro será retornado se o parâmetro de nível tiver sido especificado como um valor diferente de 0 ou 1.
ERROR_INVALID_PARAMETER	Um parâmetro passado não era válido. Esse erro será retornado se o parâmetro num_entries não for válido.
ERROR_NOT_ENOUGH_MEMORY	Memória insuficiente disponível para concluir a operação.
NERR_InvalidComputer	O nome do computador é inválido.
NERR_NotPrimary	A operação é permitida somente no controlador de domínio primário do domínio.
NERR_GroupNotFound	O nome do grupo especificado pelo grui0_name na estrutura GROUP_USERS_INFO_0 ou membro grui1_name na estrutura GROUP_USERS_INFO_1 apontada pelo parâmetro buf não existe.
NERR_InternalError	Ocorreu um erro interno.
NERR_UserNotFound	Não foi possível encontrar o nome de usuário.

Comentários

Se você estiver programando para o Active Directory, poderá chamar determinados métodos ADSI (Active Directory Service Interface) para obter a mesma funcionalidade que você pode obter chamando as funções de usuário de gerenciamento de rede. Para obter mais informações, consulte IADsUsUser e IADsComputer.

Se você chamar essa função em um controlador de domínio que está executando o Active Directory, o acesso será permitido ou negado com base na ACL (lista de controle de acesso) do objeto protegível. A ACL padrão permite que apenas administradores de domínio e operadores de conta chamem essa função. Em um servidor membro ou estação de trabalho, somente administradores e usuários de energia podem chamar essa função. Para obter mais informações, consulte Requisitos de segurança para as funções de gerenciamento de rede. Para obter mais informações sobre ACLs, ACEs e tokens de acesso, consulte Controle de Acesso Model.

O descritor de segurança do objeto User é usado para executar a marcar de acesso para essa função.

Para conceder uma associação de usuário em um grupo global existente, você pode chamar a função NetGroupAddUser .

Os nomes de conta de usuário são limitados a 20 caracteres e os nomes de grupo são limitados a 256 caracteres. Além disso, os nomes de conta não podem ser encerrados por um período e não podem incluir vírgulas ou qualquer um dos seguintes caracteres imprimíveis: ", /, , [, ], :, |, <, , >, +, =, ;, ?, *. Os nomes também não podem incluir caracteres no intervalo de 1 a 31, que são não imprimíveis.

Exemplos

O exemplo de código a seguir demonstra como definir associações de grupo global para uma conta de usuário com uma chamada para a função NetUserSetGroups . O exemplo de código preenche o grui0_name membro da estrutura GROUP_USERS_INFO_0 e chama NetUserSetGroups, especificando o nível de informações 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;
}

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmaccess.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll