DHCPv4

Overview

The Dynamic Host Configuration Protocol (DHCP) is a network management protocol used on IPv4 networks. A DHCPv4 server dynamically assigns an IPv4 address and other network configuration parameters to each device on a network so they can communicate with other IP networks. See this DHCP Wikipedia article for a detailed overview of how DHCP works.

Note that Zephyr only supports DHCP client functionality.

Sample usage

See DHCPv4 client sample application for details.

API Reference

group dhcpv4

DHCPv4.

Typedefs

typedef void (*net_dhcpv4_option_callback_handler_t)(struct net_dhcpv4_option_callback *cb, size_t length, enum net_dhcpv4_msg_type msg_type, struct net_if *iface)

Define the application callback handler function signature.

Note: cb pointer can be used to retrieve private data through CONTAINER_OF() if original struct net_dhcpv4_option_callback is stored in another private structure.

Param cb:

Original struct net_dhcpv4_option_callback owning this handler

Param length:

The length of data returned by the server. If this is greater than cb->max_length, only cb->max_length bytes will be available in cb->data

Param msg_type:

Type of DHCP message that triggered the callback

Param iface:

The interface on which the DHCP message was received

Enums

enum net_dhcpv4_msg_type

DHCPv4 message types.

These enumerations represent RFC2131 defined msy type codes, hence they should not be renumbered.

Additions, removald and reorders in this definition must be reflected within corresponding changes to net_dhcpv4_msg_type_name.

Values:

enumerator NET_DHCPV4_MSG_TYPE_DISCOVER = 1

Discover message.

enumerator NET_DHCPV4_MSG_TYPE_OFFER = 2

Offer message.

enumerator NET_DHCPV4_MSG_TYPE_REQUEST = 3

Request message.

enumerator NET_DHCPV4_MSG_TYPE_DECLINE = 4

Decline message.

enumerator NET_DHCPV4_MSG_TYPE_ACK = 5

Acknowledge message.

enumerator NET_DHCPV4_MSG_TYPE_NAK = 6

Negative acknowledge message.

enumerator NET_DHCPV4_MSG_TYPE_RELEASE = 7

Release message.

enumerator NET_DHCPV4_MSG_TYPE_INFORM = 8

Inform message.

Functions

static inline void net_dhcpv4_init_option_callback(struct net_dhcpv4_option_callback *callback, net_dhcpv4_option_callback_handler_t handler, uint8_t option, void *data, size_t max_length)

Helper to initialize a struct net_dhcpv4_option_callback properly.

Parameters:
  • callback – A valid Application’s callback structure pointer.

  • handler – A valid handler function pointer.

  • option – The DHCP option the callback responds to.

  • data – A pointer to a buffer for max_length bytes.

  • max_length – The maximum length of the data returned.

int net_dhcpv4_add_option_callback(struct net_dhcpv4_option_callback *cb)

Add an application callback.

Parameters:
  • cb – A valid application’s callback structure pointer.

Returns:

0 if successful, negative errno code on failure.

int net_dhcpv4_remove_option_callback(struct net_dhcpv4_option_callback *cb)

Remove an application callback.

Parameters:
  • cb – A valid application’s callback structure pointer.

Returns:

0 if successful, negative errno code on failure.

static inline void net_dhcpv4_init_option_vendor_callback(struct net_dhcpv4_option_callback *callback, net_dhcpv4_option_callback_handler_t handler, uint8_t option, void *data, size_t max_length)

Helper to initialize a struct net_dhcpv4_option_callback for encapsulated vendor-specific options properly.

Parameters:
  • callback – A valid Application’s callback structure pointer.

  • handler – A valid handler function pointer.

  • option – The DHCP encapsulated vendor-specific option the callback responds to.

  • data – A pointer to a buffer for max_length bytes.

  • max_length – The maximum length of the data returned.

int net_dhcpv4_add_option_vendor_callback(struct net_dhcpv4_option_callback *cb)

Add an application callback for encapsulated vendor-specific options.

Parameters:
  • cb – A valid application’s callback structure pointer.

Returns:

0 if successful, negative errno code on failure.

int net_dhcpv4_remove_option_vendor_callback(struct net_dhcpv4_option_callback *cb)

Remove an application callback for encapsulated vendor-specific options.

Parameters:
  • cb – A valid application’s callback structure pointer.

Returns:

0 if successful, negative errno code on failure.

void net_dhcpv4_start(struct net_if *iface)

Start DHCPv4 client on an iface.

Start DHCPv4 client on a given interface. DHCPv4 client will start negotiation for IPv4 address. Once the negotiation is success IPv4 address details will be added to interface.

Parameters:
  • iface – A valid pointer on an interface

void net_dhcpv4_stop(struct net_if *iface)

Stop DHCPv4 client on an iface.

Stop DHCPv4 client on a given interface. DHCPv4 client will remove all configuration obtained from a DHCP server from the interface and stop any further negotiation with the server.

Parameters:
  • iface – A valid pointer on an interface

void net_dhcpv4_restart(struct net_if *iface)

Restart DHCPv4 client on an iface.

Restart DHCPv4 client on a given interface. DHCPv4 client will restart the state machine without any of the initial delays used in start.

Parameters:
  • iface – A valid pointer on an interface

const char *net_dhcpv4_msg_type_name(enum net_dhcpv4_msg_type msg_type)

Return a text representation of the msg_type.

Parameters:
  • msg_type – The msg_type to be converted to text

Returns:

A text representation of msg_type