libdhcp library interface


Data Structures

struct  libdhcp_control_s

Defines

#define LIBDHCP   1
#define LOG_FATAL   8

Typedefs

typedef int(*) LIBDHCP_Callback (struct libdhcp_control_s *control, enum dhcp_state_e state, void *arg)
typedef int(*) LIBDHCP_Error_Handler (struct libdhcp_control_s *ctl, int priority, const char *fmt, va_list ap)
typedef libdhcp_control_s LIBDHCP_Control
typedef enum libdhcp_capability_e LIBDHCP_Capability
typedef int(*) DHCP_Client (LIBDHCP_Control *, int argc, char **argv, char **envp)
typedef enum dhcp_state_e DHCP_State

Enumerations

enum  libdhcp_capability_e {
  DHCP_USE_LEASE_DATABASE = 1, DHCP_USE_PID_FILE = 2, DHCP_CONFIGURE_INTERFACES = 4, DHCP_CONFIGURE_ADDRESSES = 8,
  DHCP_CONFIGURE_ROUTES = 16, DHCP_CONFIGURE_RESOLVER = 32, DHCP_CONFIGURE_RADVD = 64
}
enum  dhcp_state_e {
  DHC4_NBI, DHC4_PREINIT, DHC4_BOUND, DHC4_RENEW,
  DHC4_REBOOT, DHC4_REBIND, DHC4_STOP, DHC4_MEDIUM,
  DHC4_TIMEOUT, DHC4_FAIL, DHC4_EXPIRE, DHC4_RELEASE,
  DHC_TIMEDOUT, DHC6_BOUND, DHC6_REBIND, DHC6_RELEASE
}

Functions

LIBDHCP_Controllibdhcp_control_new (LIBDHCP_Callback callback, LIBDHCP_Capability dhc_cap, time_t timeout, void *arg, LIBDHCP_Error_Handler error_handler, uint8_t log_level)
void libdhcp_control_free (LIBDHCP_Control *)
int libdhcp_call_client (LIBDHCP_Control *, DHCP_Client,...)
char * libdhcp_state_string (DHCP_State, char *buf)
int libdhcp_stderr_logger (struct libdhcp_control_s *ctl, int priority, const char *fmt, va_list ap)
int libdhcp_syslogger (struct libdhcp_control_s *ctl, int priority, const char *fmt, va_list ap)

Detailed Description

API for libdhcp, a minimal interface to the ISC dhcp IPv4 client library, libdhcp4client, and to the dhcpv6 DHCPv6 client library, libdhcp6client .

Define Documentation

#define LIBDHCP   1

this must be defined during the DHCP client compile to select libdhcp specific modicifications:

Definition at line 41 of file libdhcp.h.


Typedef Documentation

typedef int(*) DHCP_Client(LIBDHCP_Control *, int argc, char **argv, char **envp)

The function prototype of the DHCP client main() function or primary entry point, (renamed dhcpv4_client for the DHCPv4 client, and dhcpv6_client for the DHCPv6 client). Users must include the appropriate dhcpv{4,6}client.h header to obtain the declarations of these clients' entry points.

Definition at line 167 of file libdhcp.h.

typedef enum dhcp_state_e DHCP_State

The DHCP_state enum represents the states of the DHCP clients, that each client will call the user's call back for on a state change.

typedef int( *) LIBDHCP_Callback(struct libdhcp_control_s *control, enum dhcp_state_e state, void *arg)

The DHCP client callback type. The DHCP clients will call the users' callback on important state change events, which is of this function type, and is passed in through the client control structure.

Definition at line 47 of file libdhcp.h.

typedef enum libdhcp_capability_e LIBDHCP_Capability

LIBDHCP_Capability

enum that defines the capabilities DHCP clients are allowed to exercise.

The DHCP_CONFIGURE* capabilities are supported by DHCPv6 in process, while the DHCPv4 client would fork and exec the dhclient-script to implement them if these bits are set - otherwise, if no bits are set, the callback is called and the script is not run.

Warning:
If using the dhcp4_nic DHCPv4 network interface configurator, DO NOT set any of the DHCP_CONFIGURE_* bits to one.

typedef struct libdhcp_control_s LIBDHCP_Control

LIBDHCP_Control

The libdhcp DHCP client control structure. Each client is called with a pointer to this structure as the first argument to its main dhcp*_client function. This structure specifies what the client is allowed to do and how it will communicate state changes to the calling code.

typedef int( *) LIBDHCP_Error_Handler(struct libdhcp_control_s *ctl, int priority, const char *fmt, va_list ap)

The libdhcp error handler / logger callback type. The DHCP clients, and parts of libdhcp, that need to report / log an error condition will call a function of this type, passed in through the control structure. No DHCP client or libdhcp code will do any logging unless a non-zero pointer to a function of this type is recorded in the ctl->eh member.

Definition at line 59 of file libdhcp.h.


Enumeration Type Documentation

enum dhcp_state_e

The DHCP_state enum represents the states of the DHCP clients, that each client will call the user's call back for on a state change.

Enumerator:
DHC4_NBI  failed: no broadcast interfaces found
DHC4_PREINIT  configuration started - bring the interface "UP"
DHC4_BOUND  lease obtained
DHC4_RENEW  lease renewed
DHC4_REBOOT  have valid lease, but now obtained a different one
DHC4_REBIND  new, different lease
DHC4_STOP  remove old lease
DHC4_MEDIUM  media selection begun
DHC4_TIMEOUT  timed out contacting DHCP server
DHC4_FAIL  all attempts to contact server timed out, sleeping
DHC4_EXPIRE  lease has expired, renewing
DHC4_RELEASE  releasing lease
DHC_TIMEDOUT  libdhcp_control timeout has been exceeded
DHC6_BOUND  new lease obtained - arg is optinfo *
DHC6_REBIND  existing expired lease rebound - arg is optinfo *
DHC6_RELEASE  existing lease expired - arg is dhcp6_iaidaddr

Definition at line 185 of file libdhcp.h.

enum libdhcp_capability_e

LIBDHCP_Capability

enum that defines the capabilities DHCP clients are allowed to exercise.

The DHCP_CONFIGURE* capabilities are supported by DHCPv6 in process, while the DHCPv4 client would fork and exec the dhclient-script to implement them if these bits are set - otherwise, if no bits are set, the callback is called and the script is not run.

Warning:
If using the dhcp4_nic DHCPv4 network interface configurator, DO NOT set any of the DHCP_CONFIGURE_* bits to one.
Enumerator:
DHCP_USE_LEASE_DATABASE  use / do not use persistent lease database files. If this bit is set to one, clients will maintain a persistent lease database, as they would under normal DHCP client operation. When restarted, they will first check for existing unexpired leases in the lease database and will request the latest unexpired lease from the server; if no server can be contacted, they will enter the REBIND state with the latest unexpired lease. The IPv4 client (DHCPv4) will maintain its lease database in /var/lib/dhclient ; the IPv6 client (DHCPv6) will maintain its lease database in /var/lib/dhcpv6 .

Warning:
Use of DHCP_USE_LEASE_DATABASE with DHCPv6 when invoking dhcpv6_client multiple times in the same process will lead to memory leaks in the flex scanner used for parsing the DHCPv6 lease database . This problem is being worked on, but is expected most users of the dhcp6client library will be invoking the client only once / not using DHCP_USE_LEASE_DATABASE . DHCPv4 has no memory leaks.
DHCP_USE_PID_FILE  use / do not use pid file
DHCP_CONFIGURE_INTERFACES  configure interfaces UP/DOWN as required
DHCP_CONFIGURE_ADDRESSES  configure interface addresses as required
DHCP_CONFIGURE_ROUTES  configure routes as required
DHCP_CONFIGURE_RESOLVER  configure resolv.conf as required
DHCP_CONFIGURE_RADVD  (DHCPv6 only) configure radvd.conf & restart radvd as required

Definition at line 114 of file libdhcp.h.


Function Documentation

int libdhcp_call_client ( LIBDHCP_Control ,
DHCP_Client  ,
  ... 
)

calls the dhcpv{4,6}_client function with the arguments in the variable argument list.

Definition at line 61 of file libdhcp.c.

Referenced by do_dhcpv6().

LIBDHCP_Control* libdhcp_control_new ( LIBDHCP_Callback  callback,
LIBDHCP_Capability  dhc_cap,
time_t  timeout,
void *  arg,
LIBDHCP_Error_Handler  error_handler,
uint8_t  log_level 
)

libdhcp_control_new - creates a new DHCP client control LIBDHCP_Control structure. The arguments correspond to the named LIBDHCP_Control structure members .

See also:
LIBDHCP_control
Parameters:
callback  the user's function to be called on state changes
dhc_cap  DHCP client capabilities to enable -
See also:
LIBDHCP_Capability
timeout  time period in seconds after which client must return
arg  argument to pass to user's callback as third arg
error_handler  the logger this client is to use
log_level  the maximum log level to be logged by this client

Definition at line 34 of file libdhcp.c.

References libdhcp_control_s::arg, libdhcp_control_s::callback, libdhcp_control_s::capability, libdhcp_control_s::eh, libdhcp_control_s::log_level, and libdhcp_control_s::timeout.

char* libdhcp_state_string ( DHCP_State  ,
char *  buf 
)

function to convert a DHCP_State to a string.

Definition at line 84 of file libdhcp.c.

References DHC4_BOUND, DHC4_EXPIRE, DHC4_FAIL, DHC4_MEDIUM, DHC4_NBI, DHC4_PREINIT, DHC4_REBIND, DHC4_REBOOT, DHC4_RELEASE, DHC4_RENEW, DHC4_STOP, DHC4_TIMEOUT, DHC6_BOUND, DHC6_REBIND, DHC6_RELEASE, and DHC_TIMEDOUT.

Referenced by dhcp4_nic_callback(), and dhcp6_nic_callback().

int libdhcp_stderr_logger ( struct libdhcp_control_s ctl,
int  priority,
const char *  fmt,
va_list  ap 
)

default error handler that logs to stderr.

See also:
LIBDHCP_Error_Handler

Definition at line 131 of file libdhcp.c.

References LOG_FATAL, and libdhcp_control_s::log_level.

int libdhcp_syslogger ( struct libdhcp_control_s ctl,
int  priority,
const char *  fmt,
va_list  ap 
)

default error handler that logs to syslog.

See also:
LIBDHCP_Error_Handler

Definition at line 167 of file libdhcp.c.

References LOG_FATAL, and libdhcp_control_s::log_level.


Generated on Mon Aug 14 17:25:56 2006 for libdhcp by  doxygen 1.4.7