Función NetUserGetGroups (lmaccess.h)
La función NetUserGetGroups recupera una lista de grupos globales a los que pertenece un usuario especificado.
Sintaxis
NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
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] username
Puntero a una cadena constante que especifica el nombre del usuario que se va a buscar en cada cuenta de grupo. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
[in] level
Nivel de información de los datos solicitados. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
Devuelve los nombres de los grupos globales a los que pertenece el usuario. El parámetro bufptr apunta a una matriz de estructuras GROUP_USERS_INFO_0 . |
|
Devuelve los nombres de los grupos globales a los que pertenece el usuario con atributos. El parámetro bufptr apunta a una matriz de estructuras GROUP_USERS_INFO_1 . |
[out] bufptr
Puntero al búfer que recibe los datos. El sistema asigna este búfer y se debe liberar mediante la función NetApiBufferFree . Tenga en cuenta que debe liberar el búfer incluso si se produce un error en la función con ERROR_MORE_DATA.
[in] prefmaxlen
Longitud máxima preferida, en bytes, de datos devueltos. Si se especifica MAX_PREFERRED_LENGTH, la función asigna la cantidad de memoria necesaria para los datos. Si se 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 Network Management Function Buffers (Búferes de funciones de administración de red) y Network Management Function Buffer Lengths (Longitudes de búfer de funciones de administración de red).
[out] entriesread
Puntero a un valor que recibe el recuento de elementos recuperados realmente.
[out] totalentries
Puntero a un valor que recibe el número total de entradas que se podrían haber recuperado.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es 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 derechos de acceso a la información solicitada. |
|
No se ha encontrado la ruta de acceso de la red. Este error se devuelve si no se encontró el parámetro servername . |
|
El nivel de llamada del sistema no es válido. Este error se devuelve si el parámetro level se especificó como un valor distinto de 0 o 1. |
|
La sintaxis de nombre es incorrecta. Este error se devuelve si el parámetro servername tiene espacios en blanco iniciales o finales o contiene un carácter no válido. |
|
Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas. |
|
No había memoria suficiente para completar la operación. |
|
Se ha producido un error interno. |
|
No se encontró el usuario. Este error se devuelve si no se encontró el nombre de usuario . |
Comentarios
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 esta función 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 redes. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Modelo.
El descriptor de seguridad del objeto User se usa para realizar la comprobación de acceso de esta función.
Para recuperar una lista de los grupos locales a los que pertenece un usuario, puede llamar a la función NetUserGetLocalGroups . Los grupos de red son independientes y distintos de los grupos de sistema de Windows NT.
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.
Ejemplos
En el ejemplo de código siguiente se muestra cómo recuperar una lista de grupos globales a los que pertenece un usuario con una llamada a la función NetUserGetGroups . El ejemplo llama a NetUserGetGroups, especificando el nivel de información 0 ( GROUP_USERS_INFO_0). El código recorre en bucle las entradas e imprime el nombre de los grupos globales en los que el usuario tiene pertenencia. El ejemplo también imprime el número total de entradas que están disponibles y el número de entradas realmente enumeradas si no coinciden. Por último, el ejemplo de código libera la memoria asignada para el búfer.
#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[])
{
LPGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
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 NetUserGetGroups function, specifying level 0.
//
nStatus = NetUserGetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nGlobal group(s):\n");
//
// Loop through the entries;
// print the name of the global 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->grui0_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 buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
Requisitos
| 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 redes