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

Статья
02/28/2024

Возвращает сведения о некоторых или всех открытых файлах на сервере в зависимости от указанных параметров.

Синтаксис

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

Параметры

[in] servername

Указатель на строку, указывающую DNS- или NetBIOS-имя удаленного сервера, на котором выполняется функция. Если этот параметр имеет значение NULL, используется локальный компьютер.

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

[in] basepath

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

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

[in] username

Указатель на строку, указывающую имя пользователя или имя соединения. Если строка начинается с двух обратных косых черт ("\"), то она указывает имя соединения, например "\127.0.0.1" или "\ClientName". Часть имени подключения после обратных косых черт совпадает с именем клиента в структуре сведений о сеансе, возвращаемой функцией NetSessionEnum . Если строка не начинается с двух обратных косых черт, она указывает имя пользователя. Если этот параметр не равен NULL, его значение служит квалификатором для перечисления . Возвращаемые файлы ограничены именами пользователей или именами подключений, которые соответствуют квалификатору. Если этот параметр имеет значение NULL, квалификатор имени пользователя не используется.

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот параметр является указателем на строку, указывающую имя пользователя. Если этот параметр не равен NULL, его значение служит квалификатором для перечисления . Возвращаемые файлы ограничены теми, имена пользователей которых соответствуют квалификатору. Если этот параметр имеет значение NULL, квалификатор имени пользователя не используется.

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

[in] level

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

Значение	Значение
2	Возвращает идентификационный номер файла. Параметр bufptr указывает на массив FILE_INFO_2 структур.
3	Возврат сведений о файле. Параметр bufptr указывает на массив FILE_INFO_3 структур.

[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.

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

Код возврата	Описание
ERROR_ACCESS_DENIED	У пользователя нет доступа к запрошенной информации.
ERROR_INVALID_LEVEL	Значение, указанное для параметра level , является недопустимым.
ERROR_MORE_DATA	Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти.
NERR_BufTooSmall	Предоставленный буфер слишком мал.

При программировании для Active Directory вы можете вызвать определенные методы интерфейса службы Active Directory (ADSI) для достижения тех же функциональных возможностей, которые можно достичь, вызвав NetFileEnum. Дополнительные сведения см. в разделах IADsResource и IADsFileServiceOperations.

Требования

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