Función NetLocalGroupEnum (lmaccess.h)

Artículo
08/24/2023

La función NetLocalGroupEnum devuelve información sobre cada cuenta de grupo local en el servidor especificado.

Sintaxis

NET_API_STATUS NET_API_FUNCTION NetLocalGroupEnum(
  [in]      LPCWSTR    servername,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resumehandle
);

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
0	Devuelve nombres de grupo locales. El parámetro bufptr apunta a una matriz de estructuras de LOCALGROUP_INFO_0 .
1	Devuelve nombres de grupo locales y el comentario asociado a cada grupo. El parámetro bufptr apunta a una matriz de estructuras de LOCALGROUP_INFO_1 .

[out] bufptr

Puntero a la dirección del búfer que recibe la estructura de información. 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

Especifica la longitud máxima preferida de los datos devueltos, en bytes. Si especifica MAX_PREFERRED_LENGTH, la función 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 aproximado de entradas que se podrían haber enumerado a partir de la posición de reanudación actual. El número total de entradas es solo una sugerencia. Para obtener más información sobre cómo determinar el número exacto de entradas, vea la sección Comentarios siguiente.

[in, out] resumehandle

Puntero a un valor que contiene un identificador de reanudación que se usa para continuar con una búsqueda de grupo local 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. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

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
ERROR_ACCESS_DENIED	El usuario no tiene acceso a la información pedida.
ERROR_MORE_DATA	Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas.
NERR_InvalidComputer	El nombre de equipo no es válido.
NERR_BufTooSmall	El búfer de retorno es demasiado pequeño.

Comentarios

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.

La función 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.

Para determinar el número total exacto de grupos locales, debe enumerar todo el árbol, lo que puede ser una operación costosa. Para enumerar todo el árbol, use el parámetro resumehandle para continuar con la enumeración de llamadas consecutivas y use el parámetro entriesread para acumular el número total de grupos locales. Si la aplicación se comunica con un controlador de dominio, debe considerar la posibilidad de usar el 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.

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.

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 del grupo local de administración de red. Para obtener más información, consulte IADsGroup.

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