MIB Smithy

Callback Functions

Callback functions are used by the SNMP Session request subcommands to implement asynchronous request functionality. When a request call is made that specifies the -callback option, its value specifies the name of a function to be called when a response is received or when the request times out after the maximum number of configured or specified retries. The general form for a callback function is:

proc callback { id args } { ... }

The id parameter receives the unique handle identifying the outstanding request. This is the same value returned by call to the SNMP Session command that initiated the request and is used to correlate the result and response information to a local cache of information on pending requests.

The args parameter is literal - this is a special function parameter name provided by Tcl that allows for a variable number of arguments to be passed to the function. This parameter receives a list of name+value pairs, suitable for use with Tcl's array set command, providing all of the result and response information applicable to the request. The exact parameters and their order may vary depending on the type of request and its result, which is why args should be used, although the -status value pair is always present. The set of possible parameter names is provided below.

Any Tcl errors that occur in the callback procedure or errors that occur during parsing or processing of received messages will trigger a background error (i.e., usually a call to Tcl's "bgerror" procedure).

Callback Parameters

-address address

This parameter indicates the address from which the message was received. Currently, this should always be the same address as that to which the request was sent, particularly since the SDK will drop responses that come from an address different from that which the request was sent to (which might indicate a man-in-the-middle attack of some sort). In the future it will also be used to indicate the source address of received notifications and requests. In the latter case, it would be the address to which a response should be sent.

-dir direction

Indicates the direction of the message (either send for a message sent or recv for a message received).

-community string

Present only for SNMPv1 and SNMPv2c messages, this parameter the community string extracted from the received message.

-ctxengineid string

Present only for SNMPv3 messages, this parameter's value corresponds to the contextEngineID value extracted from the SNMPv3 scopedPDU.

-ctxname string

Present only for SNMPv3 messages, this parameter's value corresponds to the contextName value extracted from the SNMPv3 scopedPDU.

-eindex integer

This parameter corresponds to the error-index field from the response PDU.

-engineid string

Present only for SNMPv3 messages, this parameter's value corresponds to the msgAuthoritativeEngineID value extracted from the SNMPv3 message header.

-engineboots integer

Present only for SNMPv3 messages, this parameter provides an integer value corresponding to the msgAuthoritativeEngineBoots value extracted from the SNMPv3 message header.

-enginetime integer

Present only for SNMPv3 messages, this parameter provides an integer value corresponding to the msgAuthoritativeEngineTime value extracted from the SNMPv3 message header.

-maxreps count

Present only for received GET-BULK PDUs (which are not presently handled), this parameter indicates the value of the max-repetitions field extracted from the PDU.

-messageid integer

Present only for SNMPv3, this parameter indicates the value of the msgID field extracted from the SNMPv3 message header. For response and report PDUs, this field corresponds to that of the previously sent request that this message was correlated with.

-mpd name

This parameter provides the name of the SNMP Session that generated the request and received the response. This may be used in addition to the id argument to correlate requests to responses. It may also be used in the future to allow scripting handlers for notifications and receiving requests to implement the behavior of an entity acting in an agent role.

-msgflags integer

Present only for SNMPv3 messages, this parameter provides an integer value corresponding to the msgFlags value extracted from the SNMPv3 message header.

-nonreps count

Present only for received GET-BULK PDUs (which are not presently handled), this parameter indicates the value of the non-repeaters field extracted from the PDU.

-pdutype name

This parameter indicates the type of PDU that was received. For callbacks, this is always response or report. For notification handlers, this may be inform, v1trap or v2trap. Additional keywords, reserved for later support, are: get, next, set and bulk.

-port port

This parameter indicates the port from which the message was received. Currently, this should always be the same port as that to which the request was sent, particularly since the SDK will drop responses that come from a port different from that which the request was sent to (which might indicate a man-in-the-middle attack of some sort). In the future it will also be used to indicate the source port of received notifications and requests. In the latter case, it would be the port to which the response should be sent.

-requestid integer

This parameter indicates the value of the request-id field from the received PDU. For response and report PDUs, this field corresponds to that of the previously sent request that this message was correlated with. This field will not be present for SNMPv1 Trap-PDUs (-pdutype v1trap).

-status status

For normal responses, the value provided with this parameter is the keyword associated the error-status field from the response PDU (e.g. noError, noSuchName, etc.). If the received error-status value is not recognized, its value will be unknown. If the request timed out (no response was received), then this will be the only parameter present and its value will be timeout.

-username string

Present only for SNMPv3 messages, this parameter indicates the msgUserName extracted from the security parameters section of the SNMPv3 message header.

-varbinds varBindList

Present for all received PDUs, this parameter indicates the list of Variable Bindings extracted from the PDU. This is a list of { oid type value } triplets, one for each variable, that provide the actual data carried by the PDU. The type for each variable binding will be either the raw ASN.1 type or the derived type, depending on whether or not the oid value corresponds to a known OBJECT-TYPE record in the session's configured SMI Database, and whether or not the raw ASN.1 type specified in the definition matches that of the received message. It may also be NULL for exceptions or error-status values other than noError where the request did not specify a value for the variable.

-version version

This parameter indicates the SNMP version of the received message, and may be SNMPv1, SNMPv2c or SNMPv3. This will usually be the same version as the sent request unless the agent is implemented incorrectly.