libdhcp.h

Go to the documentation of this file.
00001 /** @file libdhcp.h
00002  *
00003  *  API for libdhcp, a minimal interface to the ISC dhcp IPv4 client,
00004  *  and to the dhcpv6 DHCPv6 client libraries, libdhcp4client, and 
00005  *  libdhcp6client .
00006  *  
00007  *  @author
00008  *  Jason Vas Dias <jvdias@redhat.com>
00009  * 
00010  * @addtogroup LIBDHCP
00011  * @{
00012  */  
00013 /*
00014  *  Copyright(C) Jason Vas Dias <jvdias@redhat.com> Red Hat Inc. May 2006
00015  *
00016  *  This program is free software; you can redistribute it and/or modify
00017  *  it under the terms of the GNU General Public License as published by
00018  *  the Free Software Foundation at 
00019  *           http://www.fsf.org/licensing/licenses/gpl.txt
00020  *  and included in this software distribution as the "LICENSE" file.
00021  *
00022  *  This program is distributed in the hope that it will be useful,
00023  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00024  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00025  *  GNU General Public License for more details.
00026  */
00027 #ifndef LIBDHCP_H
00028 #define LIBDHCP_H
00029 
00030 #include <sys/types.h>
00031 #include <sys/syslog.h>
00032 #include <stdint.h>
00033 #include <stdarg.h>
00034 
00035 /**
00036  * this must be defined during the DHCP client compile to
00037  * select libdhcp specific modicifications:
00038  */
00039 #define LIBDHCP 1
00040 
00041 enum dhcp_state_e;
00042 struct libdhcp_control_s;
00043 
00044 typedef 
00045 int ( *LIBDHCP_Callback ) ( struct libdhcp_control_s *control, enum dhcp_state_e state, void* arg );/**<
00046 * The DHCP client callback type.
00047 * The DHCP clients will call the users' callback on important state change events,
00048 * which is of this function type, and is passed in through the client control structure.
00049 * @arg control:    the DHCP client control handle.
00050 * @arg state:      the client DHCP_State.
00051 * @arg arg:        user pointer from the control structure. 
00052 */
00053 
00054 #define LOG_FATAL 8
00055 typedef
00056 int ( *LIBDHCP_Error_Handler )
00057     ( struct libdhcp_control_s *ctl,
00058       int priority,
00059       const char *fmt,
00060       va_list ap
00061     ); /**<
00062  * The libdhcp error handler / logger callback type.
00063  * The DHCP clients, and parts of libdhcp, that need to report / log an error condition will
00064  * call a function of this type, passed in through the control structure.
00065  * No DHCP client or libdhcp code will do any logging unless a non-zero pointer to a function
00066  * of this type is recorded in the ctl->eh member.
00067  * @arg ctl:        the DHCP client control handle.
00068  * @arg priority:   the log level / priority of the log message, ala syslog(3) priority.
00069  * The priority corresponds to the syslog priorities LOG_ERR, LOG_INFO, and LOG_DEBUG.
00070  * A special LOG_FATAL priority (8), not used by syslog, is used to indicate a condition
00071  * that would cause the client to exit when not run under libdhcp. LOG_FATAL messages 
00072  * are always logged, and the handler sets ctl->finished = 1 on receipt of a LOG_FATAL
00073  * message - @see LIBDHCP_Control::finished.
00074  */
00075 
00076 /** LIBDHCP_Control
00077  * 
00078  *  The libdhcp DHCP client control structure.
00079  *  Each client is called with a pointer to this structure as the first argument
00080  *  to its main dhcp*_client function.
00081  *  This structure specifies what the client is allowed to do and how it will
00082  *  communicate state changes to the calling code.
00083  */
00084 typedef 
00085 struct libdhcp_control_s
00086 {
00087 /*{ this structure MUST be the same as in libdhcp_control.h for DHCP clients */
00088     LIBDHCP_Callback    callback;       /**< the DHCP clients' main loop calls this on state changes */
00089     uint16_t            capability;     /**< LIBDHCP_Capability bits to enable                       */
00090     uint8_t             finished;       /**< set to one to make clients exit their main loop         */
00091     uint8_t             decline;        /**< set to one to decline the lease (DHCPv4 only)           */
00092     time_t              timeout;        /**< (timeout+now) == time after which clients MUST return   */
00093     time_t              now;            /**< clients set this to time(0) on entering main loop       */
00094     void               *arg;            /**< user data pointer                                       */
00095     LIBDHCP_Error_Handler eh;           /**< The logger / error hander callback                      */
00096 /*} end of fields known to DHCP clients */
00097     uint8_t             log_level;      /**< maximum log level (LOG_FATAL excluded)                  */  
00098 } LIBDHCP_Control;
00099 
00100 /** 
00101  * LIBDHCP_Capability 
00102  *
00103  * enum that defines the capabilities DHCP clients are allowed to exercise.
00104  *
00105  * The DHCP_CONFIGURE* capabilities are supported by DHCPv6 in process, 
00106  * while the DHCPv4 client would fork and exec the dhclient-script to implement them if these
00107  * bits are set - otherwise, if no bits are set, the callback is called and the script is 
00108  * not run. 
00109  * @warning If using the dhcp4_nic DHCPv4 network interface configurator, DO NOT set any of
00110  * the DHCP_CONFIGURE_* bits to one.
00111  */
00112 typedef enum libdhcp_capability_e
00113 {
00114     DHCP_USE_LEASE_DATABASE   = 1,      /* use / do not use persistent lease database files   */
00115     DHCP_USE_PID_FILE         = 2,      /**< use / do not use pid file                        */
00116     DHCP_CONFIGURE_INTERFACES = 4,      /**< configure interfaces UP/DOWN as required         */
00117     DHCP_CONFIGURE_ADDRESSES  = 8,      /**< configure interface addresses as required        */
00118     DHCP_CONFIGURE_ROUTES     =16,      /**< configure routes as required                     */
00119     DHCP_CONFIGURE_RESOLVER   =32,      /**< configure resolv.conf as required                */
00120     DHCP_CONFIGURE_RADVD      =64,      /**< (DHCPv6 only) configure radvd.conf & restart radvd as required */
00121 } LIBDHCP_Capability;
00122 
00123 /**
00124  * @var  LIBDHCP_Capability::DHCP_USE_LEASE_DATABASE
00125  * @brief use / do not use persistent lease database files.
00126  * If this bit is set to one, clients will maintain a persistent lease database,
00127  * as they would under normal DHCP client operation.
00128  * When restarted, they will first check for existing unexpired leases in the lease database
00129  * and will request the latest unexpired lease from the server; if no server can be contacted,
00130  * they will enter the REBIND state with the latest unexpired lease.
00131  * The IPv4 client (DHCPv4) will maintain its lease database in /var/lib/dhclient ; 
00132  * the IPv6 client (DHCPv6) will maintain its lease database in /var/lib/dhcpv6 .
00133  * @warning 
00134  * Use of DHCP_USE_LEASE_DATABASE with DHCPv6 when invoking dhcpv6_client multiple
00135  * times in the same process will lead to memory leaks in the flex scanner used for parsing
00136  * the DHCPv6 lease database .
00137  * This problem is being worked on, but is expected most users of the dhcp6client library
00138  * will be invoking the client only once / not using DHCP_USE_LEASE_DATABASE .
00139  * DHCPv4 has no memory leaks.
00140  */
00141 
00142 /**
00143  * libdhcp_control_new - creates a new DHCP client control LIBDHCP_Control structure.
00144  * The arguments correspond to the named LIBDHCP_Control structure members .
00145  * @see LIBDHCP_control 
00146  */
00147 extern LIBDHCP_Control*
00148 libdhcp_control_new
00149 (   LIBDHCP_Callback       callback,      /**< the user's function to be called on state changes*/
00150     LIBDHCP_Capability     dhc_cap,       /**< DHCP client capabilities to enable - @see LIBDHCP_Capability*/
00151     time_t                 timeout,       /**< time period in seconds after which client must return */
00152     void                  *arg,           /**< argument to pass to user's callback as third arg */
00153     LIBDHCP_Error_Handler  error_handler, /**< the logger this client is to use */
00154     uint8_t                log_level      /**< the maximum log level to be logged by this client */
00155 );  
00156 
00157 extern void libdhcp_control_free(LIBDHCP_Control *);
00158 
00159 /**
00160  * The function prototype of the DHCP client main() function or primary entry point, 
00161  * (renamed dhcpv4_client for the DHCPv4 client, and dhcpv6_client for the DHCPv6 client).
00162  * Users must include the appropriate dhcpv{4,6}client.h header to obtain the declarations
00163  * of these clients' entry points.
00164  */
00165 typedef int (*DHCP_Client) ( LIBDHCP_Control*, int argc, char **argv, char **envp );
00166 
00167 extern int
00168 libdhcp_call_client( LIBDHCP_Control *,  DHCP_Client, ...); /**<
00169  * calls the dhcpv{4,6}_client function with the arguments in the variable argument list.
00170  * @arg ctl : the client control structure - @see LIBDHCP_Control
00171  * @arg client: the dhcp client to run - @see DHCP_Client
00172  * @arg ... : The argv[] argument list to pass to the client.
00173  * The last argument in the argument list MUST be 0 .
00174  * The dhcpv4 client has many useful arguments to pass, 
00175  * eg. the \b -H \b <host-name> , \b -V \b <vendor-class-identifier>,
00176  * and \b -I \b <dhcp-client-identifier> arguments - see man dhclient(8).  
00177  */
00178 
00179 /**
00180  * The DHCP_state enum represents the states of the DHCP clients,
00181  * that each client will call the user's call back for on a state change.
00182  */
00183 typedef enum dhcp_state_e
00184 {
00185 
00186     /* DHCPv4 client states - third callback arg will be a 'struct client_state *'    */
00187     DHC4_NBI,                   /**< failed: no broadcast interfaces found              */
00188     DHC4_PREINIT,               /**< configuration started - bring the interface "UP"   */
00189     DHC4_BOUND,                 /**< lease obtained                                     */
00190     DHC4_RENEW,                 /**< lease renewed                                      */
00191     DHC4_REBOOT,                /**< have valid lease, but now obtained a different one */
00192     DHC4_REBIND,                /**< new, different lease                               */
00193     DHC4_STOP,                  /**< remove old lease                                   */
00194     DHC4_MEDIUM,                /**< media selection begun                              */
00195     DHC4_TIMEOUT,               /**< timed out contacting DHCP server                   */
00196     DHC4_FAIL,                  /**< all attempts to contact server timed out, sleeping */
00197     DHC4_EXPIRE,                /**< lease has expired, renewing                        */
00198     DHC4_RELEASE,               /**< releasing lease                                    */
00199     /* This state raised by both clients: */
00200     DHC_TIMEDOUT,               /**< libdhcp_control timeout has been exceeded          */
00201     /* DHCPv6 client states:    */
00202     DHC6_BOUND,                 /**< new lease obtained             - arg is optinfo *  */
00203     DHC6_REBIND,                /**< existing expired lease rebound - arg is optinfo *  */
00204     DHC6_RELEASE                /**< existing lease expired         - arg is dhcp6_iaidaddr*/
00205 } DHCP_State;
00206 
00207 /**
00208  * function to convert a ::DHCP_State to a string.
00209  * @arg buf : if non-zero, will be used to store the string
00210  * @warning If buf is 0, the string returned is to a static buffer,
00211  * and the call cannot be used more than once in an argument list.
00212  */
00213 char *libdhcp_state_string( DHCP_State, char *buf );
00214 
00215 /**
00216  * default error handler that logs to stderr.
00217  * @see LIBDHCP_Error_Handler
00218  */
00219 extern 
00220 int libdhcp_stderr_logger
00221 (   struct libdhcp_control_s *ctl,
00222     int priority,
00223     const char *fmt,
00224     va_list ap
00225 );
00226 
00227 /**
00228  * default error handler that logs to syslog.
00229  * @see LIBDHCP_Error_Handler
00230  */
00231 extern 
00232 int libdhcp_syslogger
00233 (   struct libdhcp_control_s *ctl,
00234     int priority,
00235     const char *fmt,
00236     va_list ap
00237 );
00238 
00239 /** @} */
00240 
00241 #endif
00242 

Generated on Thu Aug 10 22:16:40 2006 for libdhcp by  doxygen 1.4.7