Função NetUserSetGroups (lmaccess.h)
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 |
|---|---|
|
O parâmetro buf aponta para uma matriz de estruturas de GROUP_USERS_INFO_0 que especifica nomes de grupo globais. |
|
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 |
|---|---|
|
O usuário não tem acesso às informações solicitadas. |
|
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. |
|
Um parâmetro passado não era válido. Esse erro será retornado se o parâmetro num_entries não for válido. |
|
Memória insuficiente disponível para concluir a operação. |
|
O nome do computador é inválido. |
|
A operação é permitida somente no controlador de domínio primário do domínio. |
|
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. |
|
Ocorreu um erro interno. |
|
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 |
Confira também
Funções de gerenciamento de rede