NetServerDiskEnum 函数 (lmserver.h)

  • 项目

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
);

parameters

[in] servername

指向字符串的指针，该字符串指定要对其执行函数的远程服务器的 DNS 或 NetBIOS 名称。 如果此参数为 NULL，则使用本地计算机。

[in] level

所需的信息级别。 零值是唯一有效的级别。

[out] bufptr

指向接收数据的缓冲区的指针。 数据是一个由三个字符组成的字符串数组， (驱动器号、冒号和终止 null 字符) 。 此缓冲区由系统分配，必须使用 NetApiBufferFree 函数释放。 请注意，即使函数因ERROR_MORE_DATA而失败，也必须释放缓冲区。

[in] prefmaxlen

返回数据的首选最大长度（以字节为单位）。 如果指定MAX_PREFERRED_LENGTH，函数将分配数据所需的内存量。 如果在此参数中指定另一个值，它可以限制函数返回的字节数。 如果缓冲区大小不足以容纳所有条目，则函数将返回ERROR_MORE_DATA。 有关详细信息，请参阅 网络管理功能缓冲区 和 网络管理功能缓冲区长度。

注意 此参数当前被忽略。
 

[out] entriesread

指向一个值的指针，该值接收实际枚举的元素计数。

[out] totalentries

指向一个值的指针，该值接收可能从当前恢复位置枚举的条目总数。 请注意，应用程序应仅将此值视为提示。

[in, out] resume_handle

指向一个值的指针，该值包含用于继续现有服务器磁盘搜索的恢复句柄。 第一次调用时，句柄应为零，后续调用应保持不变。 如果 resume_handle 参数为 NULL 指针，则不存储任何恢复句柄。

返回值

如果函数成功，则返回值NERR_Success。

如果函数失败，则返回值可能是以下错误代码之一。

返回代码 说明
ERROR_ACCESS_DENIED
 用户无权访问请求的信息。
ERROR_INVALID_LEVEL
 为 级别 参数指定的值无效。
ERROR_MORE_DATA
 有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。
ERROR_NOT_ENOUGH_MEMORY
 可用内存不足。
ERROR_NOT_SUPPORTED
 不支持该请求。 如果在 servername 参数中指定了远程服务器，远程服务器仅支持使用旧式远程访问协议机制的远程 RPC 调用，并且不支持此请求，则返回此错误。

注解

只有管理员或服务器操作员本地组的成员才能在远程计算机上成功执行 NetServerDiskEnum 函数。

如果要对 Active Directory 进行编程，则可以调用某些 Active Directory 服务接口 (ADSI) 方法，以实现通过调用网络管理服务器函数可实现的相同结果。 有关详细信息，请参阅 IADsComputer 接口参考。

示例

以下代码示例演示如何调用 NetServerDiskEnum 函数来检索服务器上的磁盘驱动器列表。 此示例调用 NetServerDiskEnum，指定信息级别 0 (所需的) 。 如果有要返回的条目，并且用户有权访问信息，它将以三个字符字符串的格式打印驱动器列表：驱动器号、冒号和终止 null 字符。 该示例还打印了可用的条目总数，以及有关实际枚举的条目数的提示。 最后，代码示例释放为缓冲区分配的内存。

#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)
Library Netapi32.lib
DLL Netapi32.dll

另请参阅

IADsComputer

NetServerEnum

网络管理功能

网络管理概述

服务器函数