SNMP_API(3)

NAME
snmp_open, snmp_build, snmp_parse, snmp_send, snmp_read, snmp_select_info, snmp_timeout, snmp_close, snmp_api_stats

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

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

struct snmp_session *snmp_open(struct snmp_session * Session);

int snmp_close(struct snmp_session * Session);

int snmp_build(struct snmp_session * Session, struct snmp_pdu * PDU, unsigned char * Packet, int * OutLen

unsigned char *snmp_parse(struct snmp_session * Session, struct snmp_pdu * PDU, unsigned char * Data, int Length);

int snmp_send(struct snmp_session * Session, struct snmp_pdu * PDU);

void snmp_read(fd_set *);

int snmp_select_info(int * numfds, fd_set * fdset, struct timeval * timeout, int * block);

void snmp_timeout(void);

void snmp_api_stats(void * outP);

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;

DESCRIPTION
snmp_open() opens the specified session.

snmp_close() closes the specified session.

snmp_build() Encodes PDU into the area pointed to by Packet based on the specified Session. OutLen is the number of bytes in the area pointed to by Packet. When finished, OutLen contains the amount of space left in Packet once the encoding is finished.

snmp_parse() Parses the Data of length Length received by the specified Session.

snmp_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_read() will read all pending SNMP data from the specified fdset. Once the packet is read, a PDU will be created, and if this response was being waited for, the callback will be called.

snmp_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_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_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_select_info(). On return, if block is true, the value of timeout will be undefined.

snmp_timeout() should be called whenever the timeout from snmp_select_info() expires. It may also be polled (probably a cpu expensive proposition). snmp_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_api_stats() prints some API statistics to the FILE * pointed to by outP.

RETURN VALUES
snmp_open() returns the open session, or NULL.

snmp_close() returns 1 upon success, 0 otherwise.

snmp_build() returns -1 upon error, 0 otherwise.

snmp_parse() returns the community string contained in the PDU upon success, NULL otherwise.

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

snmp_select_info() returns the number of open sockets.

WARNINGS
The Community String returned by snmp_parse() must be free()'d.

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)