Função NetUserGetLocalGroups (lmaccess.h)
A função NetUserGetLocalGroups recupera uma lista de grupos locais aos quais um usuário especificado pertence.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetUserGetLocalGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] DWORD flags,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
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 retornar informações de associação de grupo local. Se a cadeia de caracteres for do formulário DomainName\UserName , espera-se que o nome de usuário seja encontrado nesse domínio. Se a cadeia de caracteres for do formato UserName, espera-se que o nome de usuário seja encontrado no servidor especificado pelo parâmetro servername . 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 ser o valor a seguir.
| Valor | Significado |
|---|---|
|
Retorne os nomes dos grupos locais aos quais o usuário pertence. O parâmetro bufptr aponta para uma matriz de estruturas de LOCALGROUP_USERS_INFO_0 . |
[in] flags
Uma máscara de bits de sinalizadores que afetam a operação. Atualmente, somente o valor definido é LG_INCLUDE_INDIRECT. Se esse bit for definido, a função também retornará os nomes dos grupos locais nos quais o usuário é indiretamente um membro (ou seja, o usuário tem associação em um grupo global que é um membro de um ou mais grupos locais).
[out] bufptr
Um ponteiro para o buffer que recebe os dados. O formato desses dados depende do valor do parâmetro de nível . Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree . Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA.
[in] prefmaxlen
O comprimento máximo preferencial, em bytes, dos dados retornados. Se MAX_PREFERRED_LENGTH for especificado nesse parâmetro, a função alocará a quantidade de memória necessária para os dados. Se outro valor for especificado nesse parâmetro, ele poderá restringir o número de bytes retornados pela função. Se o tamanho do buffer for insuficiente para manter todas as entradas, a função retornará ERROR_MORE_DATA. Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.
[out] entriesread
Um ponteiro para um valor que recebe a contagem de elementos realmente enumerados.
[out] totalentries
Um ponteiro para um valor que recebe o número total de entradas que poderiam ter sido enumeradas.
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 direitos de acesso às informações solicitadas. Esse erro também será retornado se o parâmetro servername tiver um espaço em branco à direita. |
|
O nível de chamada do sistema não está correto. Esse erro será retornado se o parâmetro de nível não tiver sido especificado como 0. |
|
Um parâmetro está incorreto. Esse erro será retornado se o parâmetro flags contiver um valor diferente de LG_INCLUDE_INDIRECT. |
|
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas. |
|
Memória insuficiente disponível para concluir a operação. |
|
Não foi possível encontrar o controlador de domínio. |
|
Não foi possível encontrar o usuário. Esse erro será retornado se o nome de usuário não puder ser encontrado. |
|
O servidor RPC não está disponível. Esse erro será retornado se o parâmetro servername não puder ser encontrado. |
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 todos os usuários autenticados e membros do grupo "Acesso compatível com o Pré-Windows 2000" exibam as informações. Se você chamar essa função em um servidor membro ou estação de trabalho, todos os usuários autenticados poderão exibir as informações. Para obter informações sobre acesso anônimo e restrição de acesso anônimo nessas plataformas, 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 Domain é usado para executar a marcar de acesso para essa função. O chamador deve ter a permissão Propriedade de Leitura no objeto Domain.
Para recuperar uma lista de grupos globais aos quais um usuário especificado pertence, você pode chamar a função NetUserGetGroups .
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 recuperar uma lista dos grupos locais aos quais um usuário pertence com uma chamada para a função NetUserGetLocalGroups . O exemplo chama NetUserGetLocalGroups, especificando o nível de informações 0 (LOCALGROUP_USERS_INFO_0). O exemplo percorre as entradas e imprime o nome de cada grupo local no qual o usuário tem associação. Se todas as entradas disponíveis não forem enumeradas, ela também imprimirá o número de entradas realmente enumeradas e o número total de entradas disponíveis. Por fim, o exemplo de código libera a memória alocada para o buffer de informações.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwFlags = LG_INCLUDE_INDIRECT ;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
NET_API_STATUS nStatus;
if (argc != 3)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
exit(1);
}
//
// Call the NetUserGetLocalGroups function
// specifying information level 0.
//
// The LG_INCLUDE_INDIRECT flag specifies that the
// function should also return the names of the local
// groups in which the user is indirectly a member.
//
nStatus = NetUserGetLocalGroups(argv[1],
argv[2],
dwLevel,
dwFlags,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nLocal group(s):\n");
//
// Loop through the entries and
// print the names of the local groups
// to which the user belongs.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
wprintf(L"\t-- %s\n", pTmpBuf->lgrui0_name);
pTmpBuf++;
dwTotalCount++;
}
}
//
// If all available entries were
// not enumerated, print the number actually
// enumerated and the total number available.
//
if (dwEntriesRead < dwTotalEntries)
fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
//
// Otherwise, just print the total.
//
printf("\nEntries enumerated: %d\n", dwTotalCount);
}
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
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