NetUserSetGroups, fonction (lmaccess.h)

Article
08/24/2023

La fonction NetUserSetGroups définit les appartenances de groupe globales pour un compte d’utilisateur spécifié.

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetUserSetGroups(
  [in] LPCWSTR servername,
  [in] LPCWSTR username,
  [in] DWORD   level,
  [in] LPBYTE  buf,
  [in] DWORD   num_entries
);

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 définir les appartenances au groupe global. Pour plus d'informations, consultez la section Notes.

[in] level

Niveau d’informations des données. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
0	Le paramètre buf pointe vers un tableau de structures GROUP_USERS_INFO_0 qui spécifie des noms de groupes globaux.
1	Le paramètre buf pointe vers un tableau de structures GROUP_USERS_INFO_1 qui spécifie des noms de groupes globaux avec des attributs.

[in] buf

Pointeur vers la mémoire tampon qui spécifie les données. Pour plus d’informations, consultez Mémoires tampons de fonction de gestion réseau.

[in] num_entries

Nombre d’entrées contenues dans le tableau pointé vers le paramètre buf .

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_INVALID_LEVEL	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.
ERROR_INVALID_PARAMETER	Un paramètre passé n’était pas valide. Cette erreur est retournée si le paramètre num_entries n’était pas valide.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour terminer l’opération.
NERR_InvalidComputer	Le nom d'ordinateur est non valide.
NERR_NotPrimary	L’opération est autorisée uniquement sur le contrôleur de domaine principal du domaine.
NERR_GroupNotFound	Le nom de groupe spécifié par le grui0_name dans la structure GROUP_USERS_INFO_0 ou grui1_name membre dans la structure GROUP_USERS_INFO_1 pointée par le paramètre buf n’existe pas.
NERR_InternalError	Une erreur interne s’est produite.
NERR_UserNotFound	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 autorise uniquement les administrateurs de domaine et les opérateurs de compte à appeler cette fonction. Sur un serveur membre ou une station de travail, seuls les administrateurs et les utilisateurs avec pouvoir peuvent appeler cette fonction. Pour plus d’informations, 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 accorder à un utilisateur l’appartenance à un groupe global existant, vous pouvez appeler la fonction NetGroupAddUser .

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 définir des appartenances à un groupe global pour un compte d’utilisateur avec un appel à la fonction NetUserSetGroups . L’exemple de code remplit le membre grui0_name de la structure GROUP_USERS_INFO_0 et appelle NetUserSetGroups, en spécifiant le niveau d’informations 0.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   GROUP_USERS_INFO_0 gi;
   NET_API_STATUS nStatus;

   if (argc != 4)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName GroupName\n", argv[0]);
      exit(1);
   }
   //
   // Fill in the GROUP_USERS_INFO_0 structure member.
   //
   gi.grui0_name = argv[3];
   //
   // Call the NetUserSetGroups function; specify level 0.
   //
   nStatus = NetUserSetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE)&gi,
                              1);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Group membership has been successful for %s\n", argv[2]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   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