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

Статья
03/13/2024

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

Функция SnmpCreateSession запрашивает реализацию Microsoft WinSNMP, чтобы открыть сеанс для приложения WinSNMP. Приложение может указать, как реализация должна информировать сеанс WinSNMP о доступных сообщениях SNMP и асинхронных событиях. Приложение может указать уведомление окна или функцию SNMPAPI_CALLBACK для уведомления сеанса.

Функция SnmpCreateSession является элементом API WinSNMP версии 2.0. При разработке новых приложений WinSNMP рекомендуется вызывать SnmpCreateSession , чтобы открыть сеанс WinSNMP вместо функции SnmpOpen .

Синтаксис

HSNMP_SESSION SNMPAPI_CALL SnmpCreateSession(
  [in] HWND             hWnd,
  [in] UINT             wMsg,
  [in] SNMPAPI_CALLBACK fCallBack,
  [in] LPVOID           lpClientData
);

Параметры

[in] hWnd

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

[in] wMsg

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

[in] fCallBack

Указывает адрес определяемой приложением функции SNMPAPI_CALLBACK сеанса. Реализация вызовет эту функцию для информирования сеанса WinSNMP о доступности уведомлений.

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

[in] lpClientData

Указатель на определяемые приложением данные для передачи функции обратного вызова, заданной параметром fCallback . Этот параметр является необязательным и может иметь значение NULL. Если параметр fCallback имеет значение NULL, реализация игнорирует этот параметр.

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

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

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

Код возврата	Описание
SNMPAPI_NOT_INITIALIZED	Не удалось выполнить функцию SnmpStartup .
SNMPAPI_ALLOC_ERROR	Ошибка при выделении памяти.
SNMPAPI_HWND_INVALID	Параметр fCallback имеет значение NULL, но параметр hWnd не является допустимым дескриптором окна.
SNMPAPI_MESSAGE_INVALID	Параметр fCallback имеет значение NULL, но параметр wMsg не является допустимым значением сообщения.
SNMPAPI_MODE_INVALID	Параметр fCallback имеет значение NULL , а параметры hWnd и wMsg действительны по отдельности. Однако значения на платформе Windows несовместимы друг с другом.
SNMPAPI_OPERATION_INVALID	Сочетание значений параметров не указывает уведомления о обратном вызове или сообщения уведомлений о окне.
SNMPAPI_OTHER_ERROR	Произошла неизвестная или неопределенная ошибка.

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

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

Уведомления обратного вызова

Если параметр fCallback не равен NULL при успешном вызове функции SnmpCreateSession , реализация оповещает сеанс о уведомлениях с помощью функции обратного вызова, указанной параметром fCallback .

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

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Сообщения уведомлений о окне

Функция SnmpCreateSession передает в реализацию дескриптор в окно приложения и идентификатор сообщения уведомления. Когда окно приложения получает сообщение уведомления, указанное параметром wMsg , приложение WinSNMP должно получить единицу данных входящего протокола (PDU). Приложение делает это путем вызова функции SnmpRecvMsg с дескриптором сеанса, возвращенным SnmpCreateSession.

Одно приложение WinSNMP может открывать несколько сеансов WinSNMP. Если приложение открывает несколько сеансов с использованием одного дескриптора окна, рекомендуется, чтобы приложение WinSNMP указало уникальный параметр wMsg для каждого сеанса.

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

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

Требования

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