Função NetLocalGroupSetInfo (lmaccess.h)

Artigo
08/24/2023

A função NetLocalGroupSetInfo altera o nome de um grupo local existente. A função também associa um comentário a um grupo local.

Sintaxe

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

Parâmetros

[in] servername

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] groupname

Ponteiro para uma cadeia de caracteres constante que especifica o nome da conta de grupo local a ser modificada. Para obter mais informações, consulte a seção Comentários a seguir.

[in] level

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

Valor	Significado
0	Especifica o nome do grupo local. O parâmetro buf aponta para uma estrutura LOCALGROUP_INFO_0 . Use esse nível para alterar o nome de um grupo local existente.
1	Especifica o nome do grupo local e um comentário a ser associado ao grupo. O parâmetro buf aponta para uma estrutura de LOCALGROUP_INFO_1 .
1002	Especifica um comentário a ser associado ao grupo local. O parâmetro buf aponta para uma estrutura LOCALGROUP_INFO_1002 .

[in] buf

Ponteiro para um buffer que contém as 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

Ponteiro para um valor que recebe o índice do primeiro membro da estrutura de informações do grupo local que causou 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 a seguir.

Retornar valor

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 usuário não tem acesso às informações solicitadas.
ERROR_INVALID_PARAMETER	Um dos parâmetros de função é inválido. Para obter mais informações, consulte a seção Comentários a seguir.
ERROR_NO_SUCH_ALIAS	O grupo local especificado não existe.
NERR_NotPrimary	A operação é permitida somente no controlador de domínio primário do domínio.
NERR_InvalidComputer	O nome do computador é inválido.

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 objeto LocalGroup é usado para executar a marcar de acesso para essa função. Normalmente, os chamadores devem ter acesso de gravação ao objeto inteiro para que as chamadas a essa função tenham êxito.

Para especificar o novo nome de um grupo local existente, chame NetLocalGroupSetInfo com LOCALGROUP_INFO_0 e especifique um valor usando o membro lgrpi0_name . Se você chamar a função NetLocalGroupSetInfo com LOCALGROUP_INFO_1 e especificar um novo valor usando o membro lgrpi1_name , esse valor será ignorado.

Se a função NetLocalGroupSetInfo retornar ERROR_INVALID_PARAMETER, você poderá usar o parâmetro parm_err para indicar o primeiro membro da estrutura de informações do grupo local inválido. (Uma estrutura de informações de grupo local começa com LOCALGROUP_INFO_ e seu formato é especificado pelo parâmetro level .) 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. (O prefixo lgrpi*_ indica que o membro pode começar com vários prefixos, por exemplo, lgrpi0_ ou lgrpi1_.)

Valor	Membro
LOCALGROUP_NAME_PARMNUM	lgrpi*_name
LOCALGROUP_COMMENT_PARMNUM	lgrpi*_comment

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 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 grupo local de gerenciamento de rede. Para obter mais informações, consulte IADsGroup.

Requisitos

Requisito	Valor
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