Função NetLocalGroupAdd (lmaccess.h)

Artigo
08/24/2023

A função NetLocalGroupAdd cria um grupo local no banco de dados de segurança, que é o banco de dados sam (gerenciador de contas de segurança) ou, no caso de controladores de domínio, o Active Directory.

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetLocalGroupAdd(
  [in]  LPCWSTR servername,
  [in]  DWORD   level,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

Parâmetros

[in] servername

Um ponteiro para uma cadeia de caracteres 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] level

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

Valor	Significado
0	Um nome de grupo local. O parâmetro buf aponta para uma estrutura LOCALGROUP_INFO_0 .
1	Um nome de grupo local e um comentário a ser associado ao grupo. O parâmetro buf aponta para uma estrutura de LOCALGROUP_INFO_1 .

[in] buf

Um ponteiro para um buffer que contém a estrutura de informações do grupo local. O formato desses dados depende do valor do parâmetro level . Para obter mais informações, consulte Buffers de função de gerenciamento de rede.

[out] parm_err

Um ponteiro para um valor que recebe o índice do primeiro membro da estrutura de informações do grupo local para causar o erro de ERROR_INVALID_PARAMETER. Se esse parâmetro for NULL, o índice não será retornado com erro. Para obter mais informações, consulte a seção Comentários no tópico NetLocalGroupSetInfo .

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 códigos de erro a seguir.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O chamador não tem o acesso apropriado para concluir a operação.
ERROR_ALIAS_EXISTS	O grupo local especificado já existe. Esse erro será retornado se o membro do nome do grupo na estrutura apontada pelo parâmetro buf já estiver em uso como um alias.
ERROR_INVALID_LEVEL	Um parâmetro de nível é inválido.
ERROR_INVALID_PARAMETER	Um parâmetro está incorreto. Esse erro será retornado se um ou mais dos membros na estrutura apontada pelo parâmetro buf forem inválidos.
NERR_GroupExists	O nome do grupo existe. Esse erro será retornado se o membro do nome do grupo na estrutura apontada pelo parâmetro buf já estiver em uso como um nome de grupo.
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_UserExists	O nome de usuário existe. Esse erro será retornado se o membro de nome de grupo na estrutura apontada pelo parâmetro buf já estiver em uso como um nome de usuário.

Comentários

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 somente 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 avançados 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 contêiner de usuário é usado para executar a marcar de acesso para essa função. O chamador deve ser capaz de criar objetos filho da classe de grupo.

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.

Se a função NetLocalGroupAdd retornar ERROR_INVALID_PARAMETER e um ponteiro NULL não tiver sido passado no parâmetro parm_err , no retorno, o parâmetro parm_err indicará o primeiro membro da estrutura de informações do grupo local inválido. O formato da estrutura de informações do grupo local é especificado no parâmetro level . Um ponteiro para a estrutura de informações do grupo local é passado no parâmetro buf . A tabela a seguir lista os valores que podem ser retornados no parâmetro parm_err e o membro da estrutura correspondente que está com erro.

Valor	Membro
LOCALGROUP_NAME_PARMNUM	Se o parâmetro de nível fosse 0, o membro lgrpi0_name da estrutura LOCALGROUP_INFO_0 era inválido. Se o parâmetro de nível fosse 1, o membro lgrpi1_name da estrutura LOCALGROUP_INFO_1 era inválido.
LOCALGROUP_COMMENT_PARMNUM	Se o parâmetro de nível fosse 1, o membro lgrpi1_comment da estrutura LOCALGROUP_INFO_1 era inválido.

Ao fazer solicitações para um controlador de domínio e o Active Directory, talvez você possa chamar determinados métodos adsi (Interface de Serviço do Active Directory) para obter os mesmos resultados que as funções do grupo local de gerenciamento de rede. Para obter mais informações, consulte IADsGroup.

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