NetQueryDisplayInformation, fonction (lmaccess.h)

La fonction NetQueryDisplayInformation retourne des informations sur le compte d’utilisateur, l’ordinateur ou le compte de groupe. Appelez cette fonction pour énumérer rapidement les informations de compte à afficher dans les interfaces utilisateur.

Syntaxe

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
);

Paramètres

[in] ServerName

Pointeur vers une chaîne constante qui spécifie le nom DNS ou NetBIOS du serveur distant sur lequel la fonction doit s’exécuter. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

[in] Level

Spécifie le niveau d’informations des données. Ce paramètre peut prendre les valeurs suivantes.

Valeur Signification
1
Retournez les informations du compte d’utilisateur. Le paramètre SortedBuffer pointe vers un tableau de structures NET_DISPLAY_USER .
2
Renvoyer des informations sur l’ordinateur individuel. Le paramètre SortedBuffer pointe vers un tableau de structures NET_DISPLAY_MACHINE .
3
Retourne les informations du compte de groupe. Le paramètre SortedBuffer pointe vers un tableau de structures NET_DISPLAY_GROUP .

[in] Index

Spécifie l’index de la première entrée pour laquelle récupérer des informations. Spécifiez zéro pour récupérer les informations de compte à partir de la première entrée d’informations d’affichage. Pour plus d'informations, consultez la section Notes qui suit.

[in] EntriesRequested

Spécifie le nombre maximal d’entrées pour lesquelles récupérer des informations. Sur Windows 2000 et versions ultérieures, chaque appel à NetQueryDisplayInformation retourne un maximum de 100 objets.

[in] PreferredMaximumLength

Spécifie la taille maximale préférée, en octets, de la mémoire tampon allouée par le système retournée dans le paramètre SortedBuffer . Il est recommandé de définir ce paramètre sur MAX_PREFERRED_LENGTH.

[out] ReturnedEntryCount

Pointeur vers une valeur qui reçoit le nombre d’entrées dans la mémoire tampon retournée dans le paramètre SortedBuffer . Si ce paramètre est égal à zéro, il n’existe aucune entrée avec un index aussi grand que celui spécifié. Les entrées peuvent être retournées lorsque la valeur de retour de la fonction est NERR_Success ou ERROR_MORE_DATA.

[out] SortedBuffer

Pointeur vers une mémoire tampon qui reçoit un pointeur vers une mémoire tampon allouée par le système qui spécifie une liste triée des informations demandées. Le format de ces données dépend de la valeur du paramètre Level . Étant donné que cette mémoire tampon est allouée par le système, elle doit être libérée à l’aide de la fonction NetApiBufferFree . Notez que vous devez libérer la mémoire tampon même si la fonction échoue avec ERROR_MORE_DATA. Pour plus d’informations, consultez la section Valeurs de retour suivantes, ainsi que les rubriques sur les mémoires tampons de fonction de gestion du réseau et les longueurs des tampons de fonction de gestion du réseau.

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour Description
ERROR_ACCESS_DENIED
L’utilisateur n’a pas accès aux informations demandées.
ERROR_INVALID_LEVEL
Le paramètre Level spécifie une valeur non valide.
ERROR_MORE_DATA
D’autres entrées sont disponibles. Autrement dit, la dernière entrée retournée dans le paramètre SortedBuffer n’est pas la dernière entrée disponible. Pour récupérer des entrées supplémentaires, appelez à nouveau NetQueryDisplayInformation avec le paramètre Index défini sur la valeur retournée dans le membre next_index de la dernière entrée dans SortedBuffer. Notez que vous ne devez pas utiliser la valeur du membre next_index à des fins quelconques, sauf pour récupérer plus de données avec des appels supplémentaires à NetQueryDisplayInformation.

Notes

Si vous appelez cette fonction sur un contrôleur de domaine qui exécute Active Directory, l’accès est autorisé ou refusé en fonction de la liste de contrôle d’accès (ACL) pour l’objet sécurisable. La liste de contrôle d’accès par défaut permet à tous les utilisateurs authentifiés et aux membres du groupe « Accès compatible pré-Windows 2000 » d’afficher les informations. Si vous appelez cette fonction sur un serveur membre ou une station de travail, tous les utilisateurs authentifiés peuvent afficher les informations. Pour plus d’informations sur l’accès anonyme et la restriction de l’accès anonyme sur ces plateformes, consultez Exigences de sécurité pour les fonctions de gestion réseau. Pour plus d’informations sur les ACL, les ACL et les jetons d’accès, consultez Access Control Modèle.

La fonction NetQueryDisplayInformation retourne uniquement les informations auxquelles l’appelant dispose d’un accès en lecture. L’appelant doit avoir accès au contenu de liste à l’objet Domaine et énumérer l’accès à l’ensemble du domaine SAM sur l’objet serveur SAM situé dans le conteneur système.

Les fonctions NetQueryDisplayInformation et NetGetDisplayInformationIndex fournissent un mécanisme efficace pour énumérer les comptes d’utilisateur et de groupe. Si possible, utilisez ces fonctions au lieu de la fonction NetUserEnum ou de la fonction NetGroupEnum .

Pour énumérer les domaines d’approbation ou les comptes d’ordinateurs membres, appelez NetUserEnum, en spécifiant la valeur de filtre appropriée pour obtenir les informations de compte dont vous avez besoin. Pour énumérer les domaines approuvés, appelez la fonction LsaEnumerateTrustedDomains ou LsaEnumerateTrustedDomainsEx .

Le nombre d’entrées retournées par cette fonction dépend du descripteur de sécurité situé sur l’objet de domaine racine. L’API retourne les 100 premières entrées ou l’ensemble complet d’entrées dans le domaine, en fonction des privilèges d’accès de l’utilisateur. L’ACE utilisé pour contrôler ce comportement est « SAM-Enumerate-Entire-Domain » et est accordé aux utilisateurs authentifiés par défaut. Les administrateurs peuvent modifier ce paramètre pour permettre aux utilisateurs d’énumérer l’ensemble du domaine.

Chaque appel à NetQueryDisplayInformation retourne un maximum de 100 objets. L’appel de la fonction NetQueryDisplayInformation pour énumérer les informations de compte de domaine peut être coûteux en termes de performances. Si vous programmez Active Directory, vous pouvez utiliser des méthodes sur l’interface IDirectorySearch pour effectuer des requêtes paginées sur le domaine. Pour plus d’informations, consultez IDirectorySearch::SetSearchPreference et IDirectorySearch::ExecuteSearch. Pour énumérer les domaines approuvés, appelez la fonction LsaEnumerateTrustedDomainsEx .

Exemples

L’exemple de code suivant montre comment retourner des informations de compte de groupe à l’aide d’un appel à la fonction NetQueryDisplayInformation . Si l’utilisateur spécifie un nom de serveur, l’exemple appelle d’abord la fonction MultiByteToWideChar pour convertir le nom en Unicode. L’exemple appelle NetQueryDisplayInformation, en spécifiant le niveau d’informations 3 (NET_DISPLAY_GROUP) pour récupérer les informations de compte de groupe. S’il existe des entrées à retourner, l’exemple retourne les données et imprime les informations du groupe. Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon d’informations.

#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;
}

Configuration requise

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête lmaccess.h (include Lm.h)
Bibliothèque Netapi32.lib
DLL Netapi32.dll

Voir aussi

Obtenir des fonctions

LsaEnumerateTrustedDomains

LsaEnumerateTrustedDomainsEx

NET_DISPLAY_GROUP

NET_DISPLAY_MACHINE

NET_DISPLAY_USER

NetGetDisplayInformationIndex

NetGroupEnum

NetUserEnum

Fonctions de gestion du réseau

Vue d’ensemble de la gestion du réseau