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

Community for outgoing requests. The default is 0.

community_len

Length of community name. The default is SNMP_DEFAULT_COMMUNITY_LEN (0).

retries

Number of retries before timeout. The default is SNMP_DEFAULT_RETRIES (-1).

timeout

Number of microseconds until first timeout. Subsequent timeouts increase exponentiallly. The default is SNMP_DEFAULT_TIMEOUT (-1).

peername

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

remote_port

UDP port number of 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

Authentication function or NULL if null authentication is used. If your application is using version 1 of SNMP, the application 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 (0).

The authenticator() function should return an authenticated PDU, or NULL if an error occurred.

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

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()

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)