NetLocalGroupAdd, fonction (lmaccess.h)

Article
08/24/2023

La fonction NetLocalGroupAdd crée un groupe local dans la base de données de sécurité, qui est la base de données du gestionnaire de comptes de sécurité (SAM) ou, dans le cas des contrôleurs de domaine, Active Directory.

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetLocalGroupAdd(
  [in]  LPCWSTR servername,
  [in]  DWORD   level,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

Paramètres

[in] servername

Pointeur vers une chaîne 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

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

Valeur	Signification
0	Nom du groupe local. Le paramètre buf pointe vers une structure LOCALGROUP_INFO_0 .
1	Un nom de groupe local et un commentaire à associer au groupe. Le paramètre buf pointe vers une structure LOCALGROUP_INFO_1 .

[in] buf

Pointeur vers une mémoire tampon qui contient la structure d’informations de groupe local. Le format de ces données dépend de la valeur du paramètre level . Pour plus d’informations, consultez Mémoires tampons de fonction de gestion réseau.

[out] parm_err

Pointeur vers une valeur qui reçoit l’index du premier membre de la structure d’informations de groupe local pour provoquer l’erreur ERROR_INVALID_PARAMETER. Si ce paramètre a la valeur NULL, l’index n’est pas retourné en cas d’erreur. Pour plus d’informations, consultez la section Notes dans la rubrique NetLocalGroupSetInfo .

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’appelant n’a pas l’accès approprié pour terminer l’opération.
ERROR_ALIAS_EXISTS	Le groupe local spécifié existe déjà. Cette erreur est retournée si le membre du nom de groupe dans la structure vers laquelle pointe le paramètre buf est déjà utilisé en tant qu’alias.
ERROR_INVALID_LEVEL	Un paramètre de niveau n’est pas valide.
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si un ou plusieurs des membres de la structure pointés vers par le paramètre buf ne sont pas valides.
NERR_GroupExists	Le nom du groupe existe. Cette erreur est retournée si le membre du nom de groupe dans la structure pointée par le paramètre buf est déjà utilisé comme nom de groupe.
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_UserExists	Le nom d’utilisateur existe. Cette erreur est retournée si le membre du nom de groupe dans la structure pointée par le paramètre buf est déjà utilisé comme nom d’utilisateur.

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) pour 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 ou une station de travail membre, 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 ACL, les ACL et les jetons d’accès, consultez modèle Access Control.

Le descripteur de sécurité du conteneur utilisateur est utilisé pour effectuer l’case activée d’accès pour cette fonction. L’appelant doit être en mesure de créer des objets enfants de la classe de groupe.

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.

Si la fonction NetLocalGroupAdd retourne ERROR_INVALID_PARAMETER et qu’aucun pointeur NULL n’a été passé dans parm_err paramètre, le paramètre parm_err indique que le premier membre de la structure d’informations de groupe local n’est pas valide. Le format de la structure d’informations de groupe local est spécifié dans le paramètre level . Un pointeur vers la structure d’informations de groupe local est passé dans le paramètre buf . Le tableau suivant répertorie les valeurs qui peuvent être retournées dans le paramètre parm_err et le membre de structure correspondant qui est en erreur.

Valeur	Membre
LOCALGROUP_NAME_PARMNUM	Si le paramètre level était 0, le membre lgrpi0_name de la structure LOCALGROUP_INFO_0 n’était pas valide. Si le paramètre level était 1, le membre lgrpi1_name de la structure LOCALGROUP_INFO_1 n’était pas valide.
LOCALGROUP_COMMENT_PARMNUM	Si le paramètre level était 1, le membre lgrpi1_comment de la structure LOCALGROUP_INFO_1 n’était pas valide.

Lorsque vous effectuez des requêtes auprès d’un contrôleur de domaine et d’Active Directory, vous pouvez appeler certaines méthodes ADSI (Active Directory Service Interface) pour obtenir les mêmes résultats que 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