Función NetUserSetGroups (lmaccess.h)

Artículo
08/24/2023

La función NetUserSetGroups establece pertenencias a grupos globales para una cuenta de usuario especificada.

Sintaxis

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

Parámetros

[in] servername

Puntero a una cadena constante que especifica el nombre DNS o NetBIOS del servidor remoto en el que se va a ejecutar la función. Si este parámetro es NULL, se usa el equipo local.

[in] username

Puntero a una cadena constante que especifica el nombre del usuario para el que se van a establecer pertenencias a grupos globales. Para obtener más información, vea la sección Comentarios.

[in] level

Nivel de información de los datos. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
0	El parámetro buf apunta a una matriz de estructuras de GROUP_USERS_INFO_0 que especifica nombres de grupo globales.
1	El parámetro buf apunta a una matriz de estructuras de GROUP_USERS_INFO_1 que especifica nombres de grupo globales con atributos.

[in] buf

Puntero al búfer que especifica los datos. Para obtener más información, consulte Búferes de funciones de administración de redes.

[in] num_entries

Número de entradas contenidas en la matriz a las que apunta el parámetro buf .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se NERR_Success.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El usuario no tiene acceso a la información pedida.
ERROR_INVALID_LEVEL	El nivel de llamada del sistema no es válido. Este error se devuelve si el parámetro level se especificó como un valor distinto de 0 o 1.
ERROR_INVALID_PARAMETER	Un parámetro pasado no era válido. Este error se devuelve si el parámetro num_entries no era válido.
ERROR_NOT_ENOUGH_MEMORY	La memoria insuficiente estaba disponible para completar la operación.
NERR_InvalidComputer	El nombre de equipo no es válido.
NERR_NotPrimary	La operación solo se permite en el controlador de dominio principal del dominio.
NERR_GroupNotFound	El nombre del grupo especificado por el grui0_name de la estructura GROUP_USERS_INFO_0 o grui1_name miembro de la estructura GROUP_USERS_INFO_1 apuntado por el parámetro buf no existe.
NERR_InternalError	Se ha producido un error interno.
NERR_UserNotFound	No se encontró el nombre de usuario.

Comentarios

Si está programando para Active Directory, puede llamar a determinados métodos de interfaz de servicio de Active Directory (ADSI) para lograr la misma funcionalidad que puede lograr llamando a las funciones de usuario de administración de red. Para obtener más información, consulte IADsUser e IADsComputer.

Si llama a esta función en un controlador de dominio que ejecuta Active Directory, se permite o se deniega el acceso en función de la lista de control de acceso (ACL) para el objeto protegible. La ACL predeterminada permite que solo los administradores de dominio y los operadores de cuenta llamen a esta función. En un servidor miembro o estación de trabajo, solo los administradores y los usuarios avanzados pueden llamar a esta función. Para obtener más información, consulte Requisitos de seguridad para las funciones de administración de red. Para obtener más información sobre las ACL, los ACL y los tokens de acceso, consulte Access Control Model.

El descriptor de seguridad del objeto User se usa para realizar la comprobación de acceso de esta función.

Para conceder a un usuario la pertenencia a un grupo global existente, puede llamar a la función NetGroupAddUser .

Los nombres de cuenta de usuario están limitados a 20 caracteres y los nombres de grupo están limitados a 256 caracteres. Además, los nombres de cuenta no se pueden terminar por un punto y no pueden incluir comas ni ninguno de los siguientes caracteres imprimibles: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Los nombres tampoco pueden incluir caracteres en el intervalo 1-31, que no son imprimibles.

Ejemplos

En el ejemplo de código siguiente se muestra cómo establecer pertenencias a grupos globales para una cuenta de usuario con una llamada a la función NetUserSetGroups . El ejemplo de código rellena el miembro grui0_name de la estructura GROUP_USERS_INFO_0 y llama a NetUserSetGroups, especificando el nivel de información 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;
}

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	lmaccess.h (include Lm.h)
Library	Netapi32.lib
Archivo DLL	Netapi32.dll