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