Функция NetConnectionEnum (lmshare.h)

Статья
08/24/2023

Список всех подключений к общему ресурсу на сервере или всех подключений, установленных с определенного компьютера. Если это подключение использует несколько пользователей, можно получить несколько структур для одного подключения, но с другим именем пользователя.

Синтаксис

NET_API_STATUS NET_API_FUNCTION NetConnectionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   qualifier,
  [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, используется локальный компьютер.

Эта строка имеет значение Юникод, если определен _WIN32_WINNT или FORCE_UNICODE .

[in] qualifier

Указатель на строку, указывающую имя общей папки или имя компьютера для интересующих подключений. Если это имя общей папки, будут перечислены все подключения, выполненные с этим именем общей папки. Если это имя компьютера (например, оно начинается с двух символов обратной косой черты), netConnectionEnum выводит список всех подключений, выполненных с этого компьютера, к указанному серверу.

Эта строка имеет значение Юникод, если определен _WIN32_WINNT или FORCE_UNICODE .

[in] level

Задает уровень информации данных. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
0	Возвращает идентификаторы подключений. Параметр bufptr является указателем на массив CONNECTION_INFO_0 структур.
1	Возвращает идентификаторы подключений и сведения о подключении. Параметр bufptr является указателем на массив CONNECTION_INFO_1 структур.

[out] bufptr

Указатель на адрес буфера, который получает сведения. Формат этих данных зависит от значения параметра level .

Этот буфер выделяется системой и должен быть освобожден с помощью функции NetApiBufferFree . Обратите внимание, что буфер необходимо освободить, даже если функция завершается сбоем с ERROR_MORE_DATA.

[in] prefmaxlen

Задает предпочтительную максимальную длину возвращаемых данных в байтах. Если указать MAX_PREFERRED_LENGTH, функция выделяет объем памяти, необходимый для данных. Если указать другое значение в этом параметре, это может ограничить количество байтов, возвращаемых функцией. Если размер буфера недостаточен для хранения всех записей, функция возвращает ERROR_MORE_DATA. Дополнительные сведения см. в разделах Буферы функций управления сетью и Длина буфера функции управления сетью.

[out] entriesread

Указатель на значение, которое получает количество фактически перечисленных элементов.

[out] totalentries

Указатель на значение, которое получает общее количество записей, которые можно было бы перечислить из текущей позиции резюме. Обратите внимание, что приложения должны рассматривать это значение только как подсказку.

[in, out] resume_handle

Указатель на значение, содержащее дескриптор возобновления, используемый для продолжения поиска существующего подключения. Дескриптор должен быть равен нулю при первом вызове и оставить без изменений для последующих вызовов. Если этот параметр имеет значение NULL, дескриптор возобновления не сохраняется.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NERR_Success.

Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки. Список кодов ошибок см. в разделе Системные коды ошибок.

В следующем примере кода показано, как получить список подключений к общему ресурсу с помощью вызова функции NetConnectionEnum . В примере вызывается NetConnectionEnum, указывая уровень сведений 1 (CONNECTION_INFO_1). При наличии возвращаемых записей выводится значение coni1_username и coni1_netname членов. Если возвращаемых записей нет, образец выводит соответствующее сообщение. Наконец, пример кода освобождает память, выделенную для информационного буфера.

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <lm.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res, i, er = 0, tr = 0, resume = 0;
   PCONNECTION_INFO_1 p,b;
   LPTSTR lpszServer = NULL, lpszShare = NULL;

   if(argc<2)
      wprintf(L"Syntax: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
   else
   {
      //
      // The server is not the default local computer.
      //
      if(argc>2)
         lpszServer=argv[1];
      //
      // ShareName is always the last argument.
      //
      lpszShare=argv[argc - 1];
      //
      // Call the NetConnectionEnum function,
      //  specifying information level 1.
      //
      res=NetConnectionEnum(lpszServer, lpszShare, 1, (LPBYTE *) &p, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If no error occurred,
      //
      if(res == 0)
      {
         //
         // If there were any results,
         //
         if(er>0)
         {
            b=p;
            //
            // Loop through the entries; print user name and network name.
            //
            for(i=0;i<er;i++)
            {
               printf("%S\t%S\n", b->coni1_username,b->coni1_netname);
               b++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(p);
         }
         // Otherwise, print a message depending on whether 
         //  the qualifier parameter was a computer (\\ComputerName)
         //  or a share (ShareName).
         //
         else
         {
            if(lpszShare[0]=='\\')  
               printf("No connection to %S from %S\n", 
                  (lpszServer == NULL)?TEXT("LocalMachine"):lpszServer, lpszShare);
            else                       
               printf("No one connected to %S\\%S\n",
                  (lpszServer == NULL)?TEXT("\\\\LocalMachine"):lpszServer,lpszShare);
         }        
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %d\n",res);
   }
   return;
}

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	lmshare.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll