snmp_session

Structure that defines a set of transactions with similar transport characteristics

Synopsis:

#include <snmp/snmp_api.h>

struct snmp_session {
    u_char * community;
    int community_len;
    int retries;
    long timeout;
    char * peername;
    u_short remote_port;
    u_short local_port;
    u_char * ( *authenticator )();
    int ( * callback )();
    void * callback_magic;
    int version;
    oid * srcParty;
    int srcPartyLen;
    oid * dstParty;
    int dstPartyLen;
    oid * context;
    int contextLen;
};

Description:

The snmp_session structure describes a set of transactions sharing similar transport characteristics. It includes the following members:

community

The community for outgoing requests. The default is 0.

community_len

The length of the community name. The default is SNMP_DEFAULT_COMMUNITY_LEN (0).

retries

The number of retries before timing out. The default is SNMP_DEFAULT_RETRIES (-1).

timeout

The number of microseconds until the first timeout. Subsequent timeouts increase exponentially. The default is SNMP_DEFAULT_TIMEOUT (-1).

peername

The domain name or dotted IP address of the default peer. The default is SNMP_DEFAULT_PEERNAME (NULL).

remote_port

The UDP port number of the peer. The default is SNMP_DEFAULT_REMPORT (0).

local_port

My UDP port number. The default is SNMP_DEFAULT_ADDRESS (0), for picked randomly.

authenticator

The authentication function, or NULL if null authentication is used. If your application is using version 1 of SNMP, you must supply this member.

The authenticator() function is defined as:

 
u_char* authenticator( u_char* pdu,
                       int* length,
                       u_char* community,
                       int community_len)
      

The arguments are:

• pdu — the rest of the PDU to be authenticated.
• length — the length of the remaining data in the PDU, updated by authenticator().
• community — the community name for authentication.
• community_len — the length of the community name.

To specify null authentication, set the authenticator field in snmp_session to NULL.

The authenticator() function returns an authenticated PDU, or NULL if an error occurs.

callback

A function used to extract the data from the received packet (the snmp_pdu structure passed to the callback). The application must supply this member.

The callback() function is defined as:

int callback( int operation,
              struct snmp_session* session,
              int reqid, 
              struct snmp_pdu* pdu,
              void* magic );
      

The arguments are:

• operation — the possible operations are RECEIVED_MESSAGE and TIMED_OUT.
• session — the session that was authenticated using community.
• reqid — the request ID identifying the transaction within this session. Use 0 for traps.
• pdu — A pointer to PDU information. You must copy the information because it will be freed elsewhere.
• magic — a pointer to the data for callback().

The callback should return 1 on successful completion, or 0 if it should be kept pending.

callback_magic

A pointer to data that the callback function may consider important.

version

The version of SNMP: either SNMP_VERSION_1 or SNMP_VERSION_2.

srcParty

The source party being used for this session.

srcPartyLen

The number of object identifier (OID) elements in srcParty. For example, if srcParty is .1.3.6, the length is 3.

dstParty

The destination party being used for this session.

dstPartyLen

The number of OID elements in dstParty.

context

The context being used for this session.

contextLen

The number of OID elements in context.

Classification:

SNMP

See also:

snmp_close(), snmp_free_pdu(), snmp_open(), snmp_pdu, snmp_send()

Based on RFC 1157, FAQ in Internet newsgroup comp.protocols.snmp

Marshall T. Rose, The Simple Book: An Introduction to Internet Management, Revised 2nd ed. (Prentice-Hall, 1996, ISBN 0-13-451659-1)