Функция SnmpRegister (winsnmp.h)

Статья
03/04/2024

[SNMP доступен для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. Вместо этого используйте удаленное управление Windows, которое является реализацией WS-Man майкрософт.]

Функция WinSNMP SnmpRegister регистрирует или отменяет регистрацию приложения WinSNMP для получения перехватов и уведомлений. Приложение может регистрировать и получать ловушки и уведомления, а также отменять регистрацию и отключить ловушки и уведомления.

Приложение WinSNMP может зарегистрировать или отменить регистрацию для одного типа перехвата или уведомления, а также для всех ловушек и уведомлений в зависимости от значения параметра уведомления .

Синтаксис

SNMPAPI_STATUS SNMPAPI_CALL SnmpRegister(
  [in] HSNMP_SESSION session,
  [in] HSNMP_ENTITY  srcEntity,
  [in] HSNMP_ENTITY  dstEntity,
  [in] HSNMP_CONTEXT context,
  [in] smiLPCOID     notification,
  [in] smiUINT32     state
);

Параметры

[in] session

Обработка сеанса WinSNMP, который регистрирует или отменяет регистрацию для ловушек и уведомлений.

[in] srcEntity

Обработка для сущности управления, которая является источником запроса на регистрацию. Эта сущность, выступающая в роли диспетчера SNMP, получит ловушку или уведомление.

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

Если этот параметр имеет значение NULL, реализация Microsoft WinSNMP регистрирует или отменяет регистрацию всех источников запросов на перехват и уведомления.

Обратите внимание, что параметр srcEntity для функции SnmpRecvMsg имеет другую роль. В этой функции srcEntity получает дескриптор сущности, которая отправила ловушку.

[in] dstEntity

Обработка для сущности управления, которая является получателем запроса на регистрацию. Эта сущность, выступающая в роли агента SNMP, отправляет ловушку или уведомление.

Если этот параметр имеет значение NULL, реализация регистрирует или отменяет регистрацию приложения WinSNMP для перехватов и уведомлений от всех сущностей управления.

Обратите внимание, что параметр dstEntity для функции SnmpRecvMsg получает дескриптор для управляющей сущности, которая регистрирует для уведомления ловушки.

[in] context

Дескриптор для контекста, который представляет собой набор ресурсов управляемых объектов.

Если этот параметр имеет значение NULL, реализация регистрирует или отменяет регистрацию приложения WinSNMP для ловушек и уведомлений для каждого контекста.

[in] notification

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

Если этот параметр имеет значение NULL, реализация регистрирует или отменяет регистрацию приложения WinSNMP для всех ловушек и уведомлений от управляющей сущности или сущностей, указанных параметром dstEntity .

[in] state

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

Значение	Значение
SNMPAPI_OFF	Отключите ловушки и уведомления.
SNMPAPI_ON	Зарегистрируйтесь для получения ловушек и уведомлений.

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

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

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

Код возврата	Описание
SNMPAPI_NOT_INITIALIZED	Не удалось выполнить функцию SnmpStartup .
SNMPAPI_ALLOC_ERROR	Ошибка при выделении памяти.
SNMPAPI_SESSION_INVALID	Недопустимый параметр сеанса .
SNMPAPI_ENTITY_INVALID	Один или оба параметра сущности недопустимы.
SNMPAPI_CONTEXT_INVALID	Недопустимый параметр контекста .
SNMPAPI_OID_INVALID	Недопустимый параметр уведомления .
SNMPAPI_TL_NOT_INITIALIZED	Уровень сетевого транспорта не инициализирован, или не удалось запустить службу SNMPTRAP.EXE.
SNMPAPI_TL_IN_USE	Порт ловушки недоступен.
SNMPAPI_TL_NOT_AVAILABLE	Произошел сбой сетевой подсистемы.
SNMPAPI_OTHER_ERROR	Произошла неизвестная или неопределенная ошибка.

Дополнительные сведения см. в разделе Ошибки сетевого транспорта.

Важно отметить, что для пользователей, не являющихся администраторами, функция SnmpRegister успешно работает в Windows 2000 и Windows XP только в том случае, если запущена служба snmp trap.

Если приложение WinSNMP передает значение NULL в вызове функции SnmpRegister в параметрах srcEntity, dstEntity, контекста или уведомления , реализация не использует этот параметр для фильтрации ловушек и уведомлений, поступающих от приложения WinSNMP. Если приложение передает значение NULL во всех упомянутых выше параметрах, реализация доставляет в сеанс все полученные уведомления.

Если приложение WinSNMP регистрируется для получения определенного типа ловушки или уведомления, оно должно определить идентификатор объекта, то есть структуру smiOID , соответствующую такому типу ловушки. Параметр уведомления должен указывать на эту структуру. RFC 1907 , "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)" определяет идентификаторы объектов ловушки и уведомления. Дополнительные сведения см. в разделах Управление ловушками и уведомлениями и Преобразование ловушек из SNMPv1 в SNMPv2C.

Реализация использует значение параметра уведомления в качестве шаблона для сопоставления с полученными ловушками и уведомлениями. Например, если приложение WinSNMP передает n числа подидентификаторов в параметре уведомления , а первые n подидентификаторов в полученной ловушке соответствуют всем переданным подидентификаторам, то идентификатор объекта ловушки является совпадением. Если в полученной ловушке меньше подидентификаторов, чем n, идентификатор объекта не совпадает. Если совпадение есть, реализация отправляет ловушку или уведомление в приложение WinSNMP.

Если какой-либо или все параметры dstEntity, srcEntity или контекста имеют значение NULL, реализации может потребоваться выделить ресурсы для последующего вызова функции SnmpRecvMsg для соответствующих параметров этой функции. Если приложению WinSNMP больше не нужны ресурсы, возвращаемые SnmpRecvMsg , приложение должно освободить отдельные ресурсы с помощью функции, соответствующей ресурсу. Дополнительные сведения см. в разделах SnmpFreeEntity и SnmpFreeContext.

Дополнительные сведения см. в разделе Регистрация нескольких ловушек.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winsnmp.h
Библиотека	Wsnmp32.lib
DLL	Wsnmp32.dll