NetQueryDisplayInformation, fonction (lmaccess.h)
La fonction NetQueryDisplayInformation renvoie des informations de compte d’utilisateur, d’ordinateur ou 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 |
|---|---|
|
Retourner les informations de compte d’utilisateur. Le paramètre SortedBuffer pointe vers un tableau de structures NET_DISPLAY_USER . |
|
Retourner les informations de l’ordinateur individuel. Le paramètre SortedBuffer pointe vers un tableau de structures NET_DISPLAY_MACHINE . |
|
Retourner les informations de 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ées 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 et les rubriques Network Management Function Buffers et Network Management Function Buffers Lengths.
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 |
|---|---|
|
L’utilisateur n’a pas accès aux informations demandées. |
|
Le paramètre Level spécifie une valeur non valide. |
|
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 next_index membre de la dernière entrée dans SortedBuffer. Notez que vous ne devez pas utiliser la valeur du membre next_index à quelque fin que ce soit, sauf pour récupérer davantage 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 membres du groupe « Accès compatible pré-Windows 2000 » d’afficher les informations. Si vous appelez cette fonction sur un serveur ou une station de travail membre, 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 du réseau. Pour plus d’informations sur les ACL, les ACL et les jetons d’accès, consultez modèle Access Control.
La fonction NetQueryDisplayInformation retourne uniquement les informations auxquelles l’appelant dispose d’un accès en lecture. L’appelant doit avoir un accès List Contents à l’objet Domain et énumérer l’accès au domaine SAM entier sur l’objet SERVEUR SAM situé dans le conteneur Système.
Les fonctions NetQueryDisplayInformation et NetGetDisplayInformationIndex fournissent un mécanisme efficace pour l’énumération des comptes d’utilisateurs et de groupes. Lorsque cela est 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 du 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’intégralité 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 pour Active Directory, vous pouvez peut-être 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 de 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 |