NetServerDiskEnum 함수(lmserver.h)

아티클
08/24/2023

NetServerDiskEnum 함수는 서버의 디스크 드라이브 목록을 검색합니다. 함수는 세 문자 문자열(드라이브 문자, 콜론 및 종료 null 문자)의 배열을 반환합니다.

구문

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

매개 변수

[in] servername

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

[in] level

필요한 정보 수준입니다. 값 0만 유효한 수준입니다.

[out] bufptr

데이터를 수신하는 버퍼에 대한 포인터입니다. 데이터는 3자 문자열(드라이브 문자, 콜론 및 종료 null 문자)의 배열입니다. 이 버퍼는 시스템에서 할당되며 NetApiBufferFree 함수를 사용하여 해제해야 합니다. 함수가 ERROR_MORE_DATA 실패하더라도 버퍼를 해제해야 합니다.

[in] prefmaxlen

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

참고 이 매개 변수는 현재 무시됩니다.

[out] entriesread

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

[out] totalentries

현재 다시 시작 위치에서 열거할 수 있는 총 항목 수를 수신하는 값에 대한 포인터입니다. 애플리케이션은 이 값을 힌트로만 고려해야 합니다.

[in, out] resume_handle

기존 서버 디스크 검색을 계속하는 데 사용되는 다시 시작 핸들이 포함된 값에 대한 포인터입니다. 핸들은 첫 번째 호출에서 0이어야 하며 후속 호출의 경우 변경되지 않은 상태로 유지되어야 합니다. resume_handle 매개 변수가 NULL 포인터인 경우 다시 시작 핸들이 저장되지 않습니다.

반환 값

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

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

반환 코드	설명
ERROR_ACCESS_DENIED	사용자는 요청한 정보에 대한 액세스 권한이 없습니다.
ERROR_INVALID_LEVEL	level 매개 변수에 지정된 값이 잘못되었습니다.
ERROR_MORE_DATA	더 많은 항목을 사용할 수 있습니다. 모든 항목을 수신할 수 있을 만큼 큰 버퍼를 지정합니다.
ERROR_NOT_ENOUGH_MEMORY	사용 가능한 메모리가 부족합니다.
ERROR_NOT_SUPPORTED	요청이 지원되지 않습니다. 이 오류는 원격 서버가 servername 매개 변수에 지정된 경우 반환되고, 원격 서버는 레거시 원격 액세스 프로토콜 메커니즘을 사용하여 원격 RPC 호출만 지원하며, 이 요청은 지원되지 않습니다.

설명

관리자 또는 서버 운영자 로컬 그룹의 멤버만 원격 컴퓨터에서 NetServerDiskEnum 함수를 성공적으로 실행할 수 있습니다.

Active Directory를 프로그래밍하는 경우 특정 ADSI(Active Directory Service Interface) 메서드를 호출하여 네트워크 관리 서버 함수를 호출하여 달성할 수 있는 것과 동일한 결과를 얻을 수 있습니다. 자세한 내용은 IADsComputer 인터페이스 참조를 참조하세요.

예제

다음 코드 샘플에서는 NetServerDiskEnum 함수를 호출하여 서버의 디스크 드라이브 목록을 검색하는 방법을 보여 줍니다. 샘플은 정보 수준 0(필수)을 지정하여 NetServerDiskEnum을 호출합니다. 반환할 항목이 있고 사용자가 정보에 액세스할 수 있는 경우 드라이브의 목록을 드라이브 문자, 콜론 및 종료 null 문자의 3자 문자열 형식으로 출력합니다. 또한 샘플은 사용할 수 있는 총 항목 수와 실제로 열거된 항목 수에 대한 힌트를 출력합니다. 마지막으로 코드 샘플은 버퍼에 할당된 메모리를 해제합니다.

#ifndef UNICODE
#define UNICODE
#endif

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

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

int wmain(int argc, wchar_t *argv[])
{
   const int ENTRY_SIZE = 3; // Drive letter, colon, NULL
   LPTSTR pBuf = NULL;
   DWORD dwLevel = 0; // level must be zero
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;
   LPWSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = (LPTSTR) argv[1];
   //
   // Call the NetServerDiskEnum function.
   //
   nStatus = NetServerDiskEnum(pszServerName,
                               dwLevel,
                               (LPBYTE *) &pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               NULL);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPTSTR pTmpBuf;

      if ((pTmpBuf = pBuf) != NULL)
      {
         DWORD i;
         DWORD dwTotalCount = 0;
         //
         // Loop through the entries.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               // On a remote computer, only members of the
               //  Administrators or the Server Operators 
               //  local group can execute NetServerDiskEnum.
               //
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Print drive letter, colon, NULL for each drive;
            //   the number of entries actually enumerated; and
            //   the total number of entries available.
            //
            fwprintf(stdout, L"\tDisk: %S\n", pTmpBuf);

            pTmpBuf += ENTRY_SIZE;
            dwTotalCount++;
         }

         fprintf(stderr, "\nEntries enumerated: %d\n", dwTotalCount);
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %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