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.

[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.

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

Consulte también

LOCALGROUP_USERS_INFO_0

NetUserGetGroups

Funciones de administración de red

Introducción a la administración de redes

Funciones de usuario