Dallas Semiconductor DS80C400 C Libraries Home Page

Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals

rom400_dhcp.h File Reference


Detailed Description

DHCP functions in the DS80C400 ROM.

This library contains functions that allow the DS80C400 to lease addresses from a DHCP server. Only Ipv4 addresses can be leased using DHCP. Ipv6 addresses are automatically configured. Once the DHCP client negotiates a lease on an address, functions from the socket libraries (rom400_sock.h) can be used to get the current IP address and communicate with other devices.

For detailed information on the DS80C400 please see the High-Speed Microcontroller User's Guide: DS80C400 Supplement.

Warning:
The functions in this library are multi-process safe--that is, if you call the same method from two different processes at the same time, the parameters to the function will not be destroyed. However, it is recommended that only one process manage the DHCP client as it is a system-wide resource.
Note that the DHCP client requires a clock that is no slower than 133% of real time. Otherwise, DHCP lease renewal might be problematic. Avoid blocking interrupts for extended periods of time and use init_setfrequency to set the correct crystal frequency.

Go to the source code of this file.

Defines

#define ROM400_DHCP_VERSION   12
#define DHCP_STATUS_INIT   0
#define DHCP_STATUS_SELECTING   1
#define DHCP_STATUS_REQUESTING   2
#define DHCP_STATUS_INITREBOOT   3
#define DHCP_STATUS_REBOOTING   4
#define DHCP_STATUS_BOUND   5
#define DHCP_STATUS_RENEWING   6
#define DHCP_STATUS_REBINDING   7
#define DHCP_MSG_DHCPDISCOVER   1
#define DHCP_MSG_DHCPOFFER   2
#define DHCP_MSG_DHCPREQUEST   3
#define DHCP_MSG_DHCPDECLINE   4
#define DHCP_MSG_DHCPACK   5
#define DHCP_MSG_DHCPNAK   6
#define DHCP_MSG_DHCPRELEASE   7
#define DHCP_MSG_DHCPINFORM   8

Functions

unsigned char dhcp_init (void)
 Initializes the DHCP client.
void dhcp_setrequestip (struct sockaddr *address, int len)
 Sets the requested IP (and INITREBOOT state).
unsigned int dhcp_status (void)
 Gets the status of the DHCP client.
void dhcp_stop (int releaseip)
 Disabled the DHCP client.
void dhcp_registernotify (void(*functionptr)(unsigned int newstate, unsigned char far *packet))
 Register a function to be notified when DHCP acquires or loses an IP.
void dhcp_registerparseoption (void(*functionptr)(unsigned char far *option))
 Register a function to be called when an unknown or unhandled DHCP option is encountered.
void dhcp_registerbuildpacket (unsigned char(*functionptr)(unsigned char far *option, unsigned char msgtype))
 Register a function to be called when a DHCP packet is about to be sent.
unsigned int dhcp_version (void)
 Returns the version number of this DHCP library.
void dhcp_getserverip (struct sockaddr *address, int len)
 Returns the IP address of the DHCP server.
void dhcp_getprimarydns (struct sockaddr *address)
 Returns the IP address of the primary DNS server.
void dhcp_getsecondarydns (struct sockaddr *address)
 Returns the IP address of the secondary DNS server.
unsigned int dhcp_gettaskid ()
 Returns task ID of the DHCP process.
int dhcp_getsocket ()
 Returns socket handle of the socket used in the DHCP process.


Define Documentation

#define DHCP_MSG_DHCPACK   5
 

DHCP message type ACK

#define DHCP_MSG_DHCPDECLINE   4
 

DHCP message type DECLINE

#define DHCP_MSG_DHCPDISCOVER   1
 

DHCP message type DISCOVER

#define DHCP_MSG_DHCPINFORM   8
 

DHCP message type INFORM

#define DHCP_MSG_DHCPNAK   6
 

DHCP message type NAK

#define DHCP_MSG_DHCPOFFER   2
 

DHCP message type OFFER

#define DHCP_MSG_DHCPRELEASE   7
 

DHCP message type RELEASE

#define DHCP_MSG_DHCPREQUEST   3
 

DHCP message type REQUEST

#define DHCP_STATUS_BOUND   5
 

DHCP status code returned by dhcp_status. The DHCP client is in the BOUND state: it has been configured with a valid address.

See also:
dhcp_status

#define DHCP_STATUS_INIT   0
 

DHCP status code returned by dhcp_status. The DHCP client is in the INIT state: it has not yet sent a DHCP_DISCOVER message.

See also:
dhcp_status

#define DHCP_STATUS_INITREBOOT   3
 

DHCP status code returned by dhcp_status. The DHCP client is in the INITREBOOT state: it has rebooted, and is trying to acquire its old address.

See also:
dhcp_status

#define DHCP_STATUS_REBINDING   7
 

DHCP status code returned by dhcp_status. The DHCP client is in the REBINDING state: it is attempting to get a new lease after its current lease expired.

See also:
dhcp_status

#define DHCP_STATUS_REBOOTING   4
 

DHCP status code returned by dhcp_status. The DHCP client is in the REBOOTING state: after a reboot, it is waiting for permission to use its old address.

See also:
dhcp_status

#define DHCP_STATUS_RENEWING   6
 

DHCP status code returned by dhcp_status. The DHCP client is in the RENEWING state: it is attempting to extend the current, valid lease of its address.

See also:
dhcp_status

#define DHCP_STATUS_REQUESTING   2
 

DHCP status code returned by dhcp_status. The DHCP client is in the REQUESTING state: it has requested a DHCP address, and is awaiting a reply.

See also:
dhcp_status

#define DHCP_STATUS_SELECTING   1
 

DHCP status code returned by dhcp_status. The DHCP client is in the SELECTING state: it is collecting DHCP offers.

See also:
dhcp_status

#define ROM400_DHCP_VERSION   12
 

Version number associated with this header file. Should be the same as the version number returned by the dhcp_version function.

See also:
dhcp_version


Function Documentation

void dhcp_getprimarydns struct sockaddr address  ) 
 

Returns the IP address of the primary DNS server.

Returns the IP address of the primary DNS server. The DNS server can be set by an option received from a DHCP response, or by setting it manually from the DNS library function dns_setprimary. Note that this DNS server information entry is cleared out on initialization.

Parameters:
address will fill in the primary DNS server IP address
See also:
dhcp_getsecondarydns

dns_setprimary

dns_getprimary

void dhcp_getsecondarydns struct sockaddr address  ) 
 

Returns the IP address of the secondary DNS server.

Returns the IP address of the primary DNS server. The DNS server can be set by an option received from a DHCP response, or by setting it manually from the DNS library function dns_setprimary. Note that this DNS server information entry is cleared out on initialization.

Parameters:
address will fill in the secondary DNS server IP address
See also:
dhcp_getprimarydns

dns_setsecondary

dns_getsecondary

void dhcp_getserverip struct sockaddr address,
int  len
 

Returns the IP address of the DHCP server.

Parameters:
address will fill in the DHCP server IP address
len length of the address structure (ignored)

int dhcp_getsocket  ) 
 

Returns socket handle of the socket used in the DHCP process.

Returns the socket handle of the socket used in the DHCP process. If the DHCP process is not running, the return value is invalid.

Returns:
Socket handle of DHCP socket
See also:
dhcp_gettaskid

unsigned int dhcp_gettaskid  ) 
 

Returns task ID of the DHCP process.

Returns the task ID of the DHCP process. If the DHCP process has not been initialized (but the init_rom function has been called), this function returns 0.

The value returned by this function is suitable to use with the task library--for instance, to alter the priority of the DHCP task.

Returns:
Task ID of the DHCP process.
See also:
dhcp_init

dhcp_getsocket

unsigned char dhcp_init void   ) 
 

Initializes the DHCP client.

Starts a DHCP Client task and returns to the caller. DHCP is implemented for IPv4 only. The IPv6 portion of the network stack uses neighbor discovery. To read the address that the DHCP client has leased, use the socket library function getnetworkparams. DHCP tries to request a previously leased IP (INITREBOOT state), see dhcp_setrequestip. This can cause dhcp_init to take a long time. Set a zero IP to force the INIT state.

Returns:
0 for success, non-zero for failure.
See also:
dhcp_stop

getnetworkparams [in the socket library]

dhcp_setrequestip

void dhcp_registerbuildpacket unsigned char(*)(unsigned char far *option, unsigned char msgtype)  functionptr  ) 
 

Register a function to be called when a DHCP packet is about to be sent.

The function passed as functionptr will be called when the DHCP client is about to send a DHCP packet. The function pointed to by functionptr should take two argumentis (a pointer and a byte) and return a byte. Whenever the function at functionptr is called, the pointer will be pointing to the first byte after the default options. The user can fill in additional DHCP options, e.g. 0x0c,0x04,'T','I','N','I' would be a DHCP hostname option. The msgtype argument contains the current DHCP message type (DHCP_MSG_DISCOVER or DHCP_MSG_REQUEST). The return value is the number of bytes added to the DHCP options, 6 in the hostname example above.

The function does not need to save/restore any registers.

Parameters:
functionptr Pointer to a function with the signature unsigned char fn(unsigned char far* option, unsigned char msgtype)

void dhcp_registernotify void(*)(unsigned int newstate, unsigned char far *packet)  functionptr  ) 
 

Register a function to be notified when DHCP acquires or loses an IP.

The function passed as functionptr will be called when the DHCP client acquires or loses an IP.

Parameters:
functionptr Pointer to a function with the signature void fn(unsigned int newstate, unsigned char far *packet). The function will be provided with the new DHCP state and a pointer to the last DHCP packet received (the packet pointer points to the beginning of the BOOTP data structure).
See also:
dhcp_status

void dhcp_registerparseoption void(*)(unsigned char far *option)  functionptr  ) 
 

Register a function to be called when an unknown or unhandled DHCP option is encountered.

The function passed as functionptr will be called when the DHCP client is parsing an unknown DHCP option. The function pointed to by functionptr should take one argument (a pointer) and return void. Whenever the function at functionptr is called, the argument will be pointing to the current unhandled or vendor specific DHCP option.

The function does not need to save/restore any registers.

Parameters:
functionptr Pointer to a function with the signature void fn(unsigned char far* option).

void dhcp_setrequestip struct sockaddr address,
int  len
 

Sets the requested IP (and INITREBOOT state).

When dhcp_init is called and the requested IP is not zero, the DHCP state machine will start in INITREBOOT state and try to obtain a previously leased IP (if the DHCP server doesn't answer or the request is denied, it will ignore the requested IP). Setting a requested IP can delay the IP lease if the DHCP server doesn't respond (e.g. because it didn't retain the client record); set to zero to force the state machine to INIT state.

Parameters:
address fill in the requested IP address
len length of the address structure (ignored)
See also:
dhcp_init

unsigned int dhcp_status void   ) 
 

Gets the status of the DHCP client.

Returns the current state of the DHCP Client. DHCP Clients that have leased a valid address should return DHCP_STATUS_BOUND.

Returns:
Status of the DHCP client.

void dhcp_stop int  releaseip  ) 
 

Disabled the DHCP client.

Kills the DHCP client task. Use dhcp_init to restart the DHCP client. If the "releaseip" argument is non-zero, a DHCP release message is sent. Some DHCP servers don't retain client records, and releasing the IP will make it impossible/slower to get the same IP after a reboot.

Parameters:
releaseip -- 0: don't send a DHCP release message
See also:
dhcp_init

unsigned int dhcp_version void   ) 
 

Returns the version number of this DHCP library.

Returns:
Version number of this DHCP library.


Copyright 2005 Dallas Semiconductor, Inc.. Documentation generated by Doxygen.