Función SnmpExtensionQueryEx (snmp.h)

Artículo
08/26/2023

[SNMP está disponible para su uso en los sistemas operativos especificados en la sección Requisitos. En versiones posteriores podría modificarse o no estar disponible. En su lugar, use administración remota de Windows, que es la implementación de Microsoft de WS-Man.]

El servicio SNMP de Microsoft llama a la función SnmpExtensionQueryEx para procesar solicitudes SNMP que especifican variables en uno o varios subárboles MIB registrados por agentes de extensión SNMP. Esta función es un elemento de la API del Agente de extensión SNMP.

Nota Se recomienda usar la función SnmpExtensionQueryEx , que admite los tipos de datos snmp versión 2C (SNMPv2C) y las operaciones SET snmp multifase. El servicio SNMP no llama a la función SnmpExtensionQuery si el agente de extensión exporta la función SnmpExtensionQueryEx .

Sintaxis

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
);

Parámetros

[in] nRequestType

Especifica el tipo de operación que el servicio SNMP solicita al agente de extensión que realice. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
SNMP_EXTENSION_GET	Recupere el valor o los valores de las variables especificadas.
SNMP_EXTENSION_GET_NEXT	Recupere el valor o los valores del sucesor lexicográfico de las variables especificadas.
SNMP_EXTENSION_SET_TEST	Valide los valores de las variables especificadas. Esta operación maximiza la probabilidad de una escritura correcta durante la solicitud COMMIT.
SNMP_EXTENSION_SET_COMMIT	Escriba los nuevos valores en las variables especificadas.
SNMP_EXTENSION_SET_UNDO	Restablezca los valores de las variables especificadas a sus valores antes de la solicitud COMMIT.
SNMP_EXTENSION_SET_CLEANUP	Libere los recursos asignados en solicitudes y operaciones anteriores.

Para obtener información adicional sobre los tipos de solicitud SET, es decir, los que comienzan por SNMP_EXTENSION_SET_, consulte la sección Comentarios siguientes.

[in] nTransactionId

Especifica una variable DWORD que es el identificador único de la solicitud SNMP entrante PDU. El agente de extensión puede usar este valor para correlacionar varias llamadas por el servicio SNMP que implican la misma PDU.

[in, out] pVarBindList

Puntero a la lista de enlaces de variables que contiene las variables de interés.

[in, out] pContextInfo

Puntero a una cadena de octetos que contiene información de contexto definida por el usuario.

El agente de extensión puede usar este parámetro para almacenar la información de contexto utilizada durante las operaciones SET de SNMP multifase. El agente de extensión debe liberar los recursos asociados a este parámetro durante la solicitud CLEANUP. El servicio SNMP no libera ningún recurso asociado a este parámetro. Para obtener más información, vea la siguiente sección Comentarios.

[out] pErrorStatus

Puntero a una variable para recibir el resultado del estado de error. Este parámetro puede ser uno de los siguientes valores definidos por SNMPv2C.

Código de error	Significado
SNMP_ERRORSTATUS_NOERROR	El agente informa de que no se produjeron errores durante la transmisión.
SNMP_ERRORSTATUS_TOOBIG	El agente no pudo colocar los resultados de la operación SNMP solicitada en un único mensaje SNMP.
SNMP_ERRORSTATUS_NOSUCHNAME	La operación SNMP solicitada identificó una variable desconocida.
SNMP_ERRORSTATUS_BADVALUE	La operación SNMP solicitada intentó cambiar una variable, pero especificó un error de sintaxis o valor.
SNMP_ERRORSTATUS_READONLY	La operación SNMP solicitada intentó cambiar una variable que no tenía permiso para cambiar, según el perfil de comunidad de la variable.
SNMP_ERRORSTATUS_GENERR	Error distinto de uno de los enumerados aquí durante la operación SNMP solicitada.
SNMP_ERRORSTATUS_NOACCESS	No se puede acceder a la variable SNMP especificada.
SNMP_ERRORSTATUS_WRONGTYPE	El valor especifica un tipo que es incoherente con el tipo necesario para la variable.
SNMP_ERRORSTATUS_WRONGLENGTH	El valor especifica una longitud que es incoherente con la longitud necesaria para la variable.
SNMP_ERRORSTATUS_WRONGENCODING	El valor contiene una codificación Abstract Syntax Notation One (ASN.1) que es incoherente con la etiqueta ASN.1 del campo.
SNMP_ERRORSTATUS_WRONGVALUE	No se puede asignar el valor a la variable .
SNMP_ERRORSTATUS_NOCREATION	La variable no existe y el agente no puede crearla.
SNMP_ERRORSTATUS_INCONSISTENTVALUE	El valor es incoherente con los valores de otros objetos administrados.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	La asignación del valor a la variable requiere la asignación de recursos que actualmente no están disponibles.
SNMP_ERRORSTATUS_COMMITFAILED	No se produjeron errores de validación, pero no se actualizaron variables.
SNMP_ERRORSTATUS_UNDOFAILED	No se produjo ningún error de validación. Algunas variables se actualizaron porque no era posible deshacer su asignación.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR	Error de autorización.
SNMP_ERRORSTATUS_NOTWRITABLE	La variable existe, pero el agente no puede modificarla.
SNMP_ERRORSTATUS_INCONSISTENTNAME	La variable no existe; el agente no puede crearlo porque la instancia de objeto con nombre es incoherente con los valores de otros objetos administrados.

[out] pErrorIndex

Puntero a una variable para recibir el resultado del índice de error.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es TRUE.

Si se produce un error en la función, el valor devuelto es FALSE.

Comentarios

El servicio SNMP llama a la función SnmpExtensionQueryEx varias veces para procesar una solicitud SET snmp entrante. El servicio puede llamar a SnmpExtensionQueryEx durante la fase de solicitud TEST, la fase de solicitud COMMIT, la fase de solicitud UNDO y la fase de solicitud CLEANUP.

Solicitud TEST

El servicio SNMP procesa un tipo de solicitud SET snmp llamando primero a la función SnmpExtensionQueryEx con dwRequestType de SNMP_EXTENSION_SET_TEST. El servicio llama a cada agente de extensión responsable de los enlaces de variables de la solicitud. Cada agente de extensión debe validar las variables de la lista de enlaces de variables. Opcionalmente, pueden almacenar cualquier información de contexto necesaria para las siguientes solicitudes en la variable a la que apunta el parámetro pContextInfo .

Si se produce un error en la solicitud TEST, el servicio inicia una solicitud CLEANUP. El servicio llama a cada agente de extensión que devolvió previamente TRUE a la solicitud TEST de nuevo con la función SnmpExtensionQueryEx . El servicio llama a cada agente de extensión mediante el SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Solicitud COMMIT

Si todos los agentes de extensión devuelven TRUE a la solicitud TEST, el servicio SNMP llama a cada agente de extensión con la función SnmpExtensionQueryEx mediante el SNMP_EXTENSION_SET_COMMIT dwRequestType. El servicio vuelve a la información de contexto del agente de extensión que el agente de extensión pasó al servicio. Esta es la información de contexto que el agente de extensión pasó en el parámetro pContextInfo durante la solicitud TEST. El agente de extensión puede usar la información de contexto para actualizar los valores de las variables especificadas de forma específica de instrumentación.

Si el agente de extensión admite el procesamiento de reversión, puede actualizar la información de contexto en el parámetro pContextInfo en este momento. El servicio SNMP devuelve la información al agente de extensión durante la solicitud UNDO.

Si todos los agentes de extensión devuelven TRUE a la solicitud COMMIT, el servicio llama a cada agente de extensión con la función SnmpExtensionQueryEx mediante el SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Si algún agente de extensión produce un error en la solicitud COMMIT, el servicio también inicia una solicitud CLEANUP. El servicio llama a cada agente de extensión que devolvió previamente TRUE a la solicitud COMMIT de nuevo con la función SnmpExtensionQueryEx . El servicio llama a cada agente de extensión mediante el SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Solicitud CLEANUP

El servicio devuelve al agente de extensión la información de contexto pasada en el parámetro pContextInfo durante la solicitud TEST o COMMIT. El agente de extensión debe liberar los recursos asociados al parámetro en este momento.

Solicitud UNDO

Si algún agente de extensión devuelve FALSE a la solicitud COMMIT, el servicio SNMP finaliza la solicitud COMMIT. El servicio llama a cada agente de extensión que devolvió TRUE a la solicitud COMMIT con un dwRequestType de SNMP_EXTENSION_SET_UNDO. Esto indica a los agentes de extensión que se produjo un error en la solicitud COMMIT y deben iniciar el procesamiento de reversión.

Los agentes de extensión deben intentar restablecer los valores de las variables de interés, de vuelta a los valores que estaban antes de que se produzca un error en la solicitud COMMIT. Para ello, los agentes de extensión usan la información de contexto devuelta en el parámetro pContextInfo durante la solicitud COMMIT.

Si algún agente de extensión devuelve FALSE a la solicitud UNDO, se produce un error en toda la operación SET con el código de error SNMP_ERRORSTATUS_UNDOFAILED. Si todos los agentes de extensión devuelven TRUE a la solicitud UNDO, se produce un error en la operación SNMP SET con el código de error establecido por el agente de extensión que produjo un error en la solicitud COMMIT.

Después de que el UNDO solicite al servicio siempre llama a cada agente de extensión con la función SnmpExtensionQueryEx , mediante el SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	snmp.h