NetUserGetLocalGroups 함수(lmaccess.h)
NetUserGetLocalGroups 함수는 지정된 사용자가 속한 로컬 그룹 목록을 검색합니다.
구문
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
);
매개 변수
[in] servername
함수를 실행할 원격 서버의 DNS 또는 NetBIOS 이름을 지정하는 상수 문자열에 대한 포인터입니다. 이 매개 변수가 NULL이면 로컬 컴퓨터가 사용됩니다.
[in] username
로컬 그룹 멤버 자격 정보를 반환할 사용자의 이름을 지정하는 상수 문자열에 대한 포인터입니다. 문자열이 DomainName UserName\ 형식인 경우 해당 도메인에서 사용자 이름을 찾을 수 있습니다. 문자열이 UserName 형식인 경우 사용자 이름은 servername 매개 변수로 지정된 서버에서 찾을 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요.
[in] level
데이터의 정보 수준입니다. 이 매개 변수는 다음 값일 수 있습니다.
| 값 | 의미 |
|---|---|
|
사용자가 속한 로컬 그룹의 이름을 반환합니다. bufptr 매개 변수는 LOCALGROUP_USERS_INFO_0 구조체의 배열을 가리킵니다. |
[in] flags
작업에 영향을 주는 플래그의 비트 마스크입니다. 현재 정의된 값만 LG_INCLUDE_INDIRECT. 이 비트가 설정된 경우 함수는 사용자가 간접적으로 멤버인 로컬 그룹의 이름도 반환합니다(즉, 사용자가 하나 이상의 로컬 그룹의 멤버인 전역 그룹에 멤버 자격이 있음).
[out] bufptr
데이터를 수신하는 버퍼에 대한 포인터입니다. 이 데이터의 형식은 수준 매개 변수의 값에 따라 달라집니다. 이 버퍼는 시스템에서 할당되며 NetApiBufferFree 함수를 사용하여 해제해야 합니다. 함수가 ERROR_MORE_DATA 실패하더라도 버퍼를 해제해야 합니다.
[in] prefmaxlen
반환된 데이터의 기본 설정 최대 길이(바이트)입니다. 이 매개 변수에 MAX_PREFERRED_LENGTH 지정하면 함수는 데이터에 필요한 메모리 양을 할당합니다. 이 매개 변수에 다른 값을 지정하면 함수가 반환하는 바이트 수를 제한할 수 있습니다. 버퍼 크기가 모든 항목을 보유하기에 충분하지 않으면 함수는 ERROR_MORE_DATA 반환합니다. 자세한 내용은 네트워크 관리 함수 버퍼 및 네트워크관리 함수 버퍼 길이를 참조하세요.
[out] entriesread
실제로 열거된 요소 수를 수신하는 값에 대한 포인터입니다.
[out] totalentries
열거될 수 있는 총 항목 수를 수신하는 값에 대한 포인터입니다.
반환 값
함수가 성공하면 반환 값이 NERR_Success.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나일 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
사용자에게 요청된 정보에 대한 액세스 권한이 없습니다. servername 매개 변수에 후행 공백이 있는 경우에도 이 오류가 반환됩니다. |
|
시스템 호출 수준이 올바르지 않습니다. 수준 매개 변수가 0으로 지정되지 않은 경우 이 오류가 반환됩니다. |
|
매개 변수가 잘못되었습니다. flags 매개 변수에 LG_INCLUDE_INDIRECT 이외의 값이 포함된 경우 이 오류가 반환됩니다. |
|
더 많은 항목을 사용할 수 있습니다. 모든 항목을 수신할 수 있을 만큼 큰 버퍼를 지정합니다. |
|
메모리가 부족하여 작업을 완료할 수 없습니다. |
|
도메인 컨트롤러를 찾을 수 없습니다. |
|
사용자를 찾을 수 없습니다. 사용자 이름을 찾을 수 없는 경우 이 오류가 반환됩니다. |
|
RPC 서버를 사용할 수 없습니다. 서버 이름 매개 변수를 찾을 수 없는 경우 이 오류가 반환됩니다. |
설명
Active Directory를 프로그래밍하는 경우 특정 ADSI(Active Directory Service Interface) 메서드를 호출하여 네트워크 관리 사용자 함수를 호출하여 달성할 수 있는 동일한 기능을 달성할 수 있습니다. 자세한 내용은 IADsUser 및 IADsComputer를 참조하세요.
Active Directory를 실행하는 도메인 컨트롤러에서 이 함수를 호출하는 경우 보안 개체에 대한 ACL(액세스 제어 목록)에 따라 액세스가 허용되거나 거부됩니다. 기본 ACL은 "사전 Windows 2000 호환 액세스" 그룹의 모든 인증된 사용자와 멤버가 정보를 볼 수 있도록 허용합니다. 멤버 서버 또는 워크스테이션에서 이 함수를 호출하는 경우 인증된 모든 사용자가 정보를 볼 수 있습니다. 이러한 플랫폼에서 익명 액세스 및 익명 액세스 제한에 대한 자세한 내용은 네트워크 관리 함수에 대한 보안 요구 사항을 참조하세요. ACL, ACL 및 액세스 토큰에 대한 자세한 내용은 Access Control 모델을 참조하세요.
Domain 개체의 보안 설명자는 이 함수에 대한 액세스 검사 수행하는 데 사용됩니다. 호출자에게 Domain 개체에 대한 Read Property 권한이 있어야 합니다.
지정된 사용자가 속한 전역 그룹 목록을 검색하려면 NetUserGetGroups 함수를 호출하면 됩니다.
사용자 계정 이름은 20자로 제한되고 그룹 이름은 256자로 제한됩니다. 또한 계정 이름은 마침표로 종료할 수 없으며 쉼표 또는 인쇄 가능한 문자 중 일부를 포함할 수 없습니다. ", /, , [, ], :, |, <, , >+, =, ;, ?, *. 이름에는 인쇄할 수 없는 1-31 범위의 문자도 포함될 수 없습니다.
예제
다음 코드 샘플에서는 NetUserGetLocalGroups 함수를 호출하여 사용자가 속한 로컬 그룹 목록을 검색하는 방법을 보여 줍니다. 샘플은 정보 수준 0(LOCALGROUP_USERS_INFO_0)을 지정하여 NetUserGetLocalGroups를 호출합니다. 샘플은 항목을 반복하고 사용자가 멤버 자격이 있는 각 로컬 그룹의 이름을 출력합니다. 사용 가능한 모든 항목이 열거되지 않은 경우 실제로 열거된 항목 수와 사용 가능한 총 항목 수도 출력합니다. 마지막으로 코드 샘플은 정보 버퍼에 할당된 메모리를 해제합니다.
#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;
}
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | lmaccess.h(Lm.h 포함) |
| 라이브러리 | Netapi32.lib |
| DLL | Netapi32.dll |