Função NetUserEnum (lmaccess.h)
A função NetUserEnum recupera informações sobre todas as contas de usuário em um servidor.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetUserEnum(
[in] LPCWSTR servername,
[in] DWORD level,
[in] DWORD filter,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] PDWORD resume_handle
);
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] level
Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Retornar nomes de conta de usuário. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_0 . |
|
Retornar informações detalhadas sobre contas de usuário. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_1 . |
|
Retornar informações detalhadas sobre contas de usuário, incluindo níveis de autorização e informações de logon. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_2 . |
|
Retorne informações detalhadas sobre contas de usuário, incluindo níveis de autorização, informações de logon, RIDs para o usuário e o grupo primário e informações de perfil. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_3 . |
|
Retornar nomes e comentários de usuário e conta. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_10 . |
|
Retornar informações detalhadas sobre contas de usuário. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_11 . |
|
Retorne o nome e o identificador do usuário e vários atributos de conta. O parâmetro bufptr aponta para uma matriz de estruturas de USER_INFO_20 . Observe que, no Windows XP e posterior, é recomendável que você use USER_INFO_23 em vez disso. |
[in] filter
Um valor que especifica os tipos de conta de usuário a serem incluídos na enumeração. Um valor zero indica que todos os dados normais de usuário, dados de confiança e conta de computador devem ser incluídos.
Esse parâmetro também pode ser uma combinação dos valores a seguir.
[out] bufptr
Um ponteiro para o buffer que recebe os dados. O formato desses dados depende do valor do parâmetro de nível .
O buffer para esses dados é alocado pelo sistema e o aplicativo deve chamar a função NetApiBufferFree para liberar a memória alocada quando os dados retornados não forem mais necessários. Observe que você deve liberar o buffer mesmo que a função NetUserEnum falhe com ERROR_MORE_DATA.
[in] prefmaxlen
O comprimento máximo preferencial, em bytes, dos dados retornados. Se você especificar MAX_PREFERRED_LENGTH, a função NetUserEnum alocará a quantidade de memória necessária para os dados. Se você especificar outro valor 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 da posição de currículo atual. Observe que os aplicativos devem considerar esse valor apenas como uma dica. Se o aplicativo estiver se comunicando com um controlador de domínio do Windows 2000 ou posterior, considere usar o Provedor ADSI LDAP para recuperar esse tipo de dados com mais eficiência. O Provedor ADSI LDAP implementa um conjunto de objetos ADSI que dão suporte a várias interfaces ADSI. Para obter mais informações, consulte Provedores de Serviços ADSI.
Gerenciador de LAN: Se a chamada for para um computador que está executando o LAN Manager 2. x, o parâmetro totalentries sempre refletirá o número total de entradas no banco de dados, independentemente de onde ele esteja na sequência de currículos.
[in, out] resume_handle
Um ponteiro para um valor que contém um identificador de currículo que é usado para continuar uma pesquisa de usuário existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se esse parâmetro for NULL, nenhum identificador de retomada será armazenado.
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 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 for definido como um valor sem suporte. |
|
O buffer é muito pequeno para conter uma entrada. Nenhuma informação foi gravada no buffer. |
|
O nome do computador é inválido. |
|
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas. |
Comentários
A função NetUserEnum recupera informações sobre todas as contas de usuário em um servidor remoto especificado ou no computador local.
A função NetQueryDisplayInformation pode ser usada para enumerar rapidamente informações de conta de usuário, computador ou grupo global para exibição nas interfaces do usuário.
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 a função NetUserEnum 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 restringir o 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.
A função NetUserEnum retorna apenas informações às quais o chamador tem acesso de Leitura. O chamador deve ter acesso de Conteúdo de Lista ao objeto Domain e enumerar todo o acesso ao domínio SAM no objeto servidor SAM localizado no contêiner Do sistema.
A função LsaEnumerateTrustedDomains ou LsaEnumerateTrustedDomainsEx pode ser usada para recuperar os nomes e SIDs de domínios confiáveis por um objeto de política da LSA (Autoridade de Segurança Local).
A função NetUserEnum não retorna todos os usuários do sistema. Ele retorna apenas os usuários que foram adicionados com uma chamada para a função NetUserAdd . Não há nenhuma garantia de que a lista de usuários será retornada em ordem classificada.
Se você chamar a função NetUserEnum e especificar o nível de informações 1, 2 ou 3, para o parâmetro de nível , o membro de senha de cada estrutura recuperada será definido como NULL para manter a segurança de senha.
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.
A função NetUserEnum não dá suporte a um parâmetro de nível 4 e à estrutura USER_INFO_4 . A função NetUserGetInfo dá suporte a um parâmetro de nível 4 e à estrutura USER_INFO_4 .
Exemplos
O exemplo de código a seguir demonstra como recuperar informações sobre as contas de usuário em um servidor com uma chamada para a função NetUserEnum . O exemplo chama NetUserEnum, especificando o nível de informações 0 (USER_INFO_0) para enumerar apenas contas de usuário globais. Se a chamada for bem-sucedida, o código percorrerá as entradas e imprimirá o nome de cada conta de usuário. Por fim, o exemplo de código libera a memória alocada para o buffer de informações e imprime um total de usuários enumerados.
#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[])
{
LPUSER_INFO_0 pBuf = NULL;
LPUSER_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPTSTR pszServerName = NULL;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
exit(1);
}
// The server is not the default local computer.
//
if (argc == 2)
pszServerName = (LPTSTR) argv[1];
wprintf(L"\nUser account on %s: \n", pszServerName);
//
// Call the NetUserEnum function, specifying level 0;
// enumerate global user account types only.
//
do // begin do
{
nStatus = NetUserEnum((LPCWSTR) pszServerName,
dwLevel,
FILTER_NORMAL_ACCOUNT, // global users
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the name of the user account.
//
wprintf(L"\t-- %s\n", pTmpBuf->usri0_name);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, print the system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
// Continue to call NetUserEnum while
// there are more entries.
//
while (nStatus == ERROR_MORE_DATA); // end do
//
// Check again for allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of users enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
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 |
Confira também
Funções de gerenciamento de rede