dhcp_client.h
Go to the documentation of this file.
1 /**
2  * @file dhcp_client.h
3  * @brief DHCP client (Dynamic Host Configuration Protocol)
4  *
5  * @section License
6  *
7  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _DHCP_CLIENT_H
30 #define _DHCP_CLIENT_H
31 
32 //Dependencies
33 #include "core/net.h"
34 #include "core/socket.h"
35 #include "core/udp.h"
36 #include "dhcp/dhcp_common.h"
37 
38 //DHCP client support
39 #ifndef DHCP_CLIENT_SUPPORT
40  #define DHCP_CLIENT_SUPPORT ENABLED
41 #elif (DHCP_CLIENT_SUPPORT != ENABLED && DHCP_CLIENT_SUPPORT != DISABLED)
42  #error DHCP_CLIENT_SUPPORT parameter is not valid
43 #endif
44 
45 //DHCP client tick interval
46 #ifndef DHCP_CLIENT_TICK_INTERVAL
47  #define DHCP_CLIENT_TICK_INTERVAL 200
48 #elif (DHCP_CLIENT_TICK_INTERVAL < 10)
49  #error DHCP_CLIENT_TICK_INTERVAL parameter is not valid
50 #endif
51 
52 //Host name option support
53 #ifndef DHCP_CLIENT_HOSTNAME_OPTION_SUPPORT
54  #define DHCP_CLIENT_HOSTNAME_OPTION_SUPPORT ENABLED
55 #elif (DHCP_CLIENT_HOSTNAME_OPTION_SUPPORT != ENABLED && DHCP_CLIENT_HOSTNAME_OPTION_SUPPORT != DISABLED)
56  #error DHCP_CLIENT_HOSTNAME_OPTION_SUPPORT parameter is not valid
57 #endif
58 
59 //Maximum length of host name
60 #ifndef DHCP_CLIENT_MAX_HOSTNAME_LEN
61  #define DHCP_CLIENT_MAX_HOSTNAME_LEN 15
62 #elif (DHCP_CLIENT_MAX_HOSTNAME_LEN < 1)
63  #error DHCP_CLIENT_MAX_HOSTNAME_LEN parameter is not valid
64 #endif
65 
66 //Client identifier option support
67 #ifndef DHCP_CLIENT_ID_OPTION_SUPPORT
68  #define DHCP_CLIENT_ID_OPTION_SUPPORT DISABLED
69 #elif (DHCP_CLIENT_ID_OPTION_SUPPORT != ENABLED && DHCP_CLIENT_ID_OPTION_SUPPORT != DISABLED)
70  #error DHCP_CLIENT_ID_OPTION_SUPPORT parameter is not valid
71 #endif
72 
73 //Maximum size of client identifier
74 #ifndef DHCP_CLIENT_MAX_ID_SIZE
75  #define DHCP_CLIENT_MAX_ID_SIZE 15
76 #elif (DHCP_CLIENT_MAX_ID_SIZE < 1)
77  #error DHCP_CLIENT_MAX_ID_SIZE parameter is not valid
78 #endif
79 
80 //Random delay before sending the first message
81 #ifndef DHCP_CLIENT_INIT_DELAY
82  #define DHCP_CLIENT_INIT_DELAY 2000
83 #elif (DHCP_CLIENT_INIT_DELAY < 0)
84  #error DHCP_CLIENT_INIT_DELAY parameter is not valid
85 #endif
86 
87 //Initial retransmission timeout (DHCPDISCOVER)
88 #ifndef DHCP_CLIENT_DISCOVER_INIT_RT
89  #define DHCP_CLIENT_DISCOVER_INIT_RT 4000
90 #elif (DHCP_CLIENT_DISCOVER_INIT_RT < 1000)
91  #error DHCP_CLIENT_DISCOVER_INIT_RT parameter is not valid
92 #endif
93 
94 //Maximum retransmission timeout (DHCPDISCOVER)
95 #ifndef DHCP_CLIENT_DISCOVER_MAX_RT
96  #define DHCP_CLIENT_DISCOVER_MAX_RT 16000
97 #elif (DHCP_CLIENT_DISCOVER_MAX_RT < 1000)
98  #error DHCP_CLIENT_DISCOVER_MAX_RT parameter is not valid
99 #endif
100 
101 //Maximum retransmission count (DHCPREQUEST)
102 #ifndef DHCP_CLIENT_REQUEST_MAX_RC
103  #define DHCP_CLIENT_REQUEST_MAX_RC 4
104 #elif (DHCP_CLIENT_REQUEST_MAX_RC < 1)
105  #error DHCP_CLIENT_REQUEST_MAX_RC parameter is not valid
106 #endif
107 
108 //Initial retransmission timeout (DHCPREQUEST)
109 #ifndef DHCP_CLIENT_REQUEST_INIT_RT
110  #define DHCP_CLIENT_REQUEST_INIT_RT 4000
111 #elif (DHCP_CLIENT_REQUEST_INIT_RT < 1000)
112  #error DHCP_CLIENT_REQUEST_INIT_RT parameter is not valid
113 #endif
114 
115 //Maximum retransmission timeout (DHCPREQUEST)
116 #ifndef DHCP_CLIENT_REQUEST_MAX_RT
117  #define DHCP_CLIENT_REQUEST_MAX_RT 64000
118 #elif (DHCP_CLIENT_REQUEST_MAX_RT < 1000)
119  #error DHCP_CLIENT_REQUEST_MAX_RT parameter is not valid
120 #endif
121 
122 //Minimum delay between DHCPREQUEST messages in RENEWING and REBINDING states
123 #ifndef DHCP_CLIENT_REQUEST_MIN_DELAY
124  #define DHCP_CLIENT_REQUEST_MIN_DELAY 60000
125 #elif (DHCP_CLIENT_REQUEST_MIN_DELAY < 1000)
126  #error DHCP_CLIENT_REQUEST_MIN_DELAY parameter is not valid
127 #endif
128 
129 //Number of probe packets
130 #ifndef DHCP_CLIENT_PROBE_NUM
131  #define DHCP_CLIENT_PROBE_NUM 1
132 #elif (DHCP_CLIENT_PROBE_NUM < 0)
133  #error DHCP_CLIENT_PROBE_NUM parameter is not valid
134 #endif
135 
136 //Delay until repeated probe
137 #ifndef DHCP_CLIENT_PROBE_DELAY
138  #define DHCP_CLIENT_PROBE_DELAY 1000
139 #elif (DHCP_CLIENT_PROBE_DELAY < 100)
140  #error DHCP_CLIENT_PROBE_DELAY parameter is not valid
141 #endif
142 
143 //Random factor used to determine the delay between retransmissions
144 #ifndef DHCP_CLIENT_RAND_FACTOR
145  #define DHCP_CLIENT_RAND_FACTOR 1000
146 #elif (DHCP_CLIENT_RAND_FACTOR < 100)
147  #error DHCP_CLIENT_RAND_FACTOR parameter is not valid
148 #endif
149 
150 //Forward declaration of DhcpClientContext structure
151 struct _DhcpClientContext;
152 #define DhcpClientContext struct _DhcpClientContext
153 
154 //C++ guard
155 #ifdef __cplusplus
156  extern "C" {
157 #endif
158 
159 
160 /**
161  * @brief DHCP FSM states
162  **/
163 
164 typedef enum
165 {
175 } DhcpState;
176 
177 
178 /**
179  * @brief DHCP configuration timeout callback
180  **/
181 
182 typedef void (*DhcpTimeoutCallback)(DhcpClientContext *context,
183  NetInterface *interface);
184 
185 
186 /**
187  * @brief Link state change callback
188  **/
189 
190 typedef void (*DhcpLinkChangeCallback)(DhcpClientContext *context,
191  NetInterface *interface, bool_t linkState);
192 
193 
194 /**
195  * @brief FSM state change callback
196  **/
197 
199  NetInterface *interface, DhcpState state);
200 
201 
202 /**
203  * @brief DHCP client settings
204  **/
205 
206 typedef struct
207 {
208  NetInterface *interface; ///<Network interface to configure
209 #if (DHCP_CLIENT_HOSTNAME_OPTION_SUPPORT == ENABLED)
211 #endif
212 #if (DHCP_CLIENT_ID_OPTION_SUPPORT == ENABLED)
213  uint8_t clientId[DHCP_CLIENT_MAX_ID_SIZE]; ///<Client identifier
214  size_t clientIdLength; ///<Length of the client identifier
215 #endif
216  bool_t rapidCommit; ///<Quick configuration using rapid commit
217  bool_t manualDnsConfig; ///<Force manual DNS configuration
218  systime_t timeout; ///<DHCP configuration timeout
219  DhcpTimeoutCallback timeoutEvent; ///<DHCP configuration timeout event
220  DhcpLinkChangeCallback linkChangeEvent; ///<Link state change event
221  DhcpStateChangeCallback stateChangeEvent; ///<FSM state change event
223 
224 
225 /**
226  * @brief DHCP client context
227  **/
228 
230 {
231  DhcpClientSettings settings; ///<DHCP client settings
232  bool_t running; ///<This flag tells whether the DHCP client is running or not
233  DhcpState state; ///<Current state of the FSM
234  bool_t timeoutEventDone; ///<Timeout callback function has been called
235  systime_t timestamp; ///<Timestamp to manage retransmissions
236  systime_t timeout; ///<Timeout value
237  systime_t retransmitTimeout; ///<Retransmission timeout
238  uint_t retransmitCount; ///<Retransmission counter
239  Ipv4Addr serverIpAddr; ///<DHCP server IPv4 address
240  Ipv4Addr requestedIpAddr; ///<Requested IPv4 address
241  uint32_t transactionId; ///<Value to match requests with replies
242  systime_t configStartTime; ///<Address acquisition or renewal process start time
243  systime_t leaseStartTime; ///<Lease start time
244  uint32_t leaseTime; ///<Lease time
245  uint32_t t1; ///<Time at which the client enters the RENEWING state
246  uint32_t t2; ///<Time at which the client enters the REBINDING state
247 };
248 
249 
250 //Tick counter to handle periodic operations
252 
253 //DHCP client related functions
259 
260 void dhcpClientTick(DhcpClientContext *context);
262 
272 
276 
277 void dhcpClientProcessMessage(NetInterface *interface,
278  const IpPseudoHeader *pseudoHeader, const UdpHeader *udpHeader,
279  const NetBuffer *buffer, size_t offset, void *param);
280 
282  const DhcpMessage *message, size_t length);
283 
285  const DhcpMessage *message, size_t length);
286 
288  const DhcpMessage *message, size_t length);
289 
291 
293 
295  DhcpState newState, systime_t delay);
296 
298 
299 //C++ guard
300 #ifdef __cplusplus
301  }
302 #endif
303 
304 #endif
uint_t retransmitCount
Retransmission counter.
Definition: dhcp_client.h:238
DhcpLinkChangeCallback linkChangeEvent
Link state change event.
Definition: dhcp_client.h:220
bool_t running
This flag tells whether the DHCP client is running or not.
Definition: dhcp_client.h:232
uint32_t Ipv4Addr
IPv4 network address.
Definition: ipv4.h:232
uint32_t systime_t
Definition: compiler_port.h:44
#define DhcpClientContext
Definition: dhcp_client.h:152
char char_t
Definition: compiler_port.h:41
Definitions common to DHCP client and server.
TCP/IP stack core.
error_t dhcpClientInit(DhcpClientContext *context, const DhcpClientSettings *settings)
DHCP client initialization.
Definition: dhcp_client.c:110
systime_t timestamp
Timestamp to manage retransmissions.
Definition: dhcp_client.h:235
void dhcpClientStateRenewing(DhcpClientContext *context)
RENEWING state.
Definition: dhcp_client.c:823
DhcpClientSettings settings
DHCP client settings.
Definition: dhcp_client.h:231
void dhcpClientStateInit(DhcpClientContext *context)
INIT state.
Definition: dhcp_client.c:416
#define DHCP_CLIENT_MAX_HOSTNAME_LEN
Definition: dhcp_client.h:61
uint8_t message[]
Definition: chap.h:150
uint32_t leaseTime
Lease time.
Definition: dhcp_client.h:244
void dhcpClientDumpConfig(DhcpClientContext *context)
Dump DHCP configuration for debugging purpose.
Definition: dhcp_client.c:1873
error_t dhcpClientStart(DhcpClientContext *context)
Start DHCP client.
Definition: dhcp_client.c:177
void(* DhcpLinkChangeCallback)(DhcpClientContext *context, NetInterface *interface, bool_t linkState)
Link state change callback.
Definition: dhcp_client.h:190
bool_t rapidCommit
Quick configuration using rapid commit.
Definition: dhcp_client.h:216
uint32_t t1
Time at which the client enters the RENEWING state.
Definition: dhcp_client.h:245
void dhcpClientStateProbing(DhcpClientContext *context)
PROBING state.
Definition: dhcp_client.c:715
void(* DhcpTimeoutCallback)(DhcpClientContext *context, NetInterface *interface)
DHCP configuration timeout callback.
Definition: dhcp_client.h:182
DhcpState
DHCP FSM states.
Definition: dhcp_client.h:164
size_t clientIdLength
Length of the client identifier.
Definition: dhcp_client.h:214
void dhcpClientStateRequesting(DhcpClientContext *context)
REQUESTING state.
Definition: dhcp_client.c:518
systime_t retransmitTimeout
Retransmission timeout.
Definition: dhcp_client.h:237
void dhcpClientParseOffer(DhcpClientContext *context, const DhcpMessage *message, size_t length)
Parse DHCPOFFER message.
Definition: dhcp_client.c:1392
DHCP client context.
Definition: dhcp_client.h:229
NetInterface * interface
Network interface to configure.
Definition: dhcp_client.h:208
void dhcpClientChangeState(DhcpClientContext *context, DhcpState newState, systime_t delay)
Update DHCP FSM state.
Definition: dhcp_client.c:1809
systime_t dhcpClientTickCounter
Definition: dhcp_client.c:53
bool_t timeoutEventDone
Timeout callback function has been called.
Definition: dhcp_client.h:234
char_t clientId[]
DhcpStateChangeCallback stateChangeEvent
FSM state change event.
Definition: dhcp_client.h:221
__start_packed struct @126 UdpHeader
UDP header.
void dhcpClientParseNak(DhcpClientContext *context, const DhcpMessage *message, size_t length)
Parse DHCPNAK message.
Definition: dhcp_client.c:1673
Structure describing a buffer that spans multiple chunks.
Definition: net_mem.h:86
void dhcpClientTick(DhcpClientContext *context)
DHCP client timer handler.
Definition: dhcp_client.c:277
systime_t timeout
DHCP configuration timeout.
Definition: dhcp_client.h:218
void dhcpClientStateBound(DhcpClientContext *context)
BOUND state.
Definition: dhcp_client.c:782
void dhcpClientProcessMessage(NetInterface *interface, const IpPseudoHeader *pseudoHeader, const UdpHeader *udpHeader, const NetBuffer *buffer, size_t offset, void *param)
Process incoming DHCP message.
Definition: dhcp_client.c:1309
Ipv4Addr serverIpAddr
DHCP server IPv4 address.
Definition: dhcp_client.h:239
uint16_t dhcpClientComputeElapsedTime(DhcpClientContext *context)
Compute the appropriate secs field.
Definition: dhcp_client.c:1786
void dhcpClientParseAck(DhcpClientContext *context, const DhcpMessage *message, size_t length)
Parse DHCPACK message.
Definition: dhcp_client.c:1445
error_t
Error codes.
Definition: error.h:40
unsigned int uint_t
Definition: compiler_port.h:43
error_t dhcpClientStop(DhcpClientContext *context)
Stop DHCP client.
Definition: dhcp_client.c:220
void(* DhcpStateChangeCallback)(DhcpClientContext *context, NetInterface *interface, DhcpState state)
FSM state change callback.
Definition: dhcp_client.h:198
void dhcpClientStateSelecting(DhcpClientContext *context)
SELECTING state.
Definition: dhcp_client.c:456
systime_t timeout
Timeout value.
Definition: dhcp_client.h:236
#define NetInterface
Definition: net.h:34
DHCP client settings.
Definition: dhcp_client.h:206
uint32_t transactionId
Value to match requests with replies.
Definition: dhcp_client.h:241
IP pseudo header.
Definition: ip.h:76
__start_packed struct @127 DhcpMessage
DHCP message.
error_t dhcpClientSendDiscover(DhcpClientContext *context)
Send DHCPDISCOVER message.
Definition: dhcp_client.c:965
#define DHCP_CLIENT_MAX_ID_SIZE
Definition: dhcp_client.h:75
error_t dhcpClientSendRequest(DhcpClientContext *context)
Send DHCPREQUEST message.
Definition: dhcp_client.c:1076
DhcpState dhcpClientGetState(DhcpClientContext *context)
Retrieve current state.
Definition: dhcp_client.c:251
void dhcpClientCheckTimeout(DhcpClientContext *context)
Manage DHCP configuration timeout.
Definition: dhcp_client.c:1741
char_t hostname[]
Definition: tls.h:1443
void dhcpClientLinkChangeEvent(DhcpClientContext *context)
Callback function for link change event.
Definition: dhcp_client.c:354
uint32_t t2
Time at which the client enters the REBINDING state.
Definition: dhcp_client.h:246
bool_t manualDnsConfig
Force manual DNS configuration.
Definition: dhcp_client.h:217
Socket API.
uint8_t length
Definition: dtls_misc.h:140
systime_t configStartTime
Address acquisition or renewal process start time.
Definition: dhcp_client.h:242
void dhcpClientStateRebooting(DhcpClientContext *context)
REBOOTING state.
Definition: dhcp_client.c:637
error_t dhcpClientSendDecline(DhcpClientContext *context)
Send DHCPDECLINE message.
Definition: dhcp_client.c:1222
void dhcpClientGetDefaultSettings(DhcpClientSettings *settings)
Initialize settings with default values.
Definition: dhcp_client.c:73
int bool_t
Definition: compiler_port.h:47
UDP (User Datagram Protocol)
DhcpTimeoutCallback timeoutEvent
DHCP configuration timeout event.
Definition: dhcp_client.h:219
void dhcpClientStateRebinding(DhcpClientContext *context)
REBINDING state.
Definition: dhcp_client.c:888
void dhcpClientStateInitReboot(DhcpClientContext *context)
INIT-REBOOT state.
Definition: dhcp_client.c:597
systime_t leaseStartTime
Lease start time.
Definition: dhcp_client.h:243
DhcpState state
Current state of the FSM.
Definition: dhcp_client.h:233
Ipv4Addr requestedIpAddr
Requested IPv4 address.
Definition: dhcp_client.h:240