NetGroupEnum, fonction (lmaccess.h)
La fonction NetGroupEnum récupère des informations sur chaque groupe global de la base de données de sécurité, qui est la base de données du gestionnaire des comptes de sécurité (SAM) ou, dans le cas des contrôleurs de domaine, Active Directory.
La fonction NetQueryDisplayInformation fournit un mécanisme efficace pour l’énumération des groupes globaux. Lorsque cela est possible, il est recommandé d’utiliser NetQueryDisplayInformation au lieu de la fonction NetGroupEnum .
Syntaxe
NET_API_STATUS NET_API_FUNCTION NetGroupEnum(
[in] LPCWSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] PDWORD_PTR resume_handle
);
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 |
|---|---|
|
Retourne le nom du groupe global. Le paramètre bufptr pointe vers un tableau de structures GROUP_INFO_0 . |
|
Retourne le nom du groupe global et un commentaire. Le paramètre bufptr pointe vers un tableau de structures GROUP_INFO_1 . |
|
Retourne des informations détaillées sur le groupe global. Le paramètre bufptr pointe vers un tableau de structures GROUP_INFO_2 . Notez que sur Windows XP et versions ultérieures, il est recommandé d’utiliser GROUP_INFO_3 à la place. |
|
Retourne des informations détaillées sur le groupe global. Le paramètre bufptr pointe vers un tableau de structures GROUP_INFO_3 .
Windows 2000 : Ce niveau n’est pas pris en charge. |
[out] bufptr
Pointeur vers la mémoire tampon pour recevoir la structure d’informations de groupe globale. Le format de ces données dépend de la valeur du paramètre level .
Le système alloue la mémoire pour cette mémoire tampon. Vous devez appeler la fonction NetApiBufferFree pour libérer la mémoire. Notez que vous devez libérer la mémoire tampon même si la fonction échoue avec ERROR_MORE_DATA.
[in] prefmaxlen
Spécifie la longueur maximale par défaut des données retournées, en octets. Si vous spécifiez MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire nécessaire pour contenir les données. Si vous spécifiez une autre valeur dans ce paramètre, cela peut limiter le nombre d’octets retournés par la fonction. Si la taille de la mémoire tampon est insuffisante pour contenir toutes les entrées, la fonction retourne ERROR_MORE_DATA. Pour plus d’informations, consultez Mémoires tampons de fonction de gestionréseau et Longueurs de mémoire tampon des fonctions de gestion réseau.
[out] entriesread
Pointeur vers une valeur qui reçoit le nombre d’éléments réellement énumérés.
[out] totalentries
Pointeur vers une valeur qui reçoit le nombre total d’entrées qui auraient pu être énumérées à partir de la position de reprise actuelle. Le nombre total d’entrées n’est qu’un indicateur. Pour plus d’informations sur la détermination du nombre exact d’entrées, consultez la section Remarques suivante.
[in, out] resume_handle
Pointeur vers une variable qui contient un handle de reprise utilisé pour poursuivre l’énumération de groupe global. Le handle doit être égal à zéro lors du premier appel et laisser inchangé pour les appels suivants. Si ce paramètre a la valeur NULL, aucun handle de reprise n’est stocké.
Valeur retournée
Si la fonction réussit, la valeur de retour est NERR_Success.
Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants.
| Code de retour | Description |
|---|---|
|
L’utilisateur n’a pas accès aux informations demandées. |
|
Le nom d'ordinateur est non valide. |
|
D’autres entrées sont disponibles. Spécifiez une mémoire tampon suffisamment grande pour recevoir toutes les entrées. |
Notes
Si vous programmez pour Active Directory, vous pouvez peut-être appeler certaines méthodes ADSI (Active Directory Service Interface) pour obtenir les mêmes fonctionnalités que celles que vous pouvez obtenir en appelant les fonctions de groupe d’administration réseau. Pour plus d’informations, consultez IADsGroup.
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 retourne uniquement les informations auxquelles l’appelant a 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.
Pour déterminer le nombre total exact de groupes, vous devez énumérer l’arborescence entière, ce qui peut être une opération coûteuse. Pour énumérer l’arborescence entière, utilisez le paramètre resume_handle pour poursuivre l’énumération pour les appels consécutifs et utilisez le paramètre entriesread pour accumuler le nombre total de groupes. Si votre application communique avec un contrôleur de domaine, vous devez envisager d’utiliser le fournisseur LDAP ADSI pour récupérer ce type de données plus efficacement. Le fournisseur LDAP ADSI implémente un ensemble d’objets ADSI qui prennent en charge différentes interfaces ADSI. Pour plus d’informations, consultez Fournisseurs de services ADSI.
Les noms de compte d’utilisateur sont limités à 20 caractères et les noms de groupe à 256 caractères. En outre, les noms de comptes ne peuvent pas être arrêtés par un point et ils ne peuvent pas inclure de virgules ou d’un des caractères imprimables suivants : « , /, , , [, ], :, |, <, , >+, =, ?, *. Les noms ne peuvent pas non plus inclure de caractères dans la plage 1 à 31, qui ne sont pas imprimables.
Spécifications
| 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 |