Функция NetServerDiskEnum (lmserver.h)

Статья
03/14/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

Требуемый уровень информации. Единственным допустимым уровнем является нулевое значение.

[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	Значение, указанное для параметра level , является недопустимым.
ERROR_MORE_DATA	Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти.
ERROR_NOT_SUPPORTED	Запрос не поддерживается. Эта ошибка возвращается, если удаленный сервер был указан в параметре servername , удаленный сервер поддерживает только удаленные вызовы RPC с использованием устаревшего механизма протокола удаленного доступа, и этот запрос не поддерживается.

При программировании для 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
Header	lmserver.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll