NetQueryDisplayInformation 함수(lmaccess.h)

아티클
03/09/2023

NetQueryDisplayInformation 함수는 사용자 계정, 컴퓨터 또는 그룹 계정 정보를 반환합니다. 사용자 인터페이스에 표시할 계정 정보를 신속하게 열거하려면 이 함수를 호출합니다.

구문

NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
  [in]  LPCWSTR ServerName,
  [in]  DWORD   Level,
  [in]  DWORD   Index,
  [in]  DWORD   EntriesRequested,
  [in]  DWORD   PreferredMaximumLength,
  [out] LPDWORD ReturnedEntryCount,
  [out] PVOID   *SortedBuffer
);

매개 변수

[in] ServerName

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

[in] Level

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

값	의미
1	사용자 계정 정보를 반환합니다. SortedBuffer 매개 변수는 NET_DISPLAY_USER 구조체의 배열을 가리킵니다.
2	개별 컴퓨터 정보를 반환합니다. SortedBuffer 매개 변수는 NET_DISPLAY_MACHINE 구조체의 배열을 가리킵니다.
3	그룹 계정 정보를 반환합니다. SortedBuffer 매개 변수는 NET_DISPLAY_GROUP 구조체의 배열을 가리킵니다.

[in] Index

정보를 검색할 첫 번째 항목의 인덱스를 지정합니다. 첫 번째 표시 정보 항목부터 계정 정보를 검색하려면 0을 지정합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in] EntriesRequested

정보를 검색할 최대 항목 수를 지정합니다. Windows 2000 이상에서 NetQueryDisplayInformation 에 대한 각 호출은 최대 100개의 개체를 반환합니다.

[in] PreferredMaximumLength

SortedBuffer 매개 변수에 반환된 시스템 할당 버퍼의 기본 최대 크기(바이트)를 지정합니다. 이 매개 변수를 MAX_PREFERRED_LENGTH 설정하는 것이 좋습니다.

[out] ReturnedEntryCount

SortedBuffer 매개 변수에 반환된 버퍼의 항목 수를 수신하는 값에 대한 포인터입니다. 이 매개 변수가 0이면 인덱스가 지정된 만큼 큰 항목이 없습니다. 함수의 반환 값이 NERR_Success 또는 ERROR_MORE_DATA 경우 항목이 반환될 수 있습니다.

[out] SortedBuffer

요청된 정보의 정렬된 목록을 지정하는 시스템 할당 버퍼에 대한 포인터를 수신하는 버퍼에 대한 포인터입니다. 이 데이터의 형식은 Level 매개 변수의 값에 따라 달라집니다. 이 버퍼는 시스템에서 할당되므로 NetApiBufferFree 함수를 사용하여 해제해야 합니다. 함수가 ERROR_MORE_DATA 실패하더라도 버퍼를 해제해야 합니다. 자세한 내용은 다음 반환 값 섹션 및 topics 네트워크 관리 함수 버퍼 및 네트워크 관리 함수 버퍼 길이를 참조하세요.

반환 값

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

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

반환 코드	설명
ERROR_ACCESS_DENIED	사용자는 요청한 정보에 대한 액세스 권한이 없습니다.
ERROR_INVALID_LEVEL	Level 매개 변수는 잘못된 값을 지정합니다.
ERROR_MORE_DATA	더 많은 항목을 사용할 수 있습니다. 즉, SortedBuffer 매개 변수에 반환된 마지막 항목이 사용 가능한 마지막 항목이 아닙니다. 추가 항목을 검색하려면 Index 매개 변수가 SortedBuffer의 마지막 항목의 next_index 멤버에 반환된 값으로 설정된 상태에서 NetQueryDisplayInformation을 다시 호출합니다. NetQueryDisplayInformation에 대한 추가 호출을 사용하여 더 많은 데이터를 검색하는 것 외에는 어떤 목적으로도 next_index 멤버의 값을 사용하면 안 됩니다.

설명

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

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

NetQueryDisplayInformation 및 NetGetDisplayInformationIndex 함수는 사용자 및 그룹 계정을 열거하기 위한 효율적인 메커니즘을 제공합니다. 가능하면 NetUserEnum 함수 또는 NetGroupEnum 함수 대신 이러한 함수를 사용합니다.

신뢰할 수 있는 도메인 또는 멤버 컴퓨터 계정을 열거하려면 NetUserEnum을 호출하고 필요한 계정 정보를 얻기 위한 적절한 필터 값을 지정합니다. 신뢰할 수 있는 도메인을 열거하려면 LsaEnumerateTrustedDomains 또는 LsaEnumerateTrustedDomainsEx 함수를 호출합니다.

이 함수에서 반환하는 항목 수는 루트 도메인 개체에 있는 보안 설명자에 따라 달라집니다. API는 사용자의 액세스 권한에 따라 처음 100개 항목 또는 도메인의 전체 항목 집합을 반환합니다. 이 동작을 제어하는 데 사용되는 ACE는 "SAM-Enumerate-Entire-Domain"이며 기본적으로 인증된 사용자에게 부여됩니다. 관리자는 사용자가 전체 도메인을 열거할 수 있도록 이 설정을 수정할 수 있습니다.

NetQueryDisplayInformation에 대한 각 호출은 최대 100개의 개체를 반환합니다. NetQueryDisplayInformation 함수를 호출하여 도메인 계정 정보를 열거하는 것은 성능 측면에서 비용이 많이 들 수 있습니다. Active Directory를 프로그래밍하는 경우 IDirectorySearch 인터페이스의 메서드를 사용하여 도메인에 대해 페이징된 쿼리를 만들 수 있습니다. 자세한 내용은 IDirectorySearch::SetSearchPreference 및 IDirectorySearch::ExecuteSearch를 참조하세요. 신뢰할 수 있는 도메인을 열거하려면 LsaEnumerateTrustedDomainsEx 함수를 호출합니다 .

예제

다음 코드 샘플에서는 NetQueryDisplayInformation 함수에 대한 호출을 사용하여 그룹 계정 정보를 반환하는 방법을 보여 줍니다. 사용자가 서버 이름을 지정하는 경우 샘플은 먼저 MultiByteToWideChar 함수를 호출하여 이름을 유니코드로 변환합니다. 이 샘플에서는 NetQueryDisplayInformation을 호출하여 정보 수준 3(NET_DISPLAY_GROUP)을 지정하여 그룹 계정 정보를 검색합니다. 반환할 항목이 있는 경우 샘플은 데이터를 반환하고 그룹 정보를 출력합니다. 마지막으로 코드 샘플은 정보 버퍼에 할당된 메모리를 해제합니다.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>
#include <lm.h>

#pragma comment(lib, "netapi32.lib")

void main( int argc, char *argv[ ] )
{
   PNET_DISPLAY_GROUP pBuff, p;
   DWORD res, dwRec, i = 0;
   //
   // You can pass a NULL or empty string
   //  to retrieve the local information.
   //
   TCHAR szServer[255]=TEXT(""); 

   if(argc > 1) 
      //
      // Check to see if a server name was passed;
      //  if so, convert it to Unicode.
      //
      MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255); 

   do // begin do
   { 
      //
      // Call the NetQueryDisplayInformation function;
      //   specify information level 3 (group account information).
      //
      res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
      //
      // If the call succeeds,
      //
      if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
      {
         p = pBuff;
         for(;dwRec>0;dwRec--)
         {
            //
            // Print the retrieved group information.
            //
            printf("Name:      %S\n"
                  "Comment:   %S\n"
                  "Group ID:  %u\n"
                  "Attributes: %u\n"
                  "--------------------------------\n",
                  p->grpi3_name,
                  p->grpi3_comment,
                  p->grpi3_group_id,
                  p->grpi3_attributes);
            //
            // If there is more data, set the index.
            //
            i = p->grpi3_next_index;
            p++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pBuff);
      }
      else
         printf("Error: %u\n", res);
   //
   // Continue while there is more data.
   //
   } while (res==ERROR_MORE_DATA); // end do
   return;
}

요구 사항


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