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

Generated on Fri Oct 13 18:20:33 2006 for libdhcp by  doxygen 1.4.7