Função NetLocalGroupGetMembers (lmaccess.h)

Artigo
08/24/2023

A função NetLocalGroupGetMembers recupera uma lista dos membros de um grupo local específico no banco de dados de segurança, que é o banco de dados SAM (gerenciador de contas de segurança) ou, no caso de controladores de domínio, o Active Directory. Os membros do grupo local podem ser usuários ou grupos globais.

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetLocalGroupGetMembers(
  [in]      LPCWSTR    servername,
  [in]      LPCWSTR    localgroupname,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resumehandle
);

Parâmetros

[in] servername

Ponteiro para uma cadeia de caracteres constante que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

[in] localgroupname

Ponteiro para uma cadeia de caracteres constante que especifica o nome do grupo local cujos membros devem ser listados. Para obter mais informações, consulte a seção Comentários a seguir.

[in] level

Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
0	Retornar o SID ( identificador de segurança ) associado ao membro do grupo local. O parâmetro bufptr aponta para uma matriz de estruturas LOCALGROUP_MEMBERS_INFO_0 .
1	Retornar o SID e as informações da conta associadas ao membro do grupo local. O parâmetro bufptr aponta para uma matriz de estruturas LOCALGROUP_MEMBERS_INFO_1 .
2	Retornar o SID, as informações da conta e o nome de domínio associado ao membro do grupo local. O parâmetro bufptr aponta para uma matriz de estruturas LOCALGROUP_MEMBERS_INFO_2 .
3	Retornar os nomes de conta e domínio do membro do grupo local. O parâmetro bufptr aponta para uma matriz de estruturas LOCALGROUP_MEMBERS_INFO_3 .

[out] bufptr

Ponteiro para o endereço que recebe a estrutura de informações de retorno. O formato desses dados depende do valor do parâmetro level . Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree . Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA.

[in] prefmaxlen

Especifica o comprimento máximo preferencial dos dados retornados, em bytes. Se você especificar MAX_PREFERRED_LENGTH, a função alocará a quantidade de memória necessária para os dados. Se você especificar outro valor nesse parâmetro, ele poderá restringir o número de bytes retornados pela função. Se o tamanho do buffer for insuficiente para manter todas as entradas, a função retornará ERROR_MORE_DATA. Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.

[out] entriesread

Ponteiro para um valor que recebe a contagem de elementos realmente enumerados.

[out] totalentries

Ponteiro para um valor que recebe o número total de entradas que poderiam ter sido enumeradas da posição de currículo atual.

[in, out] resumehandle

Ponteiro para um valor que contém um identificador de retomada que é usado para continuar uma pesquisa de membro do grupo existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se esse parâmetro for NULL, nenhum identificador de retomada será armazenado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O usuário não tem acesso às informações solicitadas.
NERR_InvalidComputer	O nome do computador é inválido.
ERROR_MORE_DATA	Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas.
ERROR_NO_SUCH_ALIAS	O grupo local especificado não existe.

Comentários

Se você chamar essa função em um controlador de domínio que está executando o Active Directory, o acesso será permitido ou negado com base na ACL (lista de controle de acesso) do objeto protegível. A ACL padrão permite que todos os usuários autenticados e membros do grupo "Acesso compatível com o Pré-Windows 2000" exibam as informações. Se você chamar essa função em um servidor membro ou estação de trabalho, todos os usuários autenticados poderão exibir as informações. Para obter informações sobre acesso anônimo e restringir o acesso anônimo nessas plataformas, consulte Requisitos de segurança para as funções de gerenciamento de rede. Para obter mais informações sobre ACLs, ACEs e tokens de acesso, consulte Controle de Acesso Model.

O descritor de segurança do objeto LocalGroup é usado para executar a marcar de acesso para essa função.

Os nomes de conta de usuário são limitados a 20 caracteres e os nomes de grupo são limitados a 256 caracteres. Além disso, os nomes de conta não podem ser encerrados por um período e não podem incluir vírgulas ou qualquer um dos seguintes caracteres imprimíveis: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Os nomes também não podem incluir caracteres no intervalo de 1 a 31, que são não imprimíveis.

Se você estiver programando para o Active Directory, poderá chamar determinados métodos ADSI (Active Directory Service Interface) para obter a mesma funcionalidade que você pode obter chamando as funções de grupo local de gerenciamento de rede. Para obter mais informações, consulte IADsGroup.

Se essa função retornar ERROR_MORE_DATA, ela deverá ser chamada repetidamente até que ERROR_SUCCESS ou NERR_success seja retornado. A falha ao fazer isso pode resultar em um vazamento de conexão RPC.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmaccess.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll