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