Función NetQueryDisplayInformation (lmaccess.h)

Artículo
03/09/2023

La función NetQueryDisplayInformation devuelve información de cuenta de usuario, equipo o cuenta de grupo. Llame a esta función para enumerar rápidamente la información de la cuenta para mostrarla en las interfaces de usuario.

Sintaxis

NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
  [in]  LPCWSTR ServerName,
  [in]  DWORD   Level,
  [in]  DWORD   Index,
  [in]  DWORD   EntriesRequested,
  [in]  DWORD   PreferredMaximumLength,
  [out] LPDWORD ReturnedEntryCount,
  [out] PVOID   *SortedBuffer
);

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
1	Devuelve información de la cuenta de usuario. El parámetro SortedBuffer apunta a una matriz de estructuras de NET_DISPLAY_USER .
2	Devuelve información de equipo individual. El parámetro SortedBuffer apunta a una matriz de estructuras NET_DISPLAY_MACHINE .
3	Devuelve información de la cuenta de grupo. El parámetro SortedBuffer apunta a una matriz de estructuras de NET_DISPLAY_GROUP .

[in] Index

Especifica el índice de la primera entrada para la que se va a recuperar información. Especifique cero para recuperar la información de la cuenta a partir de la primera entrada de información para mostrar. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in] EntriesRequested

Especifica el número máximo de entradas para las que se va a recuperar información. En Windows 2000 y versiones posteriores, cada llamada a NetQueryDisplayInformation devuelve un máximo de 100 objetos.

[in] PreferredMaximumLength

Especifica el tamaño máximo preferido, en bytes, del búfer asignado por el sistema devuelto en el parámetro SortedBuffer . Se recomienda establecer este parámetro en MAX_PREFERRED_LENGTH.

[out] ReturnedEntryCount

Puntero a un valor que recibe el número de entradas del búfer devuelto en el parámetro SortedBuffer . Si este parámetro es cero, no hay entradas con un índice tan grande como se especificó. Las entradas se pueden devolver cuando el valor devuelto de la función es NERR_Success o ERROR_MORE_DATA.

[out] SortedBuffer

Puntero a un búfer que recibe un puntero a un búfer asignado por el sistema que especifica una lista ordenada de la información solicitada. El formato de estos datos depende del valor del parámetro Level . Dado que el sistema asigna este búfer, 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. Para obtener más información, consulte la siguiente sección Valores devueltos y los temas Búferes de funciones de administración de red y Longitudes de búferes de función de administración de red.

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 es 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_INVALID_LEVEL	El parámetro Level especifica un valor no válido.
ERROR_MORE_DATA	Hay más entradas disponibles. Es decir, la última entrada devuelta en el parámetro SortedBuffer no es la última entrada disponible. Para recuperar entradas adicionales, vuelva a llamar a NetQueryDisplayInformation con el parámetro Index establecido en el valor devuelto en el miembro next_index de la última entrada en SortedBuffer. Tenga en cuenta que no debe usar el valor del miembro next_index para ningún propósito, excepto para recuperar más datos con llamadas adicionales a NetQueryDisplayInformation.

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 redes. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Modelo.

La función NetQueryDisplayInformation solo devuelve información a la que el autor de la llamada tiene acceso de lectura. El autor de la llamada debe tener acceso a List Contents al objeto Domain y Enumerar todo el acceso de dominio SAM en el objeto SAM Server ubicado en el contenedor System.

Las funciones NetQueryDisplayInformation y NetGetDisplayInformationIndex proporcionan un mecanismo eficaz para enumerar cuentas de usuario y grupo. Cuando sea posible, use estas funciones en lugar de la función NetUserEnum o la función NetGroupEnum .

Para enumerar dominios de confianza o cuentas de equipo miembro, llame a NetUserEnum y especifique el valor de filtro adecuado para obtener la información de la cuenta que necesita. Para enumerar dominios de confianza, llame a la función LsaEnumerateTrustedDomains o LsaEnumerateTrustedDomainsEx .

El número de entradas devueltas por esta función depende del descriptor de seguridad ubicado en el objeto de dominio raíz. La API devolverá las primeras 100 entradas o todo el conjunto de entradas del dominio, en función de los privilegios de acceso del usuario. La ACE que se usa para controlar este comportamiento es "SAM-Enumerate-Entire-Domain" y se concede a los usuarios autenticados de forma predeterminada. Los administradores pueden modificar esta configuración para permitir a los usuarios enumerar todo el dominio.

Cada llamada a NetQueryDisplayInformation devuelve un máximo de 100 objetos. Llamar a la función NetQueryDisplayInformation para enumerar la información de la cuenta de dominio puede ser costosa en términos de rendimiento. Si está programando para Active Directory, es posible que pueda usar métodos en la interfaz IDirectorySearch para realizar consultas paginadas en el dominio. Para obtener más información, vea IDirectorySearch::SetSearchPreference e IDirectorySearch::ExecuteSearch. Para enumerar dominios de confianza, llame a la función LsaEnumerateTrustedDomainsEx .

Ejemplos

En el ejemplo de código siguiente se muestra cómo devolver información de la cuenta de grupo mediante una llamada a la función NetQueryDisplayInformation . Si el usuario especifica un nombre de servidor, el ejemplo llama primero a la función MultiByteToWideChar para convertir el nombre en Unicode. El ejemplo llama a NetQueryDisplayInformation, especificando el nivel de información 3 (NET_DISPLAY_GROUP) para recuperar la información de la cuenta de grupo. Si hay entradas que se van a devolver, el ejemplo devuelve los datos e imprime la información del grupo. Por último, el ejemplo de código libera la memoria asignada para el búfer de información.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>
#include <lm.h>

#pragma comment(lib, "netapi32.lib")

void main( int argc, char *argv[ ] )
{
   PNET_DISPLAY_GROUP pBuff, p;
   DWORD res, dwRec, i = 0;
   //
   // You can pass a NULL or empty string
   //  to retrieve the local information.
   //
   TCHAR szServer[255]=TEXT(""); 

   if(argc > 1) 
      //
      // Check to see if a server name was passed;
      //  if so, convert it to Unicode.
      //
      MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255); 

   do // begin do
   { 
      //
      // Call the NetQueryDisplayInformation function;
      //   specify information level 3 (group account information).
      //
      res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
      //
      // If the call succeeds,
      //
      if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
      {
         p = pBuff;
         for(;dwRec>0;dwRec--)
         {
            //
            // Print the retrieved group information.
            //
            printf("Name:      %S\n"
                  "Comment:   %S\n"
                  "Group ID:  %u\n"
                  "Attributes: %u\n"
                  "--------------------------------\n",
                  p->grpi3_name,
                  p->grpi3_comment,
                  p->grpi3_group_id,
                  p->grpi3_attributes);
            //
            // If there is more data, set the index.
            //
            i = p->grpi3_next_index;
            p++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pBuff);
      }
      else
         printf("Error: %u\n", res);
   //
   // Continue while there is more data.
   //
   } while (res==ERROR_MORE_DATA); // end do
   return;
}

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