xref: /freebsd/contrib/bsnmp/lib/snmpclient.h (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1 /*
2  * Copyright (c) 2001-2003
3  *	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4  *	All rights reserved.
5  *
6  * Author: Harti Brandt <harti@freebsd.org>
7  *	   Kendy Kutzner
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  * 1. Redistributions of source code must retain the above copyright
13  *    notice, this list of conditions and the following disclaimer.
14  * 2. Redistributions in binary form must reproduce the above copyright
15  *    notice, this list of conditions and the following disclaimer in the
16  *    documentation and/or other materials provided with the distribution.
17  *
18  * THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
29  *
30  * $Begemot: bsnmp/lib/snmpclient.h,v 1.19 2005/05/23 11:10:14 brandt_h Exp $
31  */
32 #ifndef _BSNMP_SNMPCLIENT_H
33 #define _BSNMP_SNMPCLIENT_H
34 
35 #include <sys/types.h>
36 #include <sys/socket.h>
37 #include <sys/time.h>
38 #include <netinet/in.h>
39 #include <stddef.h>
40 
41 
42 #define SNMP_STRERROR_LEN 200
43 
44 #define SNMP_LOCAL_PATH	"/tmp/snmpXXXXXXXXXXXXXX"
45 
46 /*
47  * transport methods
48  */
49 #define	SNMP_TRANS_UDP		0
50 #define	SNMP_TRANS_LOC_DGRAM	1
51 #define	SNMP_TRANS_LOC_STREAM	2
52 
53 /* type of callback function for responses
54  * this callback function is responsible for free() any memory associated with
55  * any of the PDUs. Therefor it may call snmp_pdu_free() */
56 typedef void (*snmp_send_cb_f)(struct snmp_pdu *, struct snmp_pdu *, void *);
57 
58 /* type of callback function for timeouts */
59 typedef void (*snmp_timeout_cb_f)(void * );
60 
61 /* timeout start function */
62 typedef void *(*snmp_timeout_start_f)(struct timeval *timeout,
63     snmp_timeout_cb_f callback, void *);
64 
65 /* timeout stop function */
66 typedef void (*snmp_timeout_stop_f)(void *timeout_id);
67 
68 /*
69  * Client context.
70  */
71 struct snmp_client {
72 	enum snmp_version version;
73 	int		trans;	/* which transport to use */
74 
75 	/* these two are read-only for the application */
76 	char		*cport;	/* port number as string */
77 	char		*chost;	/* host name or IP address as string */
78 
79 	char		read_community[SNMP_COMMUNITY_MAXLEN + 1];
80 	char		write_community[SNMP_COMMUNITY_MAXLEN + 1];
81 
82 	struct timeval	timeout;
83 	u_int		retries;
84 
85 	int		dump_pdus;
86 
87 	size_t		txbuflen;
88 	size_t		rxbuflen;
89 
90 	int		fd;
91 
92 	int32_t		next_reqid;
93 	int32_t		max_reqid;
94 	int32_t		min_reqid;
95 
96 	char		error[SNMP_STRERROR_LEN];
97 
98 	snmp_timeout_start_f timeout_start;
99 	snmp_timeout_stop_f timeout_stop;
100 
101 	char		local_path[sizeof(SNMP_LOCAL_PATH)];
102 };
103 
104 /* the global context */
105 extern struct snmp_client snmp_client;
106 
107 /* initizialies a snmp_client structure */
108 void snmp_client_init(struct snmp_client *);
109 
110 /* initialize fields */
111 int snmp_client_set_host(struct snmp_client *, const char *);
112 int snmp_client_set_port(struct snmp_client *, const char *);
113 
114 /* open connection to snmp server (hostname or portname can be NULL) */
115 int snmp_open(const char *_hostname, const char *_portname,
116     const char *_read_community, const char *_write_community);
117 
118 /* close connection */
119 void snmp_close(void);
120 
121 /* initialize a snmp_pdu structure */
122 void snmp_pdu_create(struct snmp_pdu *, u_int _op);
123 
124 /* add pairs of (struct asn_oid *, enum snmp_syntax) to an existing pdu */
125 int snmp_add_binding(struct snmp_pdu *, ...);
126 
127 /* check wheater the answer is valid or not */
128 int snmp_pdu_check(const struct snmp_pdu *_req, const struct snmp_pdu *_resp);
129 
130 int32_t snmp_pdu_send(struct snmp_pdu *_pdu, snmp_send_cb_f _func, void *_arg);
131 
132 /*  append an index to an oid */
133 int snmp_oid_append(struct asn_oid *_oid, const char *_fmt, ...);
134 
135 /* receive a packet */
136 int snmp_receive(int _blocking);
137 
138 /*
139  * This structure is used to describe an SNMP table that is to be fetched.
140  * The C-structure that is produced by the fetch function must start with
141  * a TAILQ_ENTRY and an u_int64_t.
142  */
143 struct snmp_table {
144 	/* base OID of the table */
145 	struct asn_oid		table;
146 	/* type OID of the LastChange variable for the table if any */
147 	struct asn_oid		last_change;
148 	/* maximum number of iterations if table has changed */
149 	u_int			max_iter;
150 	/* size of the C-structure */
151 	size_t			entry_size;
152 	/* number of index fields */
153 	u_int			index_size;
154 	/* bit mask of required fields */
155 	uint64_t		req_mask;
156 
157 	/* indexes and columns to fetch. Ended by a NULL syntax entry */
158 	struct snmp_table_entry {
159 	    /* the column sub-oid, ignored for index fields */
160 	    asn_subid_t		subid;
161 	    /* the syntax of the column or index */
162 	    enum snmp_syntax	syntax;
163 	    /* offset of the field into the C-structure. For octet strings
164 	     * this points to an u_char * followed by a size_t */
165 	    off_t		offset;
166 #if defined(__GNUC__) && __GNUC__ < 3
167 	}			entries[0];
168 #else
169 	}			entries[];
170 #endif
171 };
172 
173 /* callback type for table fetch */
174 typedef void (*snmp_table_cb_f)(void *_list, void *_arg, int _res);
175 
176 /* fetch a table. The argument points to a TAILQ_HEAD */
177 int snmp_table_fetch(const struct snmp_table *descr, void *);
178 int snmp_table_fetch_async(const struct snmp_table *, void *,
179     snmp_table_cb_f, void *);
180 
181 /* send a request and wait for the response */
182 int snmp_dialog(struct snmp_pdu *_req, struct snmp_pdu *_resp);
183 
184 /* parse a server specification */
185 int snmp_parse_server(struct snmp_client *, const char *);
186 
187 #endif /* _BSNMP_SNMPCLIENT_H */
188