Функция NetMessageNameEnum (lmmsg.h)

Статья
08/24/2023

[Эта функция не поддерживается в Windows Vista, так как служба messenger не поддерживается.]

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

Синтаксис

NET_API_STATUS NET_API_FUNCTION NetMessageNameEnum(
  [in]      LPCWSTR 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

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

Значение	Значение
0	Возврат псевдонимов сообщений. Параметр bufptr указывает на массив MSG_INFO_0 структур.
1	Возврат псевдонимов сообщений. Параметр bufptr указывает на массив MSG_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

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

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

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

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

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

Требования


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