 |
Nut/OS
4.10.3
API Reference
|
|
|
Nut/OS
4.10.3
API Reference
|
|
Dynamic host configuration protocol. More...
|
Data Structures | |
| struct | bootp |
| BOOTP message structure. More... | |
| struct | dyn_cfg |
| Dynamic configuration structure. More... | |
Typedefs | |
| typedef struct bootp | BOOTP |
| BOOTP message structure type. | |
| typedef struct dyn_cfg | DYNCFG |
| Dynamic configuration structure type. | |
Functions | |
| void | DhcpStateDebug (uint_fast8_t n, uint_fast8_t s, int li, int lt, ureg_t retries) |
| void | NutDhcpClient (void *arg) |
| DHCP client thread. | |
| int | NutDhcpIfConfig (CONST char *name, uint8_t *mac, uint32_t timeout) |
| Automatically configure an Ethernet network interface. | |
| int | NutDhcpRelease (CONST char *name, uint32_t timeout) |
| Relinguish our DHCP lease. | |
| int | NutDhcpInform (CONST char *name, uint32_t timeout) |
| Inform DHCP about an allocated address. | |
| int | NutDhcpStatus (CONST char *name) |
| Return DHCP client status. | |
| int | NutDhcpError (CONST char *name) |
| Return DHCP error code. | |
| int | NutDhcpIsConfigured (void) |
| Check if DHCP has configured our interface. | |
DHCP Client States. | |
Applications can request the current state of the DHCP client by calling NutDhcpStatus(). | |
| #define | DHCPST_IDLE 0 |
| DHCP state: Stopped. | |
| #define | DHCPST_INIT 1 |
| DHCP state: Starting. | |
| #define | DHCPST_SELECTING 2 |
| DHCP state: Selecting. | |
| #define | DHCPST_REQUESTING 3 |
| DHCP state: Requesting. | |
| #define | DHCPST_REBOOTING 4 |
| DHCP state: Rebooting. | |
| #define | DHCPST_BOUND 5 |
| DHCP state: Bound. | |
| #define | DHCPST_RENEWING 6 |
| DHCP state: Renewing. | |
| #define | DHCPST_REBINDING 7 |
| DHCP state: Rebinding. | |
| #define | DHCPST_INFORMING 8 |
| DHCP state: Informing. | |
| #define | DHCPST_RELEASING 9 |
| DHCP state: Releasing. | |
DHCP Error Codes | |
Applications can request the lastest error code of the DHCP client by calling NutDhcpError(). | |
| #define | DHCPERR_TIMEOUT 1 |
| DHCP timeout error. | |
| #define | DHCPERR_NOMAC 2 |
| DHCP MAC error. | |
| #define | DHCPERR_STATE 3 |
| DHCP state error. | |
| #define | DHCPERR_BADDEV 17 |
| DHCP error: Bad device. | |
| #define | DHCPERR_SYSTEM 18 |
| DHCP system error. | |
| #define | DHCPERR_TRANSMIT 19 |
| DHCP transmit error. | |
| #define | DHCPERR_RECEIVE 20 |
| DHCP receive error. | |
DHCP Client Configuration | |
The Nut/OS Configurator may be used to override the default values. | |
| #define | DHCP_SERVERPORT 67 |
| UDP port of DHCP server. | |
| #define | DHCP_CLIENTPORT 68 |
| UDP port of DHCP client. | |
| #define | MAX_DHCP_MSGSIZE 576 |
| Maximum DHCP message size we can accept. | |
| #define | MIN_DHCP_MSGSIZE 300 |
| Minimum DHCP message length. | |
| #define | MAX_DHCP_BUFSIZE 1728 |
| Maximum UDP buffer size used by the DHCP client. | |
| #define | MIN_DHCP_WAIT 4000 |
| Minimum number of milliseconds to wait for a response. | |
| #define | MAX_DHCP_WAIT 64000 |
| Maximum number of milliseconds to wait for a response. | |
| #define | MAX_DCHP_RETRIES 3 |
| Maximum number of request retries. | |
| #define | MAX_DCHP_RELEASE_RETRIES 0 |
| Maximum number of release retries. | |
| #define | DHCP_DEFAULT_LEASE 43200 |
| Default lease time in seconds. | |
| #define | MAX_DHCP_NAPTIME 4294967 |
| Maximum sleep time in seconds. | |
| #define | NUT_THREAD_DHCPSTACK 512 |
| Stack size of the DHCP client thread. | |
DHCP Message Types | |
| #define | DHCP_DISCOVER 1 |
| Client broadcast to locate available servers. | |
| #define | DHCP_OFFER 2 |
| Server to client in response to DHCP_DISCOVER. | |
| #define | DHCP_REQUEST 3 |
| Client message to servers. | |
| #define | DHCP_DECLINE 4 |
| Client to server indicating network address is already in use. | |
| #define | DHCP_ACK 5 |
| Server to client with configuration parameters. | |
| #define | DHCP_NAK 6 |
| Server to client indicating client's notion of network address is incorrect. | |
| #define | DHCP_RELEASE 7 |
| Client to server relinquishing network address and cancelling remaining lease. | |
| #define | DHCP_INFORM 8 |
| Client to server, asking only for local configuration parameters. | |
DHCP Options | |
| #define | DHCPOPT_PAD 0 |
| DHCP pad option. | |
| #define | DHCPOPT_NETMASK 1 |
| DHCP subnet mask option. | |
| #define | DHCPOPT_GATEWAY 3 |
| DHCP router option. | |
| #define | DHCPOPT_DNS 6 |
| DHCP domain name server option. | |
| #define | DHCPOPT_HOSTNAME 12 |
| DHCP host name option. | |
| #define | DHCPOPT_DOMAIN 15 |
| DHCP domain name option. | |
| #define | DHCPOPT_BROADCAST 28 |
| DHCP broadcast address option. | |
| #define | DHCPOPT_REQESTIP 50 |
| DHCP requested IP address option. | |
| #define | DHCPOPT_LEASETIME 51 |
| DHCP IP address lease time option. | |
| #define | DHCPOPT_MSGTYPE 53 |
| DHCP message type option. | |
| #define | DHCPOPT_SID 54 |
| DHCP server identifier option. | |
| #define | DHCPOPT_PARAMREQUEST 55 |
| DHCP parameter request list option. | |
| #define | DHCPOPT_MAXMSGSIZE 57 |
| Maximum DHCP message size option. | |
| #define | DHCPOPT_RENEWALTIME 58 |
| DHCP renewal time option. | |
| #define | DHCPOPT_REBINDTIME 59 |
| DHCP rebinding time option. | |
| #define | DHCPOPT_END 255 |
| DHCP end option. | |
Dynamic host configuration protocol.
Hosts running Nut/Net can make use of DHCP, if the local network provides this facility.
To use this feature, applications must call NutDhcpIfConfig().
#include <pro/dhcp.h> ... if(NutDhcpIfConfig("eth0", 0, 60000)) { printf("IP interface not configured. Error %d\n", NutDhcpError()); }
Application programmers often get confused by the fact, that NutDhcpIfConfig() is somewhat more general. It also checks non-volatile memory (e.g. EEPROM contents for the AVR devices). If a fixed IP address has been configured, it will use this and will not query DHCP for an IP configuration. The Ethernut Software Manual explains this in more detail.
Typical DHCP servers offer more than just the IP configuration. The following items are recognized by Nut/Net:
However, only the first three are used for the Nut/Net IP configuration. The broadcast address is internally created by the IP layer.
If provided by the DHCP server, the IP addresses of the primary and the secondary DNS are passed by the DHCP client to NutDnsConfig2().
The last two items, host and domain name, are currently discarded.
When an application wants to shut down the system, it may call NutDhcpRelease(). This lowers the burden on some busy DHCP servers with long lease times.
Applications doing their own IP configuration, e.g. using a user interface for their configuration and storing the values in non-volatile memory, may call NutDhcpInform() to inform DHCP servers about the address allocation.
The function NutDhcpStatus() is provided to enable applications to track the progress and the current status of the DHCP client.
| #define DHCPST_IDLE 0 |
DHCP state: Stopped.
Indicates that the DHCP client is inactive. Either it just started, gave up the lease or ran into an error. In the latter case the application may call NutDhcpError() to retrieve the specific error code.
In order to save heap memory, the client will not open the UDP socket while inactive.
Definition at line 147 of file dhcp.h.
Referenced by DhcpStateDebug(), NutDhcpClient(), and NutDhcpInform().
| #define DHCPST_INIT 1 |
DHCP state: Starting.
Indicates that the DHCP client started to request a configuration from the DHCP server. If any previously allocated IP address is available in the non-volatile configuration memory, then the client will continue with DHCPST_REBOOTING. Otherwise it will move to DHCPST_SELECTING.
Definition at line 157 of file dhcp.h.
Referenced by DhcpStateDebug(), NutDhcpClient(), and NutDhcpIfConfig().
| #define DHCPST_SELECTING 2 |
DHCP state: Selecting.
In this state the client will transmit a DHCP discover message and collect incoming offers from DHCP servers. If at least one acceptable offer has been received, it will change to DHCPST_REQUESTING.
Definition at line 165 of file dhcp.h.
Referenced by DhcpStateDebug(), and NutDhcpClient().
| #define DHCPST_REQUESTING 3 |
DHCP state: Requesting.
Indicates that the client received and selected an offer from a DHCP server. It is now sending a request for an offered configuration and waiting for an acknowledge, which will change the client's state to DHCPST_BOUND.
Definition at line 174 of file dhcp.h.
Referenced by DhcpStateDebug(), and NutDhcpClient().
| #define DHCPST_REBOOTING 4 |
DHCP state: Rebooting.
The client enters this state to request a previously assigned configuration.
Definition at line 181 of file dhcp.h.
Referenced by DhcpStateDebug(), and NutDhcpClient().
| #define DHCPST_BOUND 5 |
DHCP state: Bound.
This state indicates, that the DHCP client has successfully allocated a network address. Any thread blocked in NutDhcpIfConfig() will be woken up.
The client remains in this state until the renewal time elapses, in which case it moves to DHCPST_RENEWING.
In order to save heap memory, the client will close the UDP socket while in bound state.
Definition at line 195 of file dhcp.h.
Referenced by DhcpStateDebug(), NutDhcpClient(), NutDhcpIfConfig(), NutDhcpIsConfigured(), and NutDhcpRelease().
| #define DHCPST_RENEWING 6 |
DHCP state: Renewing.
In this state the client tries to extend its lease by sending a request to the DHCP server. If the server responds with an acknowledge, the client returns to DHCPST_BOUND.
If no acknowledge is received until the rebind time elapses, the client moves to DHCPST_REBINDING.
Definition at line 206 of file dhcp.h.
Referenced by DhcpStateDebug(), and NutDhcpClient().
| #define DHCPST_REBINDING 7 |
DHCP state: Rebinding.
The client enters this state after the no acknowledge has been received during DHCPST_RENEWING and the rebind time elapsed. It will broadcast a request to extend its lease.
If no acknowledge is received until the lease time elapsed, the client will move to DHCPST_INIT.
Definition at line 217 of file dhcp.h.
Referenced by DhcpStateDebug(), and NutDhcpClient().
| #define DHCPST_INFORMING 8 |
DHCP state: Informing.
The client enters this state when the application calls NutDhcpInform().
Definition at line 224 of file dhcp.h.
Referenced by DhcpStateDebug(), NutDhcpClient(), and NutDhcpInform().
| #define DHCPST_RELEASING 9 |
DHCP state: Releasing.
The client enters this state when the application calls NutDhcpRelease().
Definition at line 231 of file dhcp.h.
Referenced by DhcpStateDebug(), NutDhcpClient(), and NutDhcpRelease().
| #define DHCPERR_TIMEOUT 1 |
DHCP timeout error.
No server response within the specified number of milliseconds. Either the timeout value has been too low or no DHCP server is available in the local network.
Definition at line 251 of file dhcp.h.
Referenced by NutDhcpClient().
| #define DHCPERR_NOMAC 2 |
DHCP MAC error.
No Ethernet MAC address found in the non-volatile configuration memory and none specified by calling NutDhcpIfConfig().
Definition at line 259 of file dhcp.h.
Referenced by NutDhcpIfConfig().
| #define DHCPERR_STATE 3 |
DHCP state error.
Either NutDhcpInform() has been called while not in state DHCPST_IDLE or NutDhcpRelease() has been called while not in state DHCPST_BOUND.
Definition at line 268 of file dhcp.h.
Referenced by NutDhcpInform(), and NutDhcpRelease().
| #define DHCPERR_BADDEV 17 |
DHCP error: Bad device.
The specified device name hasn't been registered or is not an Ethernet device.
Definition at line 276 of file dhcp.h.
Referenced by NutDhcpIfConfig().
| #define DHCPERR_SYSTEM 18 |
DHCP system error.
A system error occured during DHCP processing. Most probably the system ran out of memory.
Definition at line 284 of file dhcp.h.
Referenced by NutDhcpClient().
| #define DHCPERR_TRANSMIT 19 |
DHCP transmit error.
Failed to send a UDP datagram. The DHCP client considers it a fatal error if NutUdpSendTo() to the broadcast address fails.
| #define DHCPERR_RECEIVE 20 |
DHCP receive error.
Failed to receive a UDP datagram. The DHCP client considers it a fatal error if NutUdpReceiveFrom() fails.
| #define DHCP_CLIENTPORT 68 |
| #define MAX_DHCP_MSGSIZE 576 |
| #define MIN_DHCP_MSGSIZE 300 |
| #define MAX_DHCP_BUFSIZE 1728 |
Maximum UDP buffer size used by the DHCP client.
If this item is not equal zero, the DHCP client will use its value to set SO_RCVBUF by calling NutUdpSetSockOpt().
If this item is set to zero, NutUdpSetSockOpt() is not called and the UDP socket interface will buffer the last incoming datagram on the DHCP_CLIENTPORT socket port only. Any previously received datagram is silently discarded. As long as one DHCP server is expected in the local network, this will be fine and save some heap memory while DHCP is active.
Definition at line 300 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define MIN_DHCP_WAIT 4000 |
Minimum number of milliseconds to wait for a response.
If we receive no response from a DHCP server within this time, we will double this value up to MAX_DHCP_WAIT and repeat our request up to MAX_DCHP_RETRIES times before giving up.
Definition at line 313 of file dhcpc.c.
Referenced by NutDhcpClient(), and NutDhcpIfConfig().
| #define MAX_DHCP_WAIT 64000 |
Maximum number of milliseconds to wait for a response.
The timeout value for receiving server responses will be doubled on each retry but limited by this value.
Definition at line 325 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define MAX_DCHP_RETRIES 3 |
Maximum number of request retries.
We will give up after resending this number of requests without receiving a response.
Definition at line 337 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define MAX_DCHP_RELEASE_RETRIES 0 |
Maximum number of release retries.
RFC 2131 doesn't specify a server response to release messages from the client. If the message gets lost, then the lease isn't released.
Definition at line 349 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define DHCP_DEFAULT_LEASE 43200 |
| #define MAX_DHCP_NAPTIME 4294967 |
Maximum sleep time in seconds.
Definition at line 369 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define NUT_THREAD_DHCPSTACK 512 |
| #define DHCP_DISCOVER 1 |
| #define DHCP_OFFER 2 |
| #define DHCP_REQUEST 3 |
Client message to servers.
Used for
| #define DHCP_DECLINE 4 |
| #define DHCP_ACK 5 |
Server to client with configuration parameters.
Contains committed network address.
Definition at line 431 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define DHCP_NAK 6 |
Server to client indicating client's notion of network address is incorrect.
May be caused by the client's move to new subnet or by expiration of the client's lease.
Definition at line 437 of file dhcpc.c.
Referenced by NutDhcpClient().
| #define DHCP_RELEASE 7 |
| #define DHCP_INFORM 8 |
| #define DHCPOPT_PAD 0 |
| #define DHCPOPT_REQESTIP 50 |
| #define DHCPOPT_LEASETIME 51 |
| #define DHCPOPT_PARAMREQUEST 55 |
| #define DHCPOPT_MAXMSGSIZE 57 |
| void DhcpStateDebug | ( | uint_fast8_t | n, |
| uint_fast8_t | s, | ||
| int | li, | ||
| int | lt, | ||
| ureg_t | retries | ||
| ) |
Definition at line 1387 of file dhcpc.c.
References __tcp_trf, __tcp_trs, DHCPST_BOUND, DHCPST_IDLE, DHCPST_INFORMING, DHCPST_INIT, DHCPST_REBINDING, DHCPST_REBOOTING, DHCPST_RELEASING, DHCPST_RENEWING, DHCPST_REQUESTING, DHCPST_SELECTING, fprintf(), inet_ntoa(), and NutGetSeconds().
Referenced by NutDhcpClient().
| NutDhcpClient | ( | void * | arg | ) |
DHCP client thread.
This thread implements a DHCP state machine and is automatically started when calling NutDhcpIfConfig() or NutDhcpInform().
Definition at line 1451 of file dhcpc.c.
References __tcp_trf, __tcp_trs, _CONFNET::cdn_ip_addr, _CONFNET::cdn_ip_mask, confnet, _NUTDEVICE::dev_icb, DHCP_ACK, DHCP_CLIENTPORT, DHCP_NAK, DHCPERR_SYSTEM, DHCPERR_TIMEOUT, DHCPST_BOUND, DHCPST_IDLE, DHCPST_INFORMING, DHCPST_INIT, DHCPST_REBINDING, DHCPST_REBOOTING, DHCPST_RELEASING, DHCPST_RENEWING, DHCPST_REQUESTING, DHCPST_SELECTING, DhcpStateDebug(), dyn_cfg::dyn_msgtyp, dyn_cfg::dyn_rebindTime, dyn_cfg::dyn_renewalTime, dyn_cfg::dyn_sid, dyn_cfg::dyn_yiaddr, fprintf(), free(), ifnet::if_local_ip, ifnet::if_mac, INADDR_BROADCAST, malloc(), MAX_DCHP_RELEASE_RETRIES, MAX_DCHP_RETRIES, MAX_DHCP_BUFSIZE, MAX_DHCP_NAPTIME, MAX_DHCP_WAIT, MIN_DHCP_WAIT, NUT_WAIT_INFINITE, NutEventBroadcast(), NutEventWait(), NutGetMillis(), NutGetSeconds(), NutUdpCreateSocket(), NutUdpDestroySocket(), NutUdpSetSockOpt(), and SO_RCVBUF.
Automatically configure an Ethernet network interface.
If no MAC address is specified, this routine will try to read a previously stored configuration from the EEPROM. If this retrieves a fixed IP configuration, then the network interface will be immediately configured with these values by calling NutNetIfConfig(). If no valid IP configuration has been read, then this routine will start the DHCP client thread and wait upto a given number of milliseconds for an acknowledged configuration from a DHCP server.
If a MAC address has been specified, this routine will not read the EEPROM configuration. If the application has set the global CONFNET structure to a valid IP configuration before calling this function, then the network interface will be immediately configured with these values by calling NutNetIfConfig(). Otherwise the DHCP client thread will be started and this routine will wait upto a given number of milliseconds for an acknowledged configuration from a DHCP server.
| name | Name of the registered Ethernet device. |
| mac | MAC address of the destination. Set NULL to use the configuration stored in the EEPROM. |
| timeout | Maximum number of milliseconds to wait. To disable timeout, set this parameter to NUT_WAIT_INFINITE. Otherwise the value must be larger than 3 times of MIN_DHCP_WAIT to enable collection of offers from multiple servers. |
Definition at line 2047 of file dhcpc.c.
References __tcp_trf, __tcp_trs, _CONFNET::cdn_cip_addr, _CONFNET::cdn_gateway, _CONFNET::cdn_ip_addr, _CONFNET::cdn_ip_mask, _CONFNET::cdn_mac, confnet, _NUTDEVICE::dev_icb, _NUTDEVICE::dev_type, DHCPERR_BADDEV, DHCPERR_NOMAC, DHCPST_BOUND, DHCPST_INIT, dyn_cfg::dyn_gateway, dyn_cfg::dyn_netmask, dyn_cfg::dyn_pdns, dyn_cfg::dyn_sdns, dyn_cfg::dyn_yiaddr, fprintf(), ifnet::if_local_ip, ifnet::if_mac, ifnet::if_mask, ifnet::if_type, IFT_ETHER, IFTYP_NET, inet_ntoa(), memcmp(), memcpy(), memset(), MIN_DHCP_WAIT, NutDeviceLookup(), NutDhcpRelease(), NutDnsConfig2(), NutNetIfConfig2(), NutNetIfSetup(), NutNetLoadConfig(), and NutSleep().
Referenced by main().
| int NutDhcpRelease | ( | CONST char * | name, |
| uint32_t | timeout | ||
| ) |
Relinguish our DHCP lease.
This function may be called by the application if we are moving to another network. It helps the DHCP server to tidy up his allocation table, but is not a required DHCP function.
Upon return, the system should be shut down within 20 seconds.
The client must reside in state DHCPST_BOUND.
| name | Name of the registered Ethernet device, currently ignored. |
| timeout | Maximum number of milliseconds to wait. |
Definition at line 2189 of file dhcpc.c.
References DHCPERR_STATE, DHCPST_BOUND, and DHCPST_RELEASING.
Referenced by NutDhcpIfConfig().
| int NutDhcpInform | ( | CONST char * | name, |
| uint32_t | timeout | ||
| ) |
Inform DHCP about an allocated address.
The client must reside in state DHCPST_IDLE.
| name | Name of the registered Ethernet device, currently ignored. |
| timeout | Maximum number of milliseconds to wait. |
Definition at line 2211 of file dhcpc.c.
References DHCPERR_STATE, DHCPST_IDLE, and DHCPST_INFORMING.
| int NutDhcpStatus | ( | CONST char * | name | ) |
Return DHCP client status.
| name | Name of the registered Ethernet device, currently ignored. |
| int NutDhcpError | ( | CONST char * | name | ) |
Return DHCP error code.
Possible error codes are
The error will be cleared upon return.
| name | Name of the registered Ethernet device, currently ignored. |
| int NutDhcpIsConfigured | ( | void | ) |
Check if DHCP has configured our interface.
Definition at line 2277 of file dhcpc.c.
References DHCPST_BOUND.