1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright (c) 1998 by Sun Microsystems, Inc. 24 * All rights reserved. 25 */ 26 27 #pragma ident "%Z%%M% %I% %E% SMI" 28 29 #ifndef _SNMP_API_H_ 30 #define _SNMP_API_H_ 31 32 #include <sys/types.h> 33 #include "impl.h" 34 #include "snmp.h" 35 #include "pdu.h" 36 37 38 /***** NEW CONSTANTS *****/ 39 40 /* 41 * Set fields in session to the following to 42 * get a default or unconfigured value. 43 */ 44 45 #define SNMP_DEFAULT_COMMUNITY NULL 46 #define SNMP_DEFAULT_RETRIES -1 47 #define SNMP_DEFAULT_TIMEOUT -1 48 #define SNMP_DEFAULT_REMPORT 0 49 #define SNMP_DEFAULT_LOCPORT 0 50 51 52 /* 53 * Error return values 54 */ 55 56 #define SNMPERR_GENERR -1 57 #define SNMPERR_BAD_LOCPORT -2 /* local port was already in use */ 58 #define SNMPERR_BAD_ADDRESS -3 59 #define SNMPERR_BAD_SESSION -4 60 #define SNMPERR_SYSERR -5 61 62 63 /* 64 * Operation values (see callback()) 65 */ 66 67 #define RECEIVED_MESSAGE 1 68 #define TIMED_OUT 2 69 70 71 /***** NEW TYPES *****/ 72 73 /* 74 * community: community for outgoing requests 75 * retries: Number of retries before timeout 76 * timeout: Number of uS until first timeout, then exponential backoff 77 * peername: Domain name or dotted IP address of default peer 78 * remote_port: UDP port number of peer 79 * local_port: My UDP port number, 0 for default, picked randomly 80 * callback: Function to interpret incoming data 81 * callback_magic: Pointer to data that the callback function may consider important 82 * sd: socket descriptor associated with that session 83 */ 84 85 typedef struct SNMP_session { 86 char *community; 87 int retries; 88 int32_t timeout; 89 char *peername; 90 u_short remote_port; 91 u_short local_port; 92 void (*callback)(); 93 void *callback_magic; 94 int sd; 95 } SNMP_session; 96 97 98 /***** GLOBAL VARIABLES *****/ 99 100 extern int snmp_errno; 101 102 103 /***** GLOBAL FUNCTIONS *****/ 104 105 /* 106 * snmp_session_open() 107 * 108 * Sets up the session with the information provided 109 * by the user. Then opens and binds the necessary UDP port. 110 * A handle to the created session is returned. 111 * On any error, NULL is returned 112 * and snmp_errno is set to the appropriate error code. 113 */ 114 115 SNMP_session *snmp_session_open(char *peername, char *community, int retries, int32_t timeout, void callback(), void *callback_magic, char *error_label); 116 117 SNMP_session *snmp_session_open_default(char *peername, void callback(), void *callback_magic, char *error_label); 118 119 120 /* 121 * snmp_session_close() 122 * 123 * Close the input session. Frees all data allocated for the session, 124 * dequeues any pending requests, and closes any sockets allocated for 125 * the session. Returns 0 on sucess, -1 otherwise. 126 */ 127 128 int snmp_session_close(SNMP_session *session, char *error_label); 129 130 131 /* 132 * snmp_session_send() 133 * 134 * Sends the input pdu on the session. 135 * Add a request corresponding to this pdu to the list 136 * of outstanding requests on this session, then send the pdu. 137 * Returns 0 upon sucess. 138 * On any error, -1 is returned. 139 * 140 * The pdu is freed by snmp_send() unless a failure occured. 141 */ 142 143 int snmp_session_send(SNMP_session *session, int predefined_id, SNMP_pdu *pdu, char *error_label); 144 145 146 /* 147 * snmp_session_read() 148 * 149 * Checks to see if any of the fd's set in the fdset belong to 150 * snmp. Each socket with it's fd set has a packet read from it 151 * The resulting pdu is passed to the callback routine for that session. 152 */ 153 154 void snmp_session_read(fd_set *fdset); 155 156 void snmp_session_read_2(int fd); 157 158 159 /* 160 * snmp_session_select_info() 161 * 162 * Returns info about what snmp requires from a select statement. 163 * numfds is the number of fds in the list that are significant. 164 * All file descriptors opened for SNMP are OR'd into the fdset. 165 * If activity occurs on any of these file descriptors, snmp_read 166 * should be called with that file descriptor set. 167 * 168 * The timeout is the latest time that SNMP can wait for a timeout. The 169 * select should be done with the minimum time between timeout and any other 170 * timeouts necessary. This should be checked upon each invocation of select. 171 * If a timeout is received, snmp_timeout should be called to check if the 172 * timeout was for SNMP. (snmp_timeout is idempotent) 173 * 174 * snmp_session_select_info returns the number of current requests. 175 */ 176 177 int snmp_session_select_info(int *numfds, fd_set *fdset, struct timeval *timeout); 178 179 int snmp_session_timeout_info(struct itimerval *itimeout); 180 181 182 /* 183 * snmp_session_timeout() 184 * 185 * snmp_timeout should be called whenever the timeout from snmp_select_info expires, 186 * but it is idempotent, so snmp_timeout can be polled (probably a cpu expensive 187 * proposition). snmp_timeout checks to see if any of the sessions have an 188 * outstanding request that has timed out. If it finds one (or more), and that 189 * pdu has more retries available, a new packet is formed from the pdu and is 190 * resent. If there are no more retries available, the callback for the session 191 * is used to alert the user of the timeout. 192 */ 193 194 void snmp_session_timeout(); 195 196 197 /* 198 * This routine must be supplied by the application: 199 * 200 * void callback( 201 * int operation, 202 * SNMP_session *session, The session authenticated under. 203 * int request_id, The request id of this pdu (0 for TRAP) 204 * int predefined_id, 205 * SNMP_pdu *pdu, The pdu information. 206 * void *magic); A link to the data for this routine. 207 * 208 * Any data in the pdu must be copied because it will be freed elsewhere. 209 * Operations are defined above. 210 */ 211 212 #endif 213 214