net-snmp 5.7
fd_event_manager.h
00001 /**************************************************************************
00002  * UNIT: File Descriptor (FD) Event Manager
00003  *
00004  * OVERVIEW: This unit contains functions to register a FD with the FD
00005  *           event manager for callbacks when activity is received on that
00006  *           FD.  Notification of read, write, and exception activity can 
00007  *           all be registered for individually.  Once a registered FD is
00008  *           closed by the user, the FD must be unregistered.  To use
00009  *           the FD Event manager you need to make calls to 
00010  *           netsnmp_external_event_info() and 
00011  *           netsnmp_dispatch_external_events() in your event loop to receive
00012  *           callbacks for registered events.  See snmpd.c and snmptrapd.c 
00013  *           for examples.
00014  *
00015  * LIMITATIONS:
00016  **************************************************************************/
00017 #ifndef FD_EVENT_MANAGER_H
00018 #define FD_EVENT_MANAGER_H
00019 
00020 #ifdef HAVE_SYS_SELECT_H
00021 #include <sys/select.h>
00022 #endif
00023 
00024 #ifdef __cplusplus
00025 extern          "C" {
00026 #endif
00027 
00028 #define NUM_EXTERNAL_FDS 32
00029 #define FD_REGISTERED_OK                 0
00030 #define FD_REGISTRATION_FAILED          -2
00031 #define FD_UNREGISTERED_OK               0
00032 #define FD_NO_SUCH_REGISTRATION         -1
00033 
00034 /* Since the inception of netsnmp_external_event_info and 
00035  * netsnmp_dispatch_external_events, there is no longer a need for the data 
00036  * below to be globally visible.  We will leave it global for now for 
00037  * compatibility purposes. */
00038 extern int      external_readfd[NUM_EXTERNAL_FDS],   external_readfdlen;
00039 extern int      external_writefd[NUM_EXTERNAL_FDS],  external_writefdlen;
00040 extern int      external_exceptfd[NUM_EXTERNAL_FDS], external_exceptfdlen;
00041 
00042 extern void     (*external_readfdfunc[NUM_EXTERNAL_FDS])   (int, void *);
00043 extern void     (*external_writefdfunc[NUM_EXTERNAL_FDS])  (int, void *);
00044 extern void     (*external_exceptfdfunc[NUM_EXTERNAL_FDS]) (int, void *);
00045 
00046 extern void    *external_readfd_data[NUM_EXTERNAL_FDS];
00047 extern void    *external_writefd_data[NUM_EXTERNAL_FDS];
00048 extern void    *external_exceptfd_data[NUM_EXTERNAL_FDS];
00049 
00050 /* Here are the key functions of this unit.  Use register_xfd to register
00051  * a callback to be called when there is x activity on the register fd.  
00052  * x can be read, write, or except (for exception).  When registering,
00053  * you can pass in a pointer to some data that you have allocated that
00054  * you would like to have back when the callback is called. */
00055 int             register_readfd(int, void (*func)(int, void *),   void *);
00056 int             register_writefd(int, void (*func)(int, void *),  void *);
00057 int             register_exceptfd(int, void (*func)(int, void *), void *);
00058 
00059 /* Unregisters a given fd for events */
00060 int             unregister_readfd(int);
00061 int             unregister_writefd(int);
00062 int             unregister_exceptfd(int);
00063 
00064 /*
00065  * External Event Info
00066  *
00067  * Description:
00068  *   Call this function to add an external event fds to your read, write, 
00069  *   exception fds that your application already has.  When this function
00070  *   returns, your fd_sets will be ready for select().  It returns the
00071  *   biggest fd in the fd_sets so far.
00072  *
00073  * Input Parameters: None
00074  *
00075  * Output Parameters: None
00076  *
00077  * In/Out Parameters: 
00078  *   numfds - The biggest fd so far.  On exit to this function, numfds
00079  *            could of changed since we pass out the new biggest fd.
00080  *   readfds - Set of read FDs that we are monitoring.  This function
00081  *             can modify this set to have more FDs that we are monitoring.
00082  *   writefds - Set of write FDs that we are monitoring.  This function
00083  *             can modify this set to have more FDs that we are monitoring.
00084  *   exceptfds - Set of exception FDs that we are monitoring.  This function
00085  *             can modify this set to have more FDs that we are monitoring.
00086  *
00087  * Return Value: None
00088  *
00089  * Side Effects: None
00090  */
00091 NETSNMP_IMPORT
00092 void netsnmp_external_event_info(int *numfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds);
00093 
00094 NETSNMP_IMPORT
00095 void netsnmp_external_event_info2(int *numfds,
00096                                   netsnmp_large_fd_set *readfds,
00097                                   netsnmp_large_fd_set *writefds,
00098                                   netsnmp_large_fd_set *exceptfds);
00099 
00100 /*
00101  * Dispatch External Events
00102  *
00103  * Description:
00104  *   Call this function after select returns with pending events.  If any of
00105  *   them were NETSNMP external events, the registered callback will be called.
00106  *   The corresponding fd_set will have the FD cleared after the event is
00107  *   dispatched.
00108  *
00109  * Input Parameters: None
00110  *
00111  * Output Parameters: None
00112  *
00113  * In/Out Parameters: 
00114  *   count - Number of FDs that have activity.  In this function, we decrement
00115  *           count as we dispatch an event.
00116  *   readfds - Set of read FDs that have activity
00117  *   writefds - Set of write FDs that have activity
00118  *   exceptfds - Set of exception FDs that have activity 
00119  *
00120  * Return Value: None
00121  *
00122  * Side Effects: None
00123  */
00124 NETSNMP_IMPORT
00125 void netsnmp_dispatch_external_events(int *count, fd_set *readfds, fd_set *writefds, fd_set *exceptfds);
00126 NETSNMP_IMPORT
00127 void netsnmp_dispatch_external_events2(int *count,
00128                                        netsnmp_large_fd_set *readfds,
00129                                        netsnmp_large_fd_set *writefds,
00130                                        netsnmp_large_fd_set *exceptfds);
00131 #ifdef __cplusplus
00132 }
00133 #endif
00134 #endif