eSNMP API Routines
esnmp_register
A subtree is identified by the base MIB name and the corresponding
OID
number
of the node that is the parent of all MIB variables contained in the subtree. For
example: The MIB II
tcp
subtree has an
OID
of
1.3.6.1.2.1.6
. All elements
subordinate to this have the same first seven digits and are included in the
subtree’s object table. The subtree can also be a single MIB object (a leaf node) or
even a specific instance.
By registering a subtree, the subagent indicates that it will process eSNMP
requests for all MIB variables (or
OIDs
) within that subtree’s range. Therefore,
a subagent should register the most fully qualified (longest) subtree that still
contains its instrumented MIB variables.
The master agent does not permit a subagent to register the same subtree more
than once. However, subagents can register subtrees with ranges that overlap
the
OID
ranges of subtrees previously registered, and subagents can also register
subtrees registered by other subagents.
For example, TCP/IP Services supports MIB II. In the eSNMP environment, the
os_mibs
subagent registers the MIB II subtree
ip
(OID 1.3.6.1.2.1.4).
TCP/IP Services also provides the
gated
subagent, which registers the
ipRouteEntry
MIB subtree (OID 1.3.6.1.2.1.4.21.1).
These MIBs are registered at priority 1. Any subagent that registers at a higher
priority (greater than 1) overrides these registrations.
A request for
IpRouteIfIndex
(OID 1.3.5.1.2.1.4.21.1.2) is passed to the
gated
subagent. Requests for other
ip
variables, such as
ipNetToMediaIfIndex
(OID
1.3.5.1.2.1.4.22.1.1) are passed to the
os_mibs
subagent. If the
gated
subagent
terminates or unregisters the
ipRouteEntry
subtree, subsequent requests for
ipRouteIfIndex
will go to the
os_mibs
subagent. This occurs because the
ip
subtree, which includes all
ipRouteEntry
variables, is now the authoritative
region of requests for
ipRouteIfIndex
.
Return Values
SNMP_LIB_OK
The
esnmp_register
routine has completed
successfully.
ESNMP_LIB_BAD_REG
The
esnmp_init
routine has not been called, the
timeout parameter is invalid, or the subtree has
already been queued for registration.
ESNMP_LIB_LOST_
CONNECTION
The subagent has lost communications with the
master agent.
Note that the return value indicates only the initiation of the request. The actual status returned
in the master agent’s response will be returned in a subsequent call to the
esnmp_poll
routine in
the
state
field.
Example
#include <esnmp.h>
#define RESPONSE_TIMEOUT
0
/* use the default time set
in OPEN message */
#define REGISTRATION_PRIORITY 10
/* priority at which subtrees
will register */
int status;
extern SUBTREE ipRouteEntry_subtree;
5–4 eSNMP API Routines
