SNMPSESAPI(3) Net-SNMP SNMPSESAPI(3)
NAME
snmpsessinit, snmpsessopen, snmpsesssession, snmpsesssend,
snmpsessasyncsend, snmpsessselectinfo, snmpsessread,
snmpsesstimeout, snmpsessclose, snmpsesserror - session functions
SYNOPSIS
##include <>
void snmpsessinit(struct snmpsession **session);;
void **snmpsessopen(struct snmpsession **session);;
struct snmpsession **snmpsesssession(void **handle);;
int snmpsesssend(void **handle,, struct snmppdu **pdu);;
int snmpsessasyncsend(void **handle,,
struct snmppdu **pdu,,
snmpcallback callback,,
void **callbackData);;
int snmpsessselectinfo(void **handle,,
int **numfds,, fdset **fdset,,
struct timeval **timeout,,
int **block);;
void snmpsessread(void **handle,, fdset **fdset);;
void snmpsesstimeout(void **handle);;
int snmpsessclose(void **handle);;
void snmpsesserror(void **handle,, int **pcliberr,,
int **psnmperr,, char ****pperrstring);;
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
snmpsesssession(), these functions are single session versions of the
traditional SNMP library API.
Note that these functions use an opaque pointer (handle in the above
prototypes) to identify a single session in lieu of a session pointer
(as in the traditional API).
snmpsessinit() prepares a struct snmpsession that sources transport
characteristics and common information that will be used for a set of
SNMP transactions. After this structure is passed to snmpsessopen()
to create an SNMP session, the structure is no longer used. Instead
the opaque pointer returned by snmpsessopen() is used to refer to
that session henceforth.
SNMP sessions that are created with snmpsessopen() are not affected
by, and SHOULD NOT BE USED WITH, snmpselectinfo(), snmpread(),
snmptimeout() nor snmpclose(). Rather the equivalent single session
functions described here should be used.
snmpsessinit() and snmpsessopen() each take as input a pointer to a
struct snmpsession object. This structure contains information for a
set of transactions that will share similar transport characteristics.
snmpsesssession() takes the opaque session handle and returns a
pointer to its associated struct snmpsession.
snmpsesssend() and snmpsessasyncsend() each take a pdu parameter,
which points to a struct snmppdu object containing information that
describes a transaction that will be performed over an open session.
Consult snmpapi.h for the definitions of these structures.
snmpsessselectinfo(), snmpsessread() and snmpsesstimeout() pro-
vide an interface for the use of the select(2) system call so that SNMP
transactions for a single session can occur asynchronously.
snmpsessselectinfo() is passed the information that would have been
passed to select(2) in the absence of SNMP. For example, this might
include file descriptors associated with the main loop of a graphical
application. This information is modified so that SNMP will get the
service it requires from the call to select(2). In this case, numfds,
fdset and timeout correspond to the nfds, readfds and timeout arguments
to select(2) respectively. The only exception is that timeout must
ALWAYS point to an allocated (but perhaps uninitialized) struct timeval
(it cannot be NUL as for select(2)). If timeout would have been
passed as NUL, block is instead set to true, and timeout is treated as
undefined. This same rule applies upon return from snmpselectinfo().
After calling snmpsessselectinfo() ,, select(2) should be called with
the returned data. When it returns, snmpsessread() should then be
called with the fdset returned from select(2). This will read any
input from this session's SNMP socket. If select(2) times out (that
is, it returns zero), snmpsesstimeout() should be called to see if a
timeout has occurred on the SNMP session.
DIAGNOSTICS
Error return status from snmpsessopen() is indicated by return of a
NUL pointer. Error return status from snmpsessclose() and
snmpsesssend() is indicated by a return value of 0. A successful
status will return 1.
Further information can be obtained by using snmpsesserror() to see
what type of error has occurred. This function returns the SNMP
snmperrno variable, the value of the system errno variable, and a
string interpretation of both variables. The string must be freed
after use by the caller.
For errors returned by snmpsessopen(), use the corresponding function
snmperror() instead of snmpsesserror().
Consult snmpapi.h for the complete set of SNMP library error values.
The SNMP library error value snmperr can be one of the following val-
ues:
SNMPERGENER A generic error occurred.
SNMPERBADLOCPORT The local port was bad because it had
already been allocated or permission was
denied.
SNMPERBADADRES The host name or address given was not use-
able.
SNMPERBADSESION The specified session was not open.
SNMPERTOLONG
SNMPERNOSOCKET
SNMPERV2INV1
SNMPERV1INV2
SNMPERBADREPEATERS
SNMPERBADREPETITIONS
SNMPERBADASN1BUILD
SNMPERBADSENDTO
SNMPERBADRCVFROM
SNMPERBADPARSE
SNMPERBADVERSION
SNMPERBADCOMUNITY
SNMPERNOAUTHDESPRIV
SNMPERABORT
SNMPERUNKNOWNPDU
SNMPERTIMEOUT
SEE ALSO
select(2), snmpapi(3), snmpapi.h
4.2 Berkeley Distribution 07 Mar 2002 SNMPSESAPI(3)
|
