/contrib/bsnmp/lib/snmpclient.h

  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() */
 56typedef void (*snmp_send_cb_f)(struct snmp_pdu *, struct snmp_pdu *, void *);
 57
 58/* type of callback function for timeouts */
 59typedef void (*snmp_timeout_cb_f)(void * );
 60
 61/* timeout start function */
 62typedef void *(*snmp_timeout_start_f)(struct timeval *timeout,  
 63    snmp_timeout_cb_f callback, void *);
 64
 65/* timeout stop function */
 66typedef void (*snmp_timeout_stop_f)(void *timeout_id);
 67
 68/*
 69 * Client context.
 70 */
 71struct 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	/* SNMPv3 specific fields */
 83	int32_t			identifier;
 84	int32_t			security_model;
 85	struct snmp_engine	engine;
 86	struct snmp_user	user;
 87
 88	/* SNMPv3 Access control - VACM*/
 89	uint32_t		clen;
 90	uint8_t			cengine[SNMP_ENGINE_ID_SIZ];
 91	char			cname[SNMP_CONTEXT_NAME_SIZ];
 92
 93	struct timeval		timeout;
 94	u_int			retries;
 95
 96	int			dump_pdus;
 97
 98	size_t			txbuflen;
 99	size_t			rxbuflen;
100
101	int			fd;
102
103	int32_t			next_reqid;
104	int32_t			max_reqid;
105	int32_t			min_reqid;
106
107	char			error[SNMP_STRERROR_LEN];
108
109	snmp_timeout_start_f	timeout_start;
110	snmp_timeout_stop_f	timeout_stop;
111
112	char			local_path[sizeof(SNMP_LOCAL_PATH)];
113};
114
115/* the global context */
116extern struct snmp_client snmp_client;
117
118/* initizialies a snmp_client structure */
119void snmp_client_init(struct snmp_client *);
120
121/* initialize fields */
122int snmp_client_set_host(struct snmp_client *, const char *);
123int snmp_client_set_port(struct snmp_client *, const char *);
124
125/* open connection to snmp server (hostname or portname can be NULL) */
126int snmp_open(const char *_hostname, const char *_portname,
127    const char *_read_community, const char *_write_community);
128
129/* close connection */
130void snmp_close(void);
131
132/* initialize a snmp_pdu structure */
133void snmp_pdu_create(struct snmp_pdu *, u_int _op);
134
135/* add pairs of (struct asn_oid *, enum snmp_syntax) to an existing pdu */
136int snmp_add_binding(struct snmp_pdu *, ...);
137
138/* check wheater the answer is valid or not */
139int snmp_pdu_check(const struct snmp_pdu *_req, const struct snmp_pdu *_resp);
140
141int32_t snmp_pdu_send(struct snmp_pdu *_pdu, snmp_send_cb_f _func, void *_arg);
142
143/*  append an index to an oid */
144int snmp_oid_append(struct asn_oid *_oid, const char *_fmt, ...);
145
146/* receive a packet */
147int snmp_receive(int _blocking);
148
149/*
150 * This structure is used to describe an SNMP table that is to be fetched.
151 * The C-structure that is produced by the fetch function must start with
152 * a TAILQ_ENTRY and an u_int64_t.
153 */
154struct snmp_table {
155	/* base OID of the table */
156	struct asn_oid		table;
157	/* type OID of the LastChange variable for the table if any */
158	struct asn_oid		last_change;
159	/* maximum number of iterations if table has changed */
160	u_int			max_iter;
161	/* size of the C-structure */
162	size_t			entry_size;
163	/* number of index fields */
164	u_int			index_size;
165	/* bit mask of required fields */
166	uint64_t		req_mask;
167
168	/* indexes and columns to fetch. Ended by a NULL syntax entry */
169	struct snmp_table_entry {
170	    /* the column sub-oid, ignored for index fields */
171	    asn_subid_t		subid;
172	    /* the syntax of the column or index */
173	    enum snmp_syntax	syntax;
174	    /* offset of the field into the C-structure. For octet strings
175	     * this points to an u_char * followed by a size_t */
176	    off_t		offset;
177#if defined(__GNUC__) && __GNUC__ < 3
178	}			entries[0];
179#else
180	}			entries[];
181#endif
182};
183
184/* callback type for table fetch */
185typedef void (*snmp_table_cb_f)(void *_list, void *_arg, int _res);
186
187/* fetch a table. The argument points to a TAILQ_HEAD */
188int snmp_table_fetch(const struct snmp_table *descr, void *);
189int snmp_table_fetch_async(const struct snmp_table *, void *,
190    snmp_table_cb_f, void *);
191
192/* send a request and wait for the response */
193int snmp_dialog(struct snmp_pdu *_req, struct snmp_pdu *_resp);
194
195/* discover an authorative snmpEngineId */
196int snmp_discover_engine(char *);
197
198/* parse a server specification */
199int snmp_parse_server(struct snmp_client *, const char *);
200
201#endif /* _BSNMP_SNMPCLIENT_H */