Función NetUserGetLocalGroups (lmaccess.h)
La función NetUserGetLocalGroups recupera una lista de grupos locales a los que pertenece un usuario especificado.
Sintaxis
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
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 para el que se va a devolver información de pertenencia a grupos locales. Si la cadena tiene el formato DomainName UserName\, se espera que el nombre de usuario se encuentre en ese dominio. Si la cadena tiene el formato UserName, se espera que el nombre de usuario se encuentre en el servidor especificado por el parámetro servername . Para obtener más información, vea la sección Comentarios.
[in] level
Nivel de información de los datos. Este parámetro puede ser el siguiente valor.
| Valor | Significado |
|---|---|
|
Devuelve los nombres de los grupos locales a los que pertenece el usuario. El parámetro bufptr apunta a una matriz de estructuras de LOCALGROUP_USERS_INFO_0 . |
[in] flags
Máscara de bits de marcas que afectan a la operación. Actualmente, solo se LG_INCLUDE_INDIRECT el valor definido. Si se establece este bit, la función también devuelve los nombres de los grupos locales en los que el usuario es indirectamente un miembro (es decir, el usuario tiene pertenencia a un grupo global que es en sí mismo miembro de uno o varios grupos locales).
[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 este búfer y debe liberarse 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 los datos devueltos. Si se especifica MAX_PREFERRED_LENGTH en este parámetro, 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 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.
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 derechos de acceso a la información solicitada. Este error también se devuelve si el parámetro servername tiene un espacio en blanco final. |
|
El nivel de llamada del sistema no es válido. Este error se devuelve si el parámetro level no se especificó como 0. |
|
Un parámetro es incorrecto. Este error se devuelve si el parámetro flags contiene un valor distinto de LG_INCLUDE_INDIRECT. |
|
Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas. |
|
La memoria insuficiente estaba disponible para completar la operación. |
|
No se encontró el controlador de dominio. |
|
No se encontró el usuario. Este error se devuelve si no se encontró el nombre de usuario . |
|
El servidor RPC no está disponible. Este error se devuelve si no se encontró el parámetro servername . |
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 red. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Model.
El descriptor de seguridad del objeto Domain se usa para realizar la comprobación de acceso de esta función. El autor de la llamada debe tener el permiso Read Property en el objeto Domain.
Para recuperar una lista de grupos globales a los que pertenece un usuario especificado, puede llamar a la función NetUserGetGroups .
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 los grupos locales a los que pertenece un usuario con una llamada a la función NetUserGetLocalGroups . El ejemplo llama a NetUserGetLocalGroups, especificando el nivel de información 0 (LOCALGROUP_USERS_INFO_0). El ejemplo recorre en bucle las entradas e imprime el nombre de cada grupo local en el que el usuario tiene pertenencia. Si no se enumeran todas las entradas disponibles, también imprime el número de entradas realmente enumeradas y el número total de entradas disponibles. Por último, el ejemplo de código libera la memoria asignada para el búfer de información.
#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 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