Функция SnmpExtensionQueryEx (snmp.h)

Статья
08/26/2023

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

Служба Microsoft SNMP вызывает функцию SnmpExtensionQueryEx для обработки запросов SNMP, указывающих переменные в одном или нескольких поддеревьях MIB, зарегистрированных агентами расширения SNMP. Эта функция является элементом API агента расширения SNMP.

Примечание Рекомендуется использовать функцию SnmpExtensionQueryEx , которая поддерживает типы данных SNMP версии 2C (SNMPv2C) и многофазные операции SNMP SET. Служба SNMP не вызывает функцию SnmpExtensionQuery, если агент расширения экспортирует функцию SnmpExtensionQueryEx .

Синтаксис

BOOL SNMP_FUNC_TYPE SnmpExtensionQueryEx(
  [in]      UINT            nRequestType,
  [in]      UINT            nTransactionId,
  [in, out] SnmpVarBindList *pVarBindList,
  [in, out] AsnOctetString  *pContextInfo,
  [out]     AsnInteger32    *pErrorStatus,
  [out]     AsnInteger32    *pErrorIndex
);

Параметры

[in] nRequestType

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

Значение	Значение
SNMP_EXTENSION_GET	Получение значения или значений указанных переменных.
SNMP_EXTENSION_GET_NEXT	Получение значения или значений лексикографического преемника указанных переменных.
SNMP_EXTENSION_SET_TEST	Проверьте значения указанных переменных. Эта операция максимально повышает вероятность успешной записи во время запроса COMMIT.
SNMP_EXTENSION_SET_COMMIT	Запишите новые значения в указанные переменные.
SNMP_EXTENSION_SET_UNDO	Сбросьте значения указанных переменных до их значений до запроса COMMIT.
SNMP_EXTENSION_SET_CLEANUP	Освобождение ресурсов, выделенных в предыдущих запросах и операциях.

Дополнительные сведения о типах запросов SET, то есть тех, которые начинаются с SNMP_EXTENSION_SET_, см. в следующем разделе Примечания.

[in] nTransactionId

Указывает переменную DWORD , которая является уникальным идентификатором PDU входящего SNMP-запроса. Агент расширения может использовать это значение для корреляции нескольких вызовов службы SNMP, которые используют один И тот же PDU.

[in, out] pVarBindList

Указатель на список привязок переменных, содержащий интересующие переменные.

[in, out] pContextInfo

Указатель на строку октета, содержащую определяемые пользователем сведения о контексте.

Агент расширения может использовать этот параметр для хранения контекстных сведений, используемых во время многофазных операций SNMP SET. Агент расширения должен освободить ресурсы, связанные с этим параметром, во время запроса CLEANUP. Служба SNMP не освобождает ресурсы, связанные с этим параметром. Дополнительные сведения см. в следующем разделе Примечаний.

[out] pErrorStatus

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

Код ошибки	Значение
SNMP_ERRORSTATUS_NOERROR	Агент сообщает, что во время передачи не произошло никаких ошибок.
SNMP_ERRORSTATUS_TOOBIG	Агенту не удалось поместить результаты запрошенной операции SNMP в одно сообщение SNMP.
SNMP_ERRORSTATUS_NOSUCHNAME	Запрошенная операция SNMP идентифицировала неизвестную переменную.
SNMP_ERRORSTATUS_BADVALUE	Запрошенная операция SNMP попыталась изменить переменную, но указала ошибку синтаксиса или значения.
SNMP_ERRORSTATUS_READONLY	Запрошенная операция SNMP попыталась изменить переменную, которую нельзя было изменить в соответствии с профилем сообщества переменной.
SNMP_ERRORSTATUS_GENERR	Во время запрошенной операции SNMP произошла ошибка, отличавшаяся от одной из перечисленных здесь.
SNMP_ERRORSTATUS_NOACCESS	Указанная переменная SNMP недоступна.
SNMP_ERRORSTATUS_WRONGTYPE	Значение указывает тип, несовместимый с типом, необходимым для переменной.
SNMP_ERRORSTATUS_WRONGLENGTH	Значение указывает длину, которая не соответствует длине, необходимой для переменной.
SNMP_ERRORSTATUS_WRONGENCODING	Значение содержит кодировку ASN.1, которая несовместима с тегом ASN.1 поля.
SNMP_ERRORSTATUS_WRONGVALUE	Значение не может быть присвоено переменной.
SNMP_ERRORSTATUS_NOCREATION	Переменная не существует, и агент не может создать ее.
SNMP_ERRORSTATUS_INCONSISTENTVALUE	Значение несовместимо со значениями других управляемых объектов.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	Чтобы присвоить значение переменной, необходимо выделить ресурсы, которые в настоящее время недоступны.
SNMP_ERRORSTATUS_COMMITFAILED	Ошибок проверки не произошло, но переменные не были обновлены.
SNMP_ERRORSTATUS_UNDOFAILED	Ошибок проверки не произошло. Некоторые переменные были обновлены, так как невозможно было отменить их назначение.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	Произошла ошибка авторизации.
SNMP_ERRORSTATUS_NOTWRITABLE	Переменная существует, но агент не может ее изменить.
SNMP_ERRORSTATUS_INCONSISTENTNAME	Переменная не существует; Агент не может создать его, так как именованный экземпляр объекта не соответствует значениям других управляемых объектов.

[out] pErrorIndex

Указатель на переменную для получения результата индекса ошибки.

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

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

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

Служба SNMP вызывает функцию SnmpExtensionQueryEx несколько раз для обработки входящего запроса SNMP SET. Служба может вызывать SnmpExtensionQueryEx во время этапа запроса TEST, этапа запроса COMMIT, этапа запроса UNDO и этапа запроса CLEANUP.

ЗАПРОС TEST

Служба SNMP обрабатывает тип запроса SNMP SET, сначала вызывая функцию SnmpExtensionQueryEx с dwRequestType SNMP_EXTENSION_SET_TEST. Служба вызывает каждый агент расширения, отвечающий за привязки переменных в запросе. Каждый агент расширения должен проверять переменные в списке привязки переменных. При необходимости они могут хранить любые сведения о контексте, необходимые для следующих запросов, в переменной, на которую указывает параметр pContextInfo .

Если запрос TEST завершается сбоем, служба инициирует запрос CLEANUP. Служба вызывает каждый агент расширения, который ранее вернул true в запрос TEST с помощью функции SnmpExtensionQueryEx . Служба вызывает каждый агент расширения, используя SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Запрос COMMIT

Если все агенты расширения возвращают true в запрос TEST, служба SNMP вызывает каждый агент расширения с функцией SnmpExtensionQueryEx , используя SNMP_EXTENSION_SET_COMMIT dwRequestType. Служба возвращает сведения о контексте агента расширения, которые агент расширения передал службе. Это контекстная информация, переданная агентом расширения в параметре pContextInfo во время запроса TEST. Агент расширения может использовать сведения контекста для обновления значений указанных переменных в определенном инструментировании способом.

Если агент расширения поддерживает обработку отката, он может обновить сведения о контексте в параметре pContextInfo в данный момент. Служба SNMP передает сведения обратно агенту расширения во время запроса UNDO.

Если все агенты расширения возвращают true в запрос COMMIT, служба вызывает каждый агент расширения с функцией SnmpExtensionQueryEx , используя SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Если какой-либо агент расширения не выполняет запрос COMMIT, служба также инициирует запрос CLEANUP. Служба вызывает каждый агент расширения, который ранее вернул true в запрос COMMIT с помощью функции SnmpExtensionQueryEx . Служба вызывает каждый агент расширения, используя SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Запрос CLEANUP

Служба возвращает агенту расширения сведения о контексте, переданные в параметре pContextInfo во время запроса TEST или COMMIT. В данный момент агент расширения должен освободить ресурсы, связанные с параметром .

Запрос UNDO

Если какой-либо агент расширения возвращает значение FALSE в запрос COMMIT, служба SNMP завершает запрос COMMIT. Служба вызывает каждый агент расширения, возвращающий true в запрос COMMIT, с dwRequestType SNMP_EXTENSION_SET_UNDO. Это сигнализирует агентам расширения о том, что запрос COMMIT завершился сбоем, и они должны инициировать обработку отката.

Агенты расширения должны попытаться сбросить значения интересующих переменных, вернувшись к значениям, которые они были до сбоя запроса COMMIT. Для этого агенты расширения используют сведения о контексте, возвращенные в параметре pContextInfo во время запроса COMMIT.

Если какой-либо агент расширения возвращает false в запрос UNDO, вся операция SET завершается ошибкой с кодом SNMP_ERRORSTATUS_UNDOFAILED. Если все агенты расширения возвращают значение TRUE в запрос UNDO, операция SNMP SET завершается сбоем с кодом ошибки, заданным агентом расширения, который не выполнил запрос COMMIT.

После запроса UNDO служба всегда вызывает каждый агент расширения с функцией SnmpExtensionQueryEx , используя SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Требования

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