Skip to main content

4. Dispatcher Elements of Procedure

4.1. Sending an SNMP Message to the Network​

This section describes the procedure followed by the Dispatcher when an application wants to send an SNMP PDU to another SNMP entity.

4.1.1. Sending a Request or Notification​

The following procedures are followed when an application wants to send an SNMP Request or Notification to the network.

Procedure:

  1. An application requests the Dispatcher send an SNMP PDU by calling the Dispatcher using the abstract sendPdu service interface primitive:
statusInformation = sendPdu(
    IN transportDomain,           -- transport domain to be used
    IN transportAddress,          -- destination network address
    IN messageProcessingModel,    -- typically, SNMP version
    IN securityModel,             -- Security Model to use
    IN securityName,              -- on behalf of this principal
    IN securityLevel,             -- Level of Security requested
    IN contextEngineID,           -- data from/at this SNMP entity
    IN contextName,               -- data from/in this context
    IN pduVersion,                -- the version of the PDU
    IN PDU,                       -- SNMP Protocol Data Unit
    IN expectResponse,            -- TRUE or FALSE
    IN sendPduHandle              -- the handle for matching incoming replies
)

  1. If the messageProcessingModel value does not represent a Message Processing Model known to the Dispatcher, then an errorIndication (unsupportedMsgProcessingModel) is returned to the calling application. Processing of this message is halted.

  2. The Dispatcher requests the appropriate Message Processing Model to prepare a message, according to its message format specification:

statusInformation = prepareOutgoingMessage(
    IN transportDomain,           -- as specified by application
    IN transportAddress,          -- as specified by application
    IN messageProcessingModel,    -- as specified by application
    IN securityModel,             -- as specified by application
    IN securityName,              -- as specified by application
    IN securityLevel,             -- as specified by application
    IN contextEngineID,           -- as specified by application
    IN contextName,               -- as specified by application
    IN pduVersion,                -- as specified by application
    IN PDU,                       -- as specified by application
    IN expectResponse,            -- as specified by application
    IN sendPduHandle,             -- as determined by application
    OUT destTransportDomain,      -- destination transport domain
    OUT destTransportAddress,     -- destination transport address
    OUT outgoingMessage,          -- the message to send
    OUT outgoingMessageLength     -- its length
)

  1. If the statusInformation in the statusInformation parameter is not success, the Dispatcher returns the statusInformation to the calling application. Processing of the message is halted.

  2. If the statusInformation is success, the Dispatcher sends the prepared message over the transport specified by the transportDomain and transportAddress to the network.

  3. The Dispatcher returns success to the calling application.

4.1.2. Sending a Response to the Network​

The following procedure is followed when an application wants to send a response to the network.

Procedure:

  1. An application requests the Dispatcher to send an SNMP PDU by calling the Dispatcher using the returnResponsePdu abstract service interface:
result = returnResponsePdu(
    IN messageProcessingModel,    -- typically, SNMP version
    IN securityModel,             -- Security Model in use
    IN securityName,              -- on behalf of this principal
    IN securityLevel,             -- same as on incoming request
    IN contextEngineID,           -- data from/at this SNMP entity
    IN contextName,               -- data from/in this context
    IN pduVersion,                -- the version of the PDU
    IN PDU,                       -- SNMP Protocol Data Unit
    IN maxSizeResponseScopedPDU,  -- maximum size of the Response PDU
    IN stateReference,            -- reference to state information
    IN statusInformation          -- success or errorIndication
)

Note: the abstract data elements securityModel, securityName, securityLevel, contextEngineID, contextName, and stateReference should be the same as the values originally determined when the request was received and passed to the application. These values may be retrieved from a cache using the stateReference as a key.

  1. If the messageProcessingModel value does not represent a Message Processing Model known to the Dispatcher, then an errorIndication (unsupportedMsgProcessingModel) is returned to the calling application. Processing of this message is halted.

  2. The Dispatcher requests the appropriate Message Processing Model to prepare a response message according to its message format specification:

result = prepareResponseMessage(
    IN messageProcessingModel,    -- as provided by application
    IN securityModel,             -- as provided by application
    IN securityName,              -- as provided by application
    IN securityLevel,             -- as provided by application
    IN contextEngineID,           -- as provided by application
    IN contextName,               -- as provided by application
    IN pduVersion,                -- as provided by application
    IN PDU,                       -- as provided by application
    IN maxSizeResponseScopedPDU,  -- as provided by application
    IN stateReference,            -- as provided by application
    IN statusInformation,         -- as provided by application
    OUT destTransportDomain,      -- destination transport domain
    OUT destTransportAddress,     -- destination transport address
    OUT outgoingMessage,          -- the message to send
    OUT outgoingMessageLength     -- its length
)

  1. If the result in the result parameter is not success, the Dispatcher returns the errorIndication to the calling application. Processing of the message is halted.

  2. If the result is success, the Dispatcher sends the prepared message over the transport specified by the destTransportDomain and destTransportAddress to the network.

  3. The Dispatcher returns success to the calling application.

4.2. Receiving an SNMP Message from the Network​

This section describes the procedure followed by the Dispatcher when it receives an SNMP message from the network.

4.2.1. Message Dispatching of received SNMP Messages​

The following procedures are followed when the Dispatcher receives an SNMP Message from the network:

  1. The Dispatcher receives a message from the network.

  2. The Dispatcher determines the version of the SNMP message. If the packet cannot be sufficiently parsed to determine the version, the snmpInASNParseErrs counter [RFC3418] is incremented, and the message is discarded without further processing. Processing of this message is halted.

  3. The Dispatcher determines the appropriate Message Processing Model based on the SNMP message version.

  4. If the SNMP Message version is not known to the Dispatcher, the snmpInBadVersions counter [RFC3418] is incremented, and the message is discarded without further processing. Processing of this message is halted.

4.2.2. PDU Dispatching for Incoming Messages​

After message dispatching determines the Message Processing Model, the following abstract service interface is used to request that the Message Processing Model extract the PDU and data from the message:

result = prepareDataElements(
    IN transportDomain,           -- origin transport domain
    IN transportAddress,          -- origin transport address
    IN wholeMsg,                  -- as received from the network
    IN wholeMsgLength,            -- as received from the network
    OUT messageProcessingModel,   -- typically, SNMP version
    OUT securityModel,            -- Security Model in use
    OUT securityName,             -- on behalf of this principal
    OUT securityLevel,            -- Level of Security requested
    OUT contextEngineID,          -- data from/at this SNMP entity
    OUT contextName,              -- data from/in this context
    OUT pduVersion,               -- the version of the PDU
    OUT PDU,                      -- SNMP Protocol Data Unit
    OUT pduType,                  -- SNMP PDU type
    OUT sendPduHandle,            -- handle for matched request
    OUT maxSizeResponseScopedPDU, -- maximum size of Response PDU
    OUT statusInformation,        -- success or errorIndication
    OUT stateReference            -- reference to state information
)

If the result errorIndication is set to a value other than noError, the message is discarded without further processing. Processing of this message is halted.

4.2.2.1. Incoming Requests and Notifications​

The following procedure is followed for the dispatching of PDUs when the value of the pduType indicates that the message contains a Request or Notification:

  1. Based on the pduType, contextEngineID, and contextName, an appropriate application is selected.

    a) If no application is registered for the combination of pduType, contextEngineID, and contextName, and if no application is registered for pduType and contextEngineID with a null contextName, then:

    • If the pduType is confirmed, a Report PDU is sent to the originator of the message. The Dispatcher calls an appropriate Message Processing Model to generate an error report using the reportPDU abstract service interface primitive:
result = reportPDU(
    IN messageProcessingModel,    -- typically, SNMP version
    IN securityModel,             -- Security Model in use
    IN securityName,              -- on behalf of this principal
    IN securityLevel,             -- same as on incoming request
    IN contextEngineID,           -- data from/at this SNMP entity
    IN contextName,               -- data from/in this context
    IN pduVersion,                -- the version of the PDU
    IN PDU,                       -- SNMP Protocol Data Unit
    IN maxSizeResponseScopedPDU,  -- maximum size of the Response PDU
    IN stateReference,            -- reference to state information
    IN statusInformation          -- error indication
)
  - The message is discarded. Processing of this message is halted.

b) If the pduType is unconfirmed, the message is discarded. Processing of this message is halted.

  1. The PDU is dispatched to the application, using the processPdu abstract service interface:
processPdu(
    IN messageProcessingModel,    -- typically, SNMP version
    IN securityModel,             -- Security Model in use
    IN securityName,              -- on behalf of this principal
    IN securityLevel,             -- Level of Security
    IN contextEngineID,           -- data from/at this SNMP entity
    IN contextName,               -- data from/in this context
    IN pduVersion,                -- the version of the PDU
    IN PDU,                       -- SNMP Protocol Data Unit
    IN maxSizeResponseScopedPDU,  -- maximum size of Response PDU
    IN stateReference             -- reference to state information
)

4.2.2.2. Incoming Responses​

The following procedure is followed for the dispatching of PDUs when the pduType indicates a Response, Report, or other Class 2 type PDU:

  1. The value in the sendPduHandle is used to determine to which application the PDU should be dispatched.

  2. If no application registration is found, the snmpUnknownPDUHandlers counter [RFC3418] is incremented, and the message is discarded. Processing of this message is halted.

  3. Otherwise, the message is dispatched to the application using the processResponsePdu abstract service interface:

processResponsePdu(
    IN messageProcessingModel,    -- typically, SNMP version
    IN securityModel,             -- Security Model in use
    IN securityName,              -- on behalf of this principal
    IN securityLevel,             -- Level of Security
    IN contextEngineID,           -- data from/at this SNMP entity
    IN contextName,               -- data from/in this context
    IN pduVersion,                -- the version of the PDU
    IN PDU,                       -- SNMP Protocol Data Unit
    IN statusInformation,         -- success or errorIndication
    IN sendPduHandle              -- handle for matched request
)

4.3. Application Registration for Handling PDU types​

Applications that want to process certain PDUs must register with the PDU Dispatcher. Applications specify the combination of pduType, contextEngineID, and contextName for which they want to take responsibility.

The following procedure is followed for application registration:

  1. An application calls the PDU Dispatcher using the registerContextEngineID abstract service interface primitive:
statusInformation = registerContextEngineID(
    IN contextEngineID,           -- take responsibility for this one
    IN pduType                    -- the pduType(s) to be registered
)

  1. If another application has already registered for the specified contextEngineID and pduType, an errorIndication (duplicateRegistration) is returned to the calling application. Processing of the registration is halted.

  2. Otherwise, the registration is saved by the PDU Dispatcher, and success is returned.

4.4. Application Unregistration for Handling PDU Types​

Applications that no longer want to process certain types of PDUs must unregister with the PDU Dispatcher. The application must specify the combination of contextEngineID and pduType for which it no longer wants to take responsibility.

The following procedure is followed for application unregistration:

  1. An application calls the PDU Dispatcher using the unregisterContextEngineID abstract service interface primitive:
unregisterContextEngineID(
    IN contextEngineID,           -- give up responsibility for this
    IN pduType                    -- the pduType(s) to be unregistered
)

  1. If an application registration is found, it is deleted.

  2. If no such registration is found, the request is ignored.

Last updated on