SNMP_SESS_API(3)

NAME
snmp_sess_init, snmp_sess_open, snmp_sess_session, snmp_sess_send, snmp_sess_async_send, snmp_sess_read, snmp_sess_select_info, snmp_sess_timeout, snmp_sess_close, snmp_sess_error

SYNOPSIS
cc [ flag ... ] file ... -lsnmp [ library ... ]

#include <sys/types.h>
#include <snmp/snmp.h>

void snmp_sess_init (struct snmp_session * Session);

void *snmp_sess_open (struct snmp_session * Session);

struct snmp_session* snmp_sess_session (void * Opaque);

int snmp_sess_synch_response(void * Opaque, struct snmp_pdu * PDU, struct snmp_pdu ** ResponsePDUP);

int snmp_sess_send (void * Opaque, struct snmp_pdu * PDU);

int snmp_sess_async_send (void * Opaque, struct snmp_pdu * PDU, snmp_callback Callback, void * CallbackData);

int snmp_sess_select_info (void * Opaque, int * numfds, fd_set * fdset, struct timeval * timeout, int * block);

void snmp_sess_read (void * Opaque, fd_set * fdset);

void snmp_sess_timeout (void * Opaque);

int snmp_sess_close (void * Opaque);

void snmp_sess_error (void * Opaque, int * syserrno, int * snmp_errno, char ** errorString);

STRUCTURE
The snmp_session structure is:
    int		Version;	/* SNMP Version for this session */
    u_char *		community;	/* community for outgoing requests. */
    int		community_len;	/* Length of community name. */
    int		retries;	/* Number of retries before timeout. */
    int		timeout;	/* uS 'til timeout, then exp. backoff */
    char *		peername;	/* Default peer (name or IP) */
    unsigned short	remote_port;	/* UDP port number of peer. */
    unsigned short	local_port;	/* My UDP port number, 0 for default */
    int		(*callback)();	/* Func. to interpret incoming data */
    /* Pointer to data that the callback function may consider important */
    void *		callback_magic;
    struct synch_state * snmp_synch_state;
    int		syserrno;	/* copy of system errno */
    int		snmp_errno;	/* copy of library errno */

DESCRIPTION
These functions define a subset of the API that can be used to manage single SNMP sessions in a multi-threaded application. Except for snmp_sess_init and snmp_sess_session, these functions are single session versions of the traditional SNMP library API.

Note that these functions use an Opaque pointer to identify a single session in lieu of a session pointer.

SNMP sessions that are created with snmp_sess_open are not affected by and should not be used with snmp_select_info, snmp_read, snmp_timeout, nor snmp_close. Use the other functions described here with similar capabilities.

snmp_sess_init() initializes the input Session structure.

snmp_sess_open() opens the specified session.

snmp_sess_session() returns the pointer to Session structure.

snmp_sess_close() closes the specified session.

snmp_sess_synch_response() is a quick way to send PDU over session Session and wait for a response. The response will be pointed to by ResponsePDUP.

snmp_sess_send() sends PDU over Session. If the PDU will receive a response (GET, GETNEXT, INFORM, etc), the pending response is registered, and the callback specified in the session will be called at the appropriate time.

snmp_sess_read() will read all pending SNMP data from the ssession. Once the packet is read, a PDU will be created, and if this response was being waited for, the callback will be called.

snmp_sess_select_info() Returns info about what snmp requires from a select statement. numfds is the number of fds in the list that are significant. All file descriptors opened via this API are OR'd into the fdset. If activity occurs on any of these file descriptors, snmp_sess_read() should be called with that file descriptor set.

timeout is the latest time that the API can wait for a timeout. The select should be done with the minimum time between timeout and any other timeouts necessary. This should be checked upon each invocation of select(). If a timeout is received, snmp_sess_timeout() should be called to check if the timeout was for the SNMP API.

block is 1 if the select is requested to block indefinitely, rather than time out. If block is input as 1, timeout will be treated as undefined, but it must be available for setting in snmp_sess_select_info(). On return, if block is true, the value of timeout will be undefined.

snmp_sess_timeout() should be called whenever the timeout from select() expires. It may also be polled (probably a cpu expensive proposition). snmp_sess_timeout() checks to see if any of the sessions have an outstanding request that has timed out. If it finds one (or more), and that pdu has more retries available, a new packet is formed from the pdu and is resent. If there are no more retries available, the callback for the session is used to alert the user of the timeout.

snmp_sess_error() returns a copy of the SNMP library "snmp_errno" variable, the system "errno" variable, and a string interpreting their values. The string must be freed after use.

RETURN VALUES
snmp_sess_open() returns an Opaque pointer to the open session, or NULL. If NULL is returned, more information can be had by calling snmp_error().

snmp_sess_close() returns 1 upon success, 0 otherwise.

snmp_sess_send() Returns the Request ID of the generated packet if applicable, otherwise 1. Returns 0 upon error.

snmp_sess_select_info() returns the number of open sockets.

snmp_sess_synch_response() returns either STAT_SUCCESS, STAT_TIMEOUT, or STAT_ERROR.

RFCS
Related RFCs: 1065, 1066, 1067
Related SNMPv2 RFCs: 1901, 1902, 1902, 1904, 1905, 1906, 1907, 1908, 1909

RELATED URLS
CMU Networking Group: http://www.net.cmu.edu/
CMU SNMP Home Page: http://www.net.cmu.edu/projects/snmp

SEE ALSO
snmp_api(3), snmp_api_errors(3), snmp_client(3), snmp_coexistance(3), snmp_error(3), snmp_extra(3), snmp_mib(3), snmp_mibii(3), snmp_mini_client(3), snmp_msg(3), snmp_packet_dump(3), snmp_pdu(3), snmp_sess_api(3), snmp_vars(3), snmp_version_info(3), snmp_oid(5) snmp(3)