NetLocalGroupEnum, fonction (lmaccess.h)

Article
03/09/2023

La fonction NetLocalGroupEnum retourne des informations sur chaque compte de groupe local sur le serveur spécifié.

Syntaxe

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

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
0	Retourne les noms de groupes locaux. Le paramètre bufptr pointe vers un tableau de structures LOCALGROUP_INFO_0 .
1	Retourne les noms de groupes locaux et le commentaire associé à chaque groupe. Le paramètre bufptr pointe vers un tableau de structures LOCALGROUP_INFO_1 .

[out] bufptr

Pointeur vers l’adresse de la mémoire tampon qui reçoit la structure d’informations. Le format de ces données dépend de la valeur du paramètre de niveau . Cette mémoire tampon est allouée par le système et 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.

[in] prefmaxlen

Spécifie la longueur maximale préférée des données retournées, en octets. Si vous spécifiez MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire requise pour 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 gestion ré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 approximatif d’entrées qui auraient pu être énumérées à partir de la position actuelle du CV. 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] resumehandle

Pointeur vers une valeur qui contient un handle de CV utilisé pour poursuivre une recherche de groupe local existante. Le handle doit être égal à zéro lors du premier appel et rester inchangé pour les appels suivants. Si ce paramètre a la valeur NULL, aucun handle de reprise n’est stocké. Pour plus d'informations, consultez la section Notes qui suit.

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
ERROR_ACCESS_DENIED	L’utilisateur n’a pas accès aux informations demandées.
ERROR_MORE_DATA	D’autres entrées sont disponibles. Spécifiez une mémoire tampon suffisamment grande pour recevoir toutes les entrées.
NERR_InvalidComputer	Le nom d'ordinateur est non valide.
NERR_BufTooSmall	La mémoire tampon de retour est trop petite.

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) de 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 listes de contrôle d’accès, les ACL et les jetons d’accès, consultez Access Control Modèle.

La fonction retourne uniquement les informations auxquelles l’appelant dispose d’un accès en lecture. L’appelant doit disposer d’un accès List Contents à l’objet Domain et énumérer l’accès au domaine SAM entier sur l’objet SAM Server situé dans le conteneur Système.

Pour déterminer le nombre total exact de groupes locaux, 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 resumehandle pour continuer l’énumération pour les appels consécutifs et utilisez le paramètre entriesread pour accumuler le nombre total de groupes locaux. 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 groupes sont limités à 256 caractères. En outre, les noms de compte ne peuvent pas être terminés par un point et ils ne peuvent pas inclure de virgules ou d’aucun des caractères imprimables suivants : « , /, , , [, ], :, |, <, , >+, =, ;, ?, *. Les noms ne peuvent pas non plus inclure des caractères de la plage 1 à 31, qui ne sont pas imprimables.

Si vous programmez pour Active Directory, vous pourrez 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 local de gestion réseau. Pour plus d’informations, consultez IADsGroup.

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