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