NetServerEnum 함수(lmserver.h)
NetServerEnum 함수는 도메인에 표시되는 지정된 형식의 모든 서버를 나열합니다.
구문
NET_API_STATUS NET_API_FUNCTION NetServerEnum(
[in, optional] LMCSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in] DWORD servertype,
[in, optional] LMCSTR domain,
[in, out, optional] LPDWORD resume_handle
);
매개 변수
[in, optional] servername
예약; 은 NULL이어야 합니다.
[in] level
요청된 데이터의 정보 수준입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
서버 이름 및 플랫폼 정보를 반환합니다. bufptr 매개 변수는 SERVER_INFO_100 구조체의 배열을 가리킵니다. |
|
서버 이름, 형식 및 관련 데이터를 반환합니다. bufptr 매개 변수는 SERVER_INFO_101 구조체의 배열을 가리킵니다. |
[out] bufptr
데이터를 수신하는 버퍼에 대한 포인터입니다. 이 데이터의 형식은 수준 매개 변수의 값에 따라 달라집니다. 이 버퍼는 시스템에서 할당되며 NetApiBufferFree 함수를 사용하여 해제해야 합니다. 함수가 ERROR_MORE_DATA 실패하더라도 버퍼를 해제해야 합니다.
[in] prefmaxlen
반환된 데이터의 기본 설정 최대 길이(바이트)입니다. MAX_PREFERRED_LENGTH 지정하는 경우 함수는 데이터에 필요한 메모리 양을 할당합니다. 이 매개 변수에 다른 값을 지정하면 함수가 반환하는 바이트 수를 제한할 수 있습니다. 버퍼 크기가 모든 항목을 보유하기에 충분하지 않은 경우 함수는 ERROR_MORE_DATA 반환합니다. 자세한 내용은 네트워크 관리 함수 버퍼 및 네트워크관리 함수 버퍼 길이를 참조하세요.
[out] entriesread
실제로 열거된 요소 수를 수신하는 값에 대한 포인터입니다.
[out] totalentries
네트워크에 표시되는 서버 및 워크스테이션의 총 수를 수신하는 값에 대한 포인터입니다. 애플리케이션은 이 값을 힌트로만 고려해야 합니다.
[in] servertype
열거형에서 반환할 서버 항목을 필터링하는 값입니다. 이 매개 변수는 Lmserver.h 헤더 파일에 정의된 다음 값의 조합일 수 있습니다.
[in, optional] domain
서버 목록을 반환할 도메인의 이름을 지정하는 상수 문자열에 대한 포인터입니다. 도메인 이름은 NetBIOS 도메인 이름(예: microsoft)이어야 합니다. NetServerEnum 함수는 DNS 스타일 이름(예: microsoft.com)을 지원하지 않습니다.
이 매개 변수가 NULL이면 기본 도메인이 암시됩니다.
[in, out, optional] resume_handle
예약; 를 0으로 설정해야 합니다.
반환 값
함수가 성공하면 반환 값이 NERR_Success.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나일 수 있습니다.
| 반환 코드/값 | 설명 |
|---|---|
|
액세스가 거부되었습니다. |
|
매개 변수가 올바르지 않습니다. |
|
더 많은 항목을 사용할 수 있습니다. 모든 항목을 수신할 수 있을 만큼 큰 버퍼를 지정합니다. |
|
브라우저 서버를 찾을 수 없습니다. |
|
요청이 지원되지 않습니다. |
|
서버에서 반환된 데이터가 없는 원격 오류가 발생했습니다. |
|
서버 서비스가 시작되지 않았습니다. |
|
서비스가 시작되지 않았습니다. |
|
워크스테이션 서비스가 시작되지 않았습니다. 로컬 워크스테이션 서비스는 하위 원격 서버와 통신하는 데 사용됩니다. |
설명
NetServerEnum 함수는 도메인에 표시되는 지정된 형식의 모든 서버를 나열하는 데 사용됩니다. 예를 들어 애플리케이션은 NetServerEnum 을 호출하여 모든 도메인 컨트롤러만 나열하거나 SQL Server 인스턴스만 실행하는 모든 서버를 나열할 수 있습니다.
애플리케이션은 servertype 매개 변수의 다양한 서버 형식에 대한 비트 마스크를 결합하여 여러 형식을 나열합니다. 예를 들어 값은 SV_TYPE_WORKSTATION | SVTYPE_SERVER(0x00000003)는 SV_TYPE_WORKSTATION(0x00000001) 및 SV_TYPE_SERVER(0x00000002)에 대한 비트 마스크를 결합합니다.
특정 서버에 대한 자세한 정보가 필요한 경우 WNetEnumResource 함수를 호출합니다.
NetServerEnum 함수를 성공적으로 실행하려면 특별한 그룹 멤버 자격이 필요하지 않습니다.
SV_TYPE_LOCAL_LIST_ONLY 값을 지정하면 NetServerEnum 함수는 브라우저가 내부적으로 유지 관리하는 서버 목록을 반환합니다. 이는 master 브라우저(또는 과거에 master 브라우저였던 컴퓨터)에서만 의미가 있습니다. master 브라우저는 현재 네트워크의 서버 또는 워크스테이션이 될 수 있는 컴퓨터를 확인할 수 있는 권한이 있는 컴퓨터입니다.
servertype 매개 변수에 지정된 형식과 일치하는 서버를 찾을 수 없는 경우 NetServerEnum 함수는 bufptr 매개 변수를 NULL로 반환하고 entriesread 및 totalentries 매개 변수가 가리키는 DWORD 값은 0으로 설정됩니다.
NetServerEnum 함수는 설치 및 실행 중인 브라우저 서비스에 따라 달라집니다. 브라우저 서버를 찾을 수 없으면 NetServerEnum 이 ERROR_NO_BROWSER_SERVERS_FOUND 실패합니다.
Active Directory를 프로그래밍하는 경우 특정 ADSI(Active Directory Service Interface) 메서드를 호출하여 네트워크 관리 서버 함수를 호출하여 달성할 수 있는 동일한 기능을 달성할 수 있습니다. 자세한 내용은 IADsComputer를 참조하세요.
예제
다음 코드 샘플에서는 NetServerEnum 함수를 호출하여 도메인에 표시되는 모든 서버를 나열하는 방법을 보여 줍니다. 샘플은 정보 수준 101( SERVER_INFO_101)을 지정하여 NetServerEnum을 호출합니다. 서버가 있는 경우 샘플 코드는 항목을 반복하고 검색된 데이터를 출력합니다. 서버가 도메인 컨트롤러인 경우 서버를 PDC(주 도메인 컨트롤러) 또는 BDC(백업 도메인 컨트롤러)로 식별합니다. 또한 샘플은 사용 가능한 총 항목 수와 실제로 열거된 항목 수에 대한 힌트를 출력하여 모든 항목이 열거되지 않은 경우 사용자에게 경고합니다. 마지막으로 샘플은 정보 버퍼에 할당된 메모리를 해제합니다.
#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[])
{
LPSERVER_INFO_101 pBuf = NULL;
LPSERVER_INFO_101 pTmpBuf;
DWORD dwLevel = 101;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwTotalCount = 0;
DWORD dwServerType = SV_TYPE_SERVER; // all servers
DWORD dwResumeHandle = 0;
NET_API_STATUS nStatus;
LPWSTR pszServerName = NULL;
LPWSTR pszDomainName = NULL;
DWORD i;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [DomainName]\n", argv[0]);
exit(1);
}
// The request is not for the primary domain.
//
if (argc == 2)
pszDomainName = argv[1];
//
// Call the NetServerEnum function to retrieve information
// for all servers, specifying information level 101.
//
nStatus = NetServerEnum(pszServerName,
dwLevel,
(LPBYTE *) & pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
dwServerType,
pszDomainName,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA)) {
if ((pTmpBuf = pBuf) != NULL) {
//
// Loop through the entries and
// print the data for all server types.
//
for (i = 0; i < dwEntriesRead; i++) {
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL) {
fprintf(stderr, "An access violation has occurred\n");
break;
}
printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
wprintf(L"\tName: %s\n", pTmpBuf->sv101_name);
printf("\tVersion: %d.%d\n",
pTmpBuf->sv101_version_major,
pTmpBuf->sv101_version_minor);
printf("\tType: %d", pTmpBuf->sv101_type);
//
// Check to see if the server is a domain controller;
// if so, identify it as a PDC or a BDC.
//
if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
wprintf(L" (PDC)");
else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
wprintf(L" (BDC)");
printf("\n");
//
// Also print the comment associated with the server.
//
wprintf(L"\tComment: %s\n\n", pTmpBuf->sv101_comment);
pTmpBuf++;
dwTotalCount++;
}
// Display a warning if all available entries were
// not enumerated, print the number actually
// enumerated, and the total number available.
if (nStatus == ERROR_MORE_DATA) {
fprintf(stderr, "\nMore entries available!!!\n");
fprintf(stderr, "Total entries: %d", dwTotalEntries);
}
printf("\nEntries enumerated: %d\n", dwTotalCount);
} else {
printf("No servers were found\n");
printf("The buffer (bufptr) returned was NULL\n");
printf(" entriesread: %d\n", dwEntriesRead);
printf(" totalentries: %d\n", dwEntriesRead);
}
} else
fprintf(stderr, "NetServerEnum failed with error: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | lmserver.h(Lm.h 포함) |
| 라이브러리 | Netapi32.lib |
| DLL | Netapi32.dll |