NetUserGetGroups, fonction (lmaccess.h)
La fonction NetUserGetGroups récupère une liste de groupes globaux auxquels appartient un utilisateur spécifié.
Syntaxe
NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries
);
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] username
Pointeur vers une chaîne constante qui spécifie le nom de l’utilisateur à rechercher dans chaque compte de groupe. Pour plus d'informations, consultez la section Notes qui suit.
[in] level
Niveau d’informations des données demandées. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Retourne les noms des groupes globaux auxquels l’utilisateur appartient. Le paramètre bufptr pointe vers un tableau de structures GROUP_USERS_INFO_0 . |
|
Retourne les noms des groupes globaux auxquels l’utilisateur appartient avec des attributs. Le paramètre bufptr pointe vers un tableau de structures GROUP_USERS_INFO_1 . |
[out] bufptr
Pointeur vers la mémoire tampon qui reçoit les données. 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
Longueur maximale préférée, en octets, des données retournées. Si MAX_PREFERRED_LENGTH est spécifié, la fonction alloue la quantité de mémoire requise pour les données. Si une autre valeur est spécifiée 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 récupérés.
[out] totalentries
Pointeur vers une valeur qui reçoit le nombre total d’entrées qui auraient pu être récupérées.
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 ne dispose pas de droits d’accès aux informations demandées. |
|
Le chemin d’accès réseau est introuvable. Cette erreur est retournée si le paramètre servername est introuvable. |
|
Le niveau d’appel système est incorrect. Cette erreur est retournée si le paramètre de niveau a été spécifié sous la forme d’une valeur autre que 0 ou 1. |
|
La syntaxe du nom est incorrecte. Cette erreur est retournée si le paramètre servername a des vides de début ou de fin ou contient un caractère non valide. |
|
D’autres entrées sont disponibles. Spécifiez une mémoire tampon suffisamment grande pour recevoir toutes les entrées. |
|
La mémoire disponible était insuffisante pour terminer l’opération. |
|
Une erreur interne s’est produite. |
|
L’utilisateur est introuvable. Cette erreur est retournée si le nom d’utilisateur est introuvable. |
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 utilisateur de gestion réseau. Pour plus d’informations, consultez IADsUser et IADsComputer.
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.
Le descripteur de sécurité de l’objet User est utilisé pour effectuer l’case activée d’accès pour cette fonction.
Pour récupérer la liste des groupes locaux auxquels appartient un utilisateur, vous pouvez appeler la fonction NetUserGetLocalGroups . Les groupes réseau sont séparés et distincts des groupes système Windows NT.
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.
Exemples
L’exemple de code suivant montre comment récupérer une liste de groupes globaux auxquels un utilisateur appartient avec un appel à la fonction NetUserGetGroups . L’exemple appelle NetUserGetGroups, en spécifiant le niveau d’informations 0 ( GROUP_USERS_INFO_0). Le code effectue une boucle dans les entrées et imprime le nom des groupes globaux dans lesquels l’utilisateur est membre. L’exemple affiche également le nombre total d’entrées disponibles et le nombre d’entrées réellement énumérées si elles ne correspondent pas. Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
NET_API_STATUS nStatus;
if (argc != 3)
{
fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
exit(1);
}
//
// Call the NetUserGetGroups function, specifying level 0.
//
nStatus = NetUserGetGroups(argv[1],
argv[2],
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nGlobal group(s):\n");
//
// Loop through the entries;
// print the name of the global groups
// to which the user belongs.
//
for (i = 0; i < dwEntriesRead; i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
wprintf(L"\t-- %s\n", pTmpBuf->grui0_name);
pTmpBuf++;
dwTotalCount++;
}
}
//
// If all available entries were
// not enumerated, print the number actually
// enumerated and the total number available.
//
if (dwEntriesRead < dwTotalEntries)
fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
//
// Otherwise, just print the total.
//
printf("\nEntries enumerated: %d\n", dwTotalCount);
}
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
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 |