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