[This is preliminary documentation and subject to change.]
The Microsoft SNMP service calls the SnmpExtensionQueryEx function to process SNMP requests that specify variables in one or more MIB subtrees registered by SNMP extension agents. This function is an element of the SNMP Extension Agent API.
Note It is recommended that you use the SnmpExtensionQueryEx function, which supports SNMP version 2C (SNMPv2C) data types and multiphase SNMP SET operations. However, the extension agent must also export the SnmpExtensionQuery function if the extension agent runs on Windows NT 3.51 or 4.0. The SNMP service does not call the SnmpExtensionQuery function if the extension agent exports the SnmpExtensionQueryEx function.
BOOL SnmpExtensionQueryEx(
DWORD dwRequestType, // extension agent request type
DWORD dwTransactionId, // identifier of the incoming PDU
SnmpVarBindList *pVarBindList, // pointer to variable binding list
AsnOctetString *pContextInfo, // pointer to context information
AsnInteger32 *pErrorStatus, // pointer to SNMPv2 error status
AsnInteger32 *pErrorIndex // pointer to the error index
);
| Value | Meaning |
|---|---|
| SNMP_EXTENSION_GET | Retrieve the value or values of the specified variables. |
| SNMP_EXTENSION_GET_NEXT | Retrieve the value or values of the lexicographic successor of the specified variables. |
| SNMP_EXTENSION_SET_TEST | Validate the values of the specified variables. This operation maximizes the probability of a successful write during the COMMIT request. |
| SNMP_EXTENSION_SET_COMMIT | Write the new values to the specified variables. |
| SNMP_EXTENSION_SET_UNDO | Reset the values of the specified variables to their values before the COMMIT request. |
| SNMP_EXTENSION_SET_ CLEANUP |
Release the resources allocated in previous requests and operations. |
For additional information about the SET request types, that is, those that begin with SNMP_EXTENSION_SET_, see the following Remarks section.
The extension agent can use this parameter to store context information used during multiphase SNMP SET operations. The extension agent must release resources associated with this parameter during the CLEANUP request. The SNMP service does not release any resources associated with this parameter. For additional information, see the following Remarks section.
| Error Code | Meaning |
|---|---|
| SNMP_ERROR_NOERROR | The agent reports that no errors occurred during transmission. |
| SNMP_ERROR_TOOBIG | The agent could not place the results of the requested SNMP operation into a single SNMP message. |
| SNMP_ERROR_NOSUCHNAME | The requested SNMP operation identified an unknown variable. |
| SNMP_ERROR_BADVALUE | The requested SNMP operation tried to change a variable but it specified either a syntax or value error. |
| SNMP_ERROR_READONLY | The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable. |
| SNMP_ERROR_GENERR | An error other than one of those listed here occurred during the requested SNMP operation. |
| SNMP_ERROR_NOACCESS | The specified SNMP variable is not accessible. |
| SNMP_ERROR_WRONGTYPE | The value specifies a type that is inconsistent with the type required for the variable. |
| SNMP_ERROR_WRONGLENGTH | The value specifies a length that is inconsistent with the length required for the variable. |
| SNMP_ERROR_WRONGENCODING | The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field. |
| SNMP_ERROR_WRONGVALUE | The value cannot be assigned to the variable. |
| SNMP_ERROR_NOCREATION | The variable does not exist, and the agent cannot create it. |
| SNMP_ERROR_ INCONSISTENTVALUE |
The value is inconsistent with values of other managed objects. |
| SNMP_ERROR_ RESOURCEUNAVAILABLE |
Assigning the value to the variable requires allocation of resources that are currently unavailable. |
| SNMP_ERROR_COMMITFAILED | No validation errors occurred, but no variables were updated. |
| SNMP_ERROR_UNDOFAILED | No validation errors occurred. Some variables were updated because it was not possible to undo their assignment. |
| SNMP_ERROR_ AUTHORIZATIONERROR |
An authorization error occurred. |
| SNMP_ERROR_NOTWRITABLE | The variable exists but the agent cannot modify it. |
| SNMP_ERROR_ INCONSISTENTNAME |
The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects. |
If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
The SNMP service calls the SnmpExtensionQueryEx function multiple times to process an incoming SNMP SET request. The service can call SnmpExtensionQueryEx during the TEST request phase, the COMMIT request phase, the UNDO request phase, and the CLEANUP request phase.
TEST request
The SNMP service processes an SNMP SET request type by first calling the SnmpExtensionQueryEx function with a dwRequestType of SNMP_EXTENSION_SET_TEST. The service calls each extension agent responsible for the variable bindings in the request. Each extension agent must validate the variables in the variable binding list. They can optionally store any context information required for the following requests in the variable pointed to by the pContextInfo parameter.
If the TEST request fails, the service initiates a CLEANUP request. The service calls each extension agent that previously returned TRUE to the TEST request again with the SnmpExtensionQueryEx function. The service calls each extension agent using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.
COMMIT request
If all extension agents return TRUE to the TEST request, the SNMP service calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_COMMIT dwRequestType. The service returns to the extension agent context information that the extension agent passed to the service. This is the context information the extension agent passed in the pContextInfo parameter during the TEST request. The extension agent can use the context information to update the values of the specified variables in an instrumentation-specific manner.
If the extension agent supports rollback processing, it can update the context information in the pContextInfo parameter at this time. The SNMP service passes the information back to the extension agent during the UNDO request.
If all extension agents return TRUE to the COMMIT request, the service calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.
If any extension agent fails the COMMIT request, the service also initiates a CLEANUP request. The service calls each extension agent that previously returned TRUE to the COMMIT request again with the SnmpExtensionQueryEx function. The service calls each extension agent using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.
CLEANUP request
The service returns to the extension agent the context information passed in the pContextInfo parameter during the TEST or COMMIT request. The extension agent must release the resources associated with the parameter at this time.
UNDO request
If any extension agent returns FALSE to the COMMIT request, the SNMP service terminates the COMMIT request. The service calls each extension agent that returned TRUE to the COMMIT request with a dwRequestType of SNMP_EXTENSION_SET_UNDO. This signals the extension agents that the COMMIT request failed, and they must initiate rollback processing.
The extension agents must attempt to reset the values of the variables of interest, back to the values they were before the COMMIT request failed. To do this, the extension agents use the context information returned in the pContextInfo parameter during the COMMIT request.
If any extension agent returns FALSE to the UNDO request, the entire SET operation fails with the error code SNMP_ERRORSTATUS_UNDOFAILED. If all extension agents return TRUE to the UNDO request, the SNMP SET operation fails with the error code set by the extension agent that failed the COMMIT request.
After the UNDO request the service always calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.
Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in snmp.h.
Import Library: User-defined.
Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionQuery, AsnOctetString, SnmpVarBindList