Función NetUserEnum (lmaccess.h)
La función NetUserEnum recupera información sobre todas las cuentas de usuario de un servidor.
Sintaxis
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
Puntero a una cadena constante que especifica el nombre DNS o NetBIOS del servidor remoto en el que se va a ejecutar la función. Si este parámetro es NULL, se usa el equipo local.
[in] level
Especifica el nivel de información de los datos. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
Devuelve nombres de cuenta de usuario. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_0 . |
|
Devuelve información detallada sobre las cuentas de usuario. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_1 . |
|
Devuelve información detallada sobre las cuentas de usuario, incluidos los niveles de autorización y la información de inicio de sesión. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_2 . |
|
Devuelve información detallada sobre las cuentas de usuario, incluidos los niveles de autorización, la información de inicio de sesión, los RID para el usuario y el grupo principal e información de perfil. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_3 . |
|
Devuelve los nombres y comentarios de usuario y cuenta. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_10 . |
|
Devuelve información detallada sobre las cuentas de usuario. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_11 . |
|
Devuelve el nombre y el identificador del usuario y varios atributos de cuenta. El parámetro bufptr apunta a una matriz de estructuras de USER_INFO_20 . Tenga en cuenta que en Windows XP y versiones posteriores, se recomienda usar USER_INFO_23 en su lugar. |
[in] filter
Valor que especifica los tipos de cuenta de usuario que se van a incluir en la enumeración. Un valor de cero indica que se deben incluir todos los datos normales de usuario, confianza y cuenta de equipo.
Este parámetro también puede ser una combinación de los valores siguientes.
[out] bufptr
Puntero al búfer que recibe los datos. El formato de estos datos depende del valor del parámetro level .
El sistema asigna el búfer para estos datos y la aplicación debe llamar a la función NetApiBufferFree para liberar la memoria asignada cuando los datos devueltos ya no sean necesarios. Tenga en cuenta que debe liberar el búfer incluso si se produce un error en la función NetUserEnum con ERROR_MORE_DATA.
[in] prefmaxlen
Longitud máxima preferida, en bytes, de los datos devueltos. Si especifica MAX_PREFERRED_LENGTH, la función NetUserEnum asigna la cantidad de memoria necesaria para los datos. Si especifica otro valor en este parámetro, puede restringir el número de bytes que devuelve la función. Si el tamaño del búfer no es suficiente para contener todas las entradas, la función devuelve ERROR_MORE_DATA. Para obtener más información, consulte Búferes de funciones de administración de red y longitudes de búfer de funciones de administración de red.
[out] entriesread
Puntero a un valor que recibe el recuento de elementos enumerados realmente.
[out] totalentries
Puntero a un valor que recibe el número total de entradas que se podrían haber enumerado a partir de la posición de reanudación actual. Tenga en cuenta que las aplicaciones solo deben tener en cuenta este valor como sugerencia. Si la aplicación se comunica con un controlador de dominio de Windows 2000 o posterior, debe considerar el uso del proveedor LDAP ADSI para recuperar este tipo de datos de forma más eficaz. El proveedor LDAP ADSI implementa un conjunto de objetos ADSI que admiten varias interfaces ADSI. Para obtener más información, consulte Proveedores de servicios ADSI.
Administrador de LAN: Si la llamada es a un equipo que ejecuta LAN Manager 2. x, el parámetro totalentries siempre reflejará el número total de entradas de la base de datos independientemente de dónde se encuentra en la secuencia de reanudación.
[in, out] resume_handle
Puntero a un valor que contiene un identificador de reanudación que se usa para continuar una búsqueda de usuario existente. El identificador debe ser cero en la primera llamada y dejar sin cambios para las llamadas posteriores. Si este parámetro es NULL, no se almacena ningún identificador de reanudación.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto se NERR_Success.
Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.
| Código devuelto | Descripción |
|---|---|
|
El usuario no tiene acceso a la información pedida. |
|
El nivel de llamada del sistema no es válido. Este error se devuelve si el parámetro level está establecido en un valor no admitido. |
|
El búfer es demasiado pequeño para contener una entrada. No se ha escrito información en el búfer. |
|
El nombre de equipo no es válido. |
|
Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas. |
Comentarios
La función NetUserEnum recupera información sobre todas las cuentas de usuario en un servidor remoto especificado o en el equipo local.
La función NetQueryDisplayInformation se puede usar para enumerar rápidamente la información de cuenta de usuario, equipo o grupo global para mostrarla en interfaces de usuario.
Si está programando para Active Directory, puede llamar a determinados métodos de interfaz de servicio de Active Directory (ADSI) para lograr la misma funcionalidad que puede lograr llamando a las funciones de usuario de administración de red. Para obtener más información, consulte IADsUser e IADsComputer.
Si llama a la función NetUserEnum en un controlador de dominio que ejecuta Active Directory, se permite o se deniega el acceso en función de la lista de control de acceso (ACL) para el objeto protegible. La ACL predeterminada permite que todos los usuarios y miembros autenticados del grupo "Acceso compatible con Pre-Windows 2000" vean la información. Si llama a esta función en un servidor miembro o estación de trabajo, todos los usuarios autenticados pueden ver la información. Para obtener información sobre el acceso anónimo y restringir el acceso anónimo en estas plataformas, consulte Requisitos de seguridad para las funciones de administración de red. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Model.
La función NetUserEnum solo devuelve información a la que el autor de la llamada tiene acceso de lectura. El autor de la llamada debe tener acceso List Contents al objeto Domain y Enumerar todo el acceso de dominio SAM en el objeto SAM Server ubicado en el contenedor System.
La función LsaEnumerateTrustedDomains o LsaEnumerateTrustedDomainsEx se puede usar para recuperar los nombres y los SID de dominios de confianza de un objeto de directiva de la Autoridad de seguridad local (LSA).
La función NetUserEnum no devuelve todos los usuarios del sistema. Devuelve solo los usuarios que se han agregado con una llamada a la función NetUserAdd . No hay ninguna garantía de que se devuelva la lista de usuarios en orden ordenado.
Si llama a la función NetUserEnum y especifica el nivel de información 1, 2 o 3, para el parámetro level , el miembro de contraseña de cada estructura recuperada se establece en NULL para mantener la seguridad de contraseña.
Los nombres de cuenta de usuario están limitados a 20 caracteres y los nombres de grupo están limitados a 256 caracteres. Además, los nombres de cuenta no se pueden terminar por un punto y no pueden incluir comas ni ninguno de los siguientes caracteres imprimibles: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Los nombres tampoco pueden incluir caracteres en el intervalo 1-31, que no son imprimibles.
La función NetUserEnum no admite un parámetro de nivel de 4 y la estructura USER_INFO_4 . La función NetUserGetInfo admite un parámetro de nivel de 4 y la estructura USER_INFO_4 .
Ejemplos
En el ejemplo de código siguiente se muestra cómo recuperar información sobre las cuentas de usuario de un servidor con una llamada a la función NetUserEnum . El ejemplo llama a NetUserEnum, especificando el nivel de información 0 (USER_INFO_0) para enumerar solo las cuentas de usuario globales. Si la llamada se realiza correctamente, el código recorre las entradas e imprime el nombre de cada cuenta de usuario. Por último, el ejemplo de código libera la memoria asignada para el búfer de información e imprime un total de los usuarios 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 | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | lmaccess.h (include Lm.h) |
| Library | Netapi32.lib |
| Archivo DLL | Netapi32.dll |
Consulte también
Funciones de administración de red