Функция NetShareEnum (lmshare.h)
Извлекает сведения о каждом общем ресурсе на сервере.
Для получения сведений о ресурсе также можно использовать функцию WNetEnumResource . Однако WNetEnumResource не перечисляет скрытые общие папки или пользователей, подключенных к общей папке.
Синтаксис
NET_API_STATUS NET_API_FUNCTION NetShareEnum(
[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
Задает уровень информации данных. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Возвращает имена общих ресурсов. Параметр bufptr указывает на массив SHARE_INFO_0 структур. |
|
Возвращает сведения об общих ресурсах, включая имя и тип ресурса, а также комментарий, связанный с ресурсом.
Параметр bufptr указывает на массив SHARE_INFO_1 структур. |
|
Возвращает сведения об общих ресурсах, включая имя ресурса, тип и разрешения, пароль и количество подключений. Параметр bufptr указывает на массив SHARE_INFO_2 структур. |
|
Возвращает сведения об общих ресурсах, включая имя ресурса, тип и разрешения, количество подключений и другие важные сведения. Параметр bufptr указывает на массив SHARE_INFO_502 структур. Общие папки из разных областей не возвращаются. Дополнительные сведения о области см. в разделе Примечания документации по функции NetServerTransportAddEx . |
|
Возвращает сведения об общих ресурсах, включая имя ресурса, тип и разрешения, количество подключений и другие важные сведения. Параметр bufptr указывает на массив SHARE_INFO_503 структур. Возвращаются общие папки из всех областей. Если элементом shi503_servername этой структуры является "*", то нет настроенного имени сервера, а функция NetShareEnum перечисляет общие папки для всех неопределенных имен.
Windows Server 2003 и Windows XP: Этот уровень сведений не поддерживается. |
[out] bufptr
Указатель на буфер, который получает данные. Формат этих данных зависит от значения параметра level .
Этот буфер выделяется системой и должен быть освобожден с помощью функции 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.
Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки. Список кодов ошибок см. в разделе Системные коды ошибок.
Комментарии
Эта функция применяется только к общим папкам SMB. Для других типов общих папок, таких как распределенная файловая система (DFS) или общие папки WebDAV, используйте функции windows Networking (WNet), которые поддерживают все типы общих папок.
Для интерактивных пользователей (пользователей, которые вошли в систему локально на компьютере) не требуется специальное членство в группах для выполнения функции NetShareEnum . Чтобы успешно выполнить функцию NetShareEnum на уровнях 2, 502 и 503, требуется членство неинтерактивных пользователей, администраторов, power user, операторов печати или операторов сервера. Для звонков уровня 0 или 1 не требуется специальное членство в группах.
Windows Server 2022: Чтобы успешно выполнить функцию NetShareEnum на уровнях 2, 502 и 503, требуется членство в неинтерактивных пользователях, администраторах, операторах помощи контроль доступа или членстве в группе операторов сервера.
Windows Server 2003 и Windows XP: Для успешного выполнения функции NetShareEnum на уровнях 2 и 502 требуется членство в группе "Администратор", "Power User", "Оператор печати" или "Оператор сервера".
Чтобы получить значение, указывающее, является ли общая папка корневым томом в древовидной структуре DFS, необходимо вызвать функцию NetShareGetInfo и указать уровень информации 1005.
При программировании для Active Directory вы можете вызвать определенные методы интерфейса службы Active Directory (ADSI), чтобы достичь тех же функций, которые можно достичь, вызвав функции общего доступа для управления сетью. Дополнительные сведения см. в разделе IADsFileShare.
Примеры
В следующем примере кода показано, как получить сведения о каждом общем ресурсе на сервере с помощью вызова функции NetShareEnum . В примере вызывается NetShareEnum, указывая уровень сведений 502 (SHARE_INFO_502). Если вызов выполнен успешно, код циклически просматривает записи и выводит сведения о каждой общей папке. В примере также вызывается функция IsValidSecurityDescriptor для проверки члена shi502_security_descriptor . Наконец, пример кода освобождает память, выделенную для информационного буфера.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>
#pragma comment(lib, "Netapi32.lib")
#pragma comment(lib, "Advapi32.lib")
void wmain( int argc, TCHAR *lpszArgv[ ])
{
PSHARE_INFO_502 BufPtr,p;
NET_API_STATUS res;
LPTSTR lpszServer = NULL;
DWORD er=0,tr=0,resume=0, i;
switch(argc)
{
case 2:
lpszServer = lpszArgv[1];
break;
default:
printf("Usage: NetShareEnum <servername>\n");
return;
}
//
// Print a report header.
//
printf("Share: Local Path: Uses: Descriptor:\n");
printf("---------------------------------------------------------------------\n");
//
// Call the NetShareEnum function; specify level 502.
//
do // begin do
{
res = NetShareEnum (lpszServer, 502, (LPBYTE *) &BufPtr, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
//
// If the call succeeds,
//
if(res == ERROR_SUCCESS || res == ERROR_MORE_DATA)
{
p=BufPtr;
//
// Loop through the entries;
// print retrieved data.
//
for(i=1;i<=er;i++)
{
printf("%-20S%-30S%-8u",p->shi502_netname, p->shi502_path, p->shi502_current_uses);
//
// Validate the value of the
// shi502_security_descriptor member.
//
if (IsValidSecurityDescriptor(p->shi502_security_descriptor))
printf("Yes\n");
else
printf("No\n");
p++;
}
//
// Free the allocated buffer.
//
NetApiBufferFree(BufPtr);
}
else
printf("Error: %ld\n",res);
}
// Continue to call NetShareEnum while
// there are more entries.
//
while (res==ERROR_MORE_DATA); // end do
return;
}
Требования
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | lmshare.h (включая Lm.h) |
| Библиотека | Netapi32.lib |
| DLL | Netapi32.dll |