snmp_sess_synch_response(3)

1NETSNMP_SESS_API(3)                Net-SNMP                NETSNMP_SESS_API(3)
2
3
4

NAME

6       snmp_sess_init,   snmp_sess_open,   snmp_sess_session,  snmp_sess_send,
7       snmp_sess_async_send,      snmp_sess_select_info,       snmp_sess_read,
8       snmp_sess_timeout,      snmp_sess_synch_response,      snmp_sess_close,
9       snmp_sess_error - session functions
10

SYNOPSIS

12       #include <net-snmp/session_api.h>
13
14       void snmp_sess_init(struct snmp_session *session);
15
16       void *snmp_sess_open(struct snmp_session *session);
17
18       struct snmp_session *snmp_sess_session(void *handle);
19
20       int snmp_sess_send(void *handle, struct snmp_pdu *pdu);
21
22       int snmp_sess_async_send(void *handle,
23                                struct snmp_pdu *pdu,
24                                snmp_callback callback,
25                                void *callbackData);
26
27       int snmp_sess_select_info(void *handle,
28                                 int *numfds, fd_set *fdset,
29                                 struct timeval *timeout,
30                                 int *block);
31
32       int snmp_sess_read(void *handle, fd_set *fdset);
33
34       void snmp_sess_timeout(void *handle);
35
36       int snmp_sess_synch_response ( void *handle,
37              netsnmp_pdu *pdu,
38              netsnmp_pdu **response);
39
40       int snmp_sess_close(void *handle);
41
42       void snmp_sess_error(void *handle, int *pcliberr,
43                           int *psnmperr, char **pperrstring);
44

DESCRIPTION

46       These functions define a subset of the API that can be used  to  manage
47       single  SNMP  sessions  in  a  multi-threaded  application.  Except for
48       snmp_sess_session(), these functions are single session versions of the
49       traditional SNMP library API.
50
51       Note  that  these  functions use an opaque pointer (handle in the above
52       prototypes) to identify a single session in lieu of a  session  pointer
53       (as in the traditional API).
54
55       snmp_sess_init()  prepares a struct snmp_session that sources transport
56       characteristics and common information that will be used for a  set  of
57       SNMP  transactions.  After this structure is passed to snmp_sess_open()
58       to create an SNMP session, the structure is no  longer  used.   Instead
59       the  opaque  pointer  returned  by snmp_sess_open() is used to refer to
60       that session henceforth.
61
62       SNMP sessions that are created with snmp_sess_open() are  not  affected
63       by,  and  SHOULD  NOT  BE  USED  WITH, snmp_select_info(), snmp_read(),
64       snmp_timeout() nor snmp_close().  Rather the equivalent single  session
65       functions described here should be used.
66
67       snmp_sess_init() and snmp_sess_open() each take as input a pointer to a
68       struct snmp_session object.  This structure contains information for  a
69       set  of transactions that will share similar transport characteristics.
70       snmp_sess_session() takes the  opaque  session  handle  and  returns  a
71       pointer to its associated struct snmp_session.
72
73       snmp_sess_send()  and snmp_sess_async_send() each take a pdu parameter,
74       which points to a struct snmp_pdu object  containing  information  that
75       describes a transaction that will be performed over an open session.
76
77       Consult snmp_api.h for the definitions of these structures.
78
79       With  the  snmp_sess_async_send()  call, snmp_sess_read will invoke the
80       specified callback when the response is received.
81
82       snmp_sess_select_info(), snmp_sess_read() and snmp_sess_timeout()  pro‐
83       vide an interface for the use of the select(2) system call so that SNMP
84       transactions for a single session can occur asynchronously.
85
86       snmp_sess_select_info() is passed the information that would have  been
87       passed  to  select(2)  in the absence of SNMP.  For example, this might
88       include file descriptors associated with the main loop of  a  graphical
89       application.  This  information  is  modified so that SNMP will get the
90       service it requires from the call to select(2).  In this case,  numfds,
91       fdset and timeout correspond to the nfds, readfds and timeout arguments
92       to select(2) respectively.  The only exception  is  that  timeout  must
93       ALWAYS point to an allocated (but perhaps uninitialized) struct timeval
94       (it cannot be NULL as for  select(2)).   If  timeout  would  have  been
95       passed as NULL, block is instead set to true, and timeout is treated as
96       undefined.  This same rule applies upon return from snmp_select_info().
97
98       After calling snmp_sess_select_info() , select(2) should be called with
99       the  returned  data.   When it returns, snmp_sess_read() should then be
100       called with the fd_set returned from select(2).   This  will  read  any
101       input  from  this  session's SNMP socket.  If select(2) times out (that
102       is, it returns zero), snmp_sess_timeout() should be called to see if  a
103       timeout has occurred on the SNMP session.
104
105       snmp_sess_synch_response  is  a  convenience routine that will send the
106       request, wait for the response and process it  before  returning.   See
107       the descriptions of snmp_sess_send ,  snmp_sess_read etc for details.
108

DIAGNOSTICS

110       Error  return  status from snmp_sess_open() is indicated by return of a
111       NULL  pointer.   Error  return  status   from   snmp_sess_close()   and
112       snmp_sess_send()  is  indicated  by  a return value of 0.  A successful
113       status will return 1.
114
115       Further information can be obtained by using snmp_sess_error()  to  see
116       what  type  of  error  has  occurred.   This  function returns the SNMP
117       snmp_errno variable, the value of the  system  errno  variable,  and  a
118       string  interpretation  of  both  variables.   The string must be freed
119       after use by the caller.
120
121       For errors returned by snmp_sess_open(), use the corresponding function
122       snmp_error() instead of snmp_sess_error().
123
124       Consult  snmp_api.h  for the complete set of SNMP library error values.
125       The SNMP library error value snmperr can be one of the  following  val‐
126       ues:
127
128         SNMPERR_GENERR           A generic error occurred.
129
130         SNMPERR_BAD_LOCPORT      The  local  port  was  bad  because  it  had
131                                  already been  allocated  or  permission  was
132                                  denied.
133
134         SNMPERR_BAD_ADDRESS      The  host name or address given was not use‐
135                                  able.
136
137         SNMPERR_BAD_SESSION      The specified session was not open.
138
139         SNMPERR_TOO_LONG
140
141         SNMPERR_NO_SOCKET
142
143         SNMPERR_V2_IN_V1
144
145         SNMPERR_V1_IN_V2
146
147         SNMPERR_BAD_REPEATERS
148
149         SNMPERR_BAD_REPETITIONS
150
151         SNMPERR_BAD_ASN1_BUILD
152
153         SNMPERR_BAD_SENDTO
154
155         SNMPERR_BAD_RCVFROM
156
157         SNMPERR_BAD_PARSE
158
159         SNMPERR_BAD_VERSION
160
161         SNMPERR_BAD_COMMUNITY
162
163         SNMPERR_NOAUTH_DESPRIV
164
165         SNMPERR_ABORT
166
167         SNMPERR_UNKNOWN_PDU
168
169         SNMPERR_TIMEOUT
170

NAME

SYNOPSIS

DESCRIPTION

DIAGNOSTICS

SEE ALSO