NetUserGetLocalGroups, fonction (lmaccess.h)
La fonction NetUserGetLocalGroups récupère une liste de groupes locaux auxquels appartient un utilisateur spécifié.
Syntaxe
NET_API_STATUS NET_API_FUNCTION NetUserGetLocalGroups(
[in] LPCWSTR servername,
[in] LPCWSTR username,
[in] DWORD level,
[in] DWORD flags,
[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 pour lequel retourner les informations d’appartenance au groupe local. Si la chaîne est de la forme DomainName\UserName , le nom d’utilisateur est censé être trouvé sur ce domaine. Si la chaîne est de la forme UserName, le nom d’utilisateur doit être trouvé sur le serveur spécifié par le paramètre servername . Pour plus d'informations, consultez la section Notes.
[in] level
Niveau d’informations des données. Ce paramètre peut être la valeur suivante.
| Valeur | Signification |
|---|---|
|
Retourne les noms des groupes locaux auxquels l’utilisateur appartient. Le paramètre bufptr pointe vers un tableau de structures LOCALGROUP_USERS_INFO_0 . |
[in] flags
Masque de bits d’indicateurs qui affectent l’opération. Actuellement, seule la valeur définie est LG_INCLUDE_INDIRECT. Si ce bit est défini, la fonction retourne également les noms des groupes locaux dont l’utilisateur est indirectement membre (autrement dit, l’utilisateur est membre d’un groupe global qui est lui-même membre d’un ou de plusieurs groupes locaux).
[out] bufptr
Pointeur vers la mémoire tampon qui reçoit les données. 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
Longueur maximale préférée, en octets, des données retournées. Si MAX_PREFERRED_LENGTH est spécifié dans ce paramètre, 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 é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.
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. Cette erreur est également retournée si le paramètre servername a un vide de fin. |
|
Le niveau d’appel système est incorrect. Cette erreur est retournée si le paramètre de niveau n’a pas été spécifié comme 0. |
|
Un paramètre est incorrect. Cette erreur est retournée si le paramètre flags contient une valeur autre que LG_INCLUDE_INDIRECT. |
|
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. |
|
Le contrôleur de domaine est introuvable. |
|
L’utilisateur est introuvable. Cette erreur est retournée si le nom d’utilisateur est introuvable. |
|
Le serveur RPC est indisponible. Cette erreur est retournée si le paramètre servername 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 Domain est utilisé pour effectuer l’case activée d’accès pour cette fonction. L’appelant doit disposer de l’autorisation Read Property sur l’objet Domain.
Pour récupérer une liste de groupes globaux auxquels appartient un utilisateur spécifié, vous pouvez appeler la fonction NetUserGetGroups .
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 des groupes locaux auxquels appartient un utilisateur avec un appel à la fonction NetUserGetLocalGroups . L’exemple appelle NetUserGetLocalGroups, en spécifiant le niveau d’informations 0 (LOCALGROUP_USERS_INFO_0). L’exemple effectue une boucle dans les entrées et imprime le nom de chaque groupe local auquel l’utilisateur est membre. Si toutes les entrées disponibles ne sont pas énumérées, il imprime également le nombre d’entrées réellement énumérées et le nombre total d’entrées disponibles. Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon d’informations.
#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[])
{
LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
DWORD dwLevel = 0;
DWORD dwFlags = LG_INCLUDE_INDIRECT ;
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 NetUserGetLocalGroups function
// specifying information level 0.
//
// The LG_INCLUDE_INDIRECT flag specifies that the
// function should also return the names of the local
// groups in which the user is indirectly a member.
//
nStatus = NetUserGetLocalGroups(argv[1],
argv[2],
dwLevel,
dwFlags,
(LPBYTE *) &pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries);
//
// If the call succeeds,
//
if (nStatus == NERR_Success)
{
LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
DWORD i;
DWORD dwTotalCount = 0;
if ((pTmpBuf = pBuf) != NULL)
{
fprintf(stderr, "\nLocal group(s):\n");
//
// Loop through the entries and
// print the names of the local 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->lgrui0_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 memory.
//
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 |