NetGroupEnum 함수(lmaccess.h)

아티클
08/24/2023

NetGroupEnum 함수는 SAM(보안 계정 관리자) 데이터베이스 또는 도메인 컨트롤러의 경우 Active Directory인 보안 데이터베이스의 각 전역 그룹에 대한 정보를 검색합니다.

NetQueryDisplayInformation 함수는 전역 그룹을 열거하는 효율적인 메커니즘을 제공합니다. 가능한 경우 NetGroupEnum 함수 대신 NetQueryDisplayInformation을 사용하는 것이 좋습니다.

구문

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

매개 변수

[in] servername

함수를 실행할 원격 서버의 DNS 또는 NetBIOS 이름을 지정하는 상수 문자열에 대한 포인터입니다. 이 매개 변수가 NULL이면 로컬 컴퓨터가 사용됩니다.

[in] level

데이터의 정보 수준을 지정합니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
0	전역 그룹 이름을 반환합니다. bufptr 매개 변수는 GROUP_INFO_0 구조체의 배열을 가리킵니다.
1	전역 그룹 이름 및 주석을 반환합니다. bufptr 매개 변수는 GROUP_INFO_1 구조체의 배열을 가리킵니다.
2	전역 그룹에 대한 자세한 정보를 반환합니다. bufptr 매개 변수는 GROUP_INFO_2 구조체의 배열을 가리킵니다. Windows XP 이상에서는 대신 GROUP_INFO_3 사용하는 것이 좋습니다.
3	전역 그룹에 대한 자세한 정보를 반환합니다. bufptr 매개 변수는 GROUP_INFO_3 구조체의 배열을 가리킵니다. Windows 2000: 이 수준은 지원되지 않습니다.

[out] bufptr

전역 그룹 정보 구조를 수신할 버퍼에 대한 포인터입니다. 이 데이터의 형식은 수준 매개 변수의 값에 따라 달라집니다.

시스템에서 이 버퍼에 대한 메모리를 할당합니다. NetApiBufferFree 함수를 호출하여 메모리의 할당을 취소해야 합니다. 함수가 ERROR_MORE_DATA 실패하더라도 버퍼를 해제해야 합니다.

[in] prefmaxlen

반환된 데이터의 기본 설정 최대 길이(바이트)를 지정합니다. MAX_PREFERRED_LENGTH 지정하는 경우 함수는 데이터를 보유하는 데 필요한 메모리 양을 할당합니다. 이 매개 변수에 다른 값을 지정하면 함수가 반환하는 바이트 수를 제한할 수 있습니다. 버퍼 크기가 모든 항목을 보유하기에 충분하지 않으면 함수는 ERROR_MORE_DATA 반환합니다. 자세한 내용은 네트워크 관리 함수 버퍼 및 네트워크 관리 함수 버퍼 길이를 참조하세요.

[out] entriesread

실제로 열거된 요소 수를 받는 값에 대한 포인터입니다.

[out] totalentries

현재 다시 시작 위치에서 열거할 수 있는 총 항목 수를 수신하는 값에 대한 포인터입니다. 총 항목 수는 힌트일 뿐입니다. 정확한 항목 수를 결정하는 방법에 대한 자세한 내용은 다음 주의 섹션을 참조하세요.

[in, out] resume_handle

전역 그룹 열거를 계속하는 데 사용되는 다시 시작 핸들이 포함된 변수에 대한 포인터입니다. 핸들은 첫 번째 호출에서 0이어야 하며 후속 호출의 경우 변경되지 않은 상태로 유지되어야 합니다. 이 매개 변수가 NULL이면 다시 시작 핸들이 저장되지 않습니다.

반환 값

함수가 성공하면 반환 값이 NERR_Success.

함수가 실패하면 반환 값은 다음 오류 코드 중 하나일 수 있습니다.

반환 코드	설명
ERROR_ACCESS_DENIED	사용자는 요청한 정보에 대한 액세스 권한이 없습니다.
NERR_InvalidComputer	컴퓨터 이름이 잘못된 경우
ERROR_MORE_DATA	더 많은 항목을 사용할 수 있습니다. 모든 항목을 수신할 수 있을 만큼 큰 버퍼를 지정합니다.

설명

Active Directory를 프로그래밍하는 경우 특정 ADSI(Active Directory Service Interface) 메서드를 호출하여 네트워크 관리 그룹 함수를 호출하여 달성할 수 있는 동일한 기능을 달성할 수 있습니다. 자세한 내용은 IADsGroup을 참조하세요.

Active Directory를 실행하는 도메인 컨트롤러에서 이 함수를 호출하는 경우 보안 개체에 대한 ACL(액세스 제어 목록)에 따라 액세스가 허용되거나 거부됩니다. 기본 ACL은 "사전 Windows 2000 호환 액세스" 그룹의 모든 인증된 사용자와 멤버가 정보를 볼 수 있도록 허용합니다. 멤버 서버 또는 워크스테이션에서 이 함수를 호출하는 경우 인증된 모든 사용자가 정보를 볼 수 있습니다. 이러한 플랫폼에서 익명 액세스 및 익명 액세스 제한에 대한 자세한 내용은 네트워크 관리 함수에 대한 보안 요구 사항을 참조하세요. ACL, ACL 및 액세스 토큰에 대한 자세한 내용은 Access Control 모델을 참조하세요.

함수는 호출자에게 읽기 권한이 있는 정보만 반환합니다. 호출자는 Domain 개체에 대한 List Contents 액세스 권한이 있어야 하며 시스템 컨테이너에 있는 SAM Server 개체에서 전체 SAM 도메인 액세스를 열거해야 합니다.

정확한 총 그룹 수를 확인하려면 비용이 많이 드는 작업일 수 있는 전체 트리를 열거해야 합니다. 전체 트리를 열거하려면 resume_handle 매개 변수를 사용하여 연속 호출에 대한 열거를 계속하고 entriesread 매개 변수를 사용하여 총 그룹 수를 누적합니다. 애플리케이션이 도메인 컨트롤러와 통신하는 경우 ADSI LDAP 공급자 를 사용하여 이러한 유형의 데이터를 보다 효율적으로 검색하는 것이 좋습니다. ADSI LDAP 공급자는 다양한 ADSI 인터페이스를 지원하는 ADSI 개체 집합을 구현합니다. 자세한 내용은 ADSI 서비스 공급자를 참조하세요.

사용자 계정 이름은 20자로 제한되고 그룹 이름은 256자로 제한됩니다. 또한 계정 이름은 마침표로 종료할 수 없으며 쉼표 또는 인쇄 가능한 문자 중 일부를 포함할 수 없습니다. ", /, , [, ], :, |, <, , >+, =, ;, ?, *. 이름에는 인쇄할 수 없는 1-31 범위의 문자도 포함될 수 없습니다.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	lmaccess.h(Lm.h 포함)
라이브러리	Netapi32.lib
DLL	Netapi32.dll