DHCPClient


Contents


Introduction

The DHCPClient module provides an implementation of the 'Dynamic Host Configuration Protocol'. This allows a server to allocate addresses to a client based on its internal ethernet 'MAC' address.

The module is able to control multiple interfaces simultaneously. Information about the DHCP configuration process is recorded to the DHCP log.


Service calls


Service_InternetStatus 4
(Service &B0)

Response received for BootP/DHCP request
On entry
R0=4 (sub-reason code>
R1=&B0 (reason code)
R2=Pointer to zero-terminated interface name
R3=Pointer to Device Information Block for interface
R4=Pointer to BootP/DHCP reply message buffer
R5=Size of BootP/DHCP reply
On exit
R0preserved
R1=0 to claim service, else preserved
R2-5preserved
Use

This service call is issued by the Internet module (version 5.28 or later) when a BOOTP/DHCP reply is received. Clients may inspect the contents of the buffer to extract any configuration information.

If you want to alter information in the buffer you may do so, but you must then claim the service call by setting R1 to zero on exit. If the service call is claimed the Internet module will reprocess the buffer as if it had just arrived from the network. Another Service_InternetStatus 4 will arrive in due course.

You should not normally claim this service call.

Related APIs
None

Service_InternetStatus 5
(Service &B0)

DHCPOffer has been received
On entry
R0=5 (sub-reason code>
R1=&B0 (reason code)
R2=Pointer to zero-terminated interface name
R3=Pointer to Device Information Block for interface
R4=Pointer to DHCPOFFER message buffer
R5=Size of DHCPOFFER message
On exit
R0preserved
R1=0 to claim service, else preserved
R2-5preserved
Use

This service call is issued by the DHCPClient module whenever it receives an offer of an IP address lease which is better than its current best choice (or if it is the first acceptable offer). You may inspect the buffer, but it must not be modified.

If clients choose to retain information about offers they MUST use the value of OPTION_SERVERIDENTIFIER as an opaque key to identify which offer has been chosen.

If you claim this service the DHCPClient module will not accept the offer, but will wait for another offer to be made.

You should not normally claim this service call.

Related APIs
None

Service_InternetStatus 48
(Service &B0)

DHCP address has been configured on an interface
On entry
R0=48 (sub-reason code>
R1=&B0 (reason code)
R2=Pointer to zero-terminated interface name
R3=IP address assigned to interface
On exit
R0-3preserved
Use

This service call is issued by the DHCPClient module (after 0.37) when it has successfully configured an interface with an address leased from a DHCP server. If the interface is reconfigured, the server releases the lease, the server fails to renew the lease, a duplicate address is identified, or the network stack is stopped, the lease will be lost and InternetStatus_DHCPLeaseLost will be issued. This service will not be reissued for renewals of the lease.

This service should never be claimed.

Related services
Service_InternetStatus 49

Service_InternetStatus 49
(Service &B0)

DHCP address has been removed from an interface
On entry
R0=49 (sub-reason code>
R1=&B0 (reason code)
R2=Pointer to zero-terminated interface name
R3=IP address that was assigned to interface
On exit
R0-3preserved
Use

This service call is issued by the DHCPClient module (after 0.37) when it has lost the DHCP server leased address allocated to an interface. A new address may be established by the DHCPClient if the server responds, or the interface may be manually reconfigured (however, this service may have been issued because of a manual reconfiguration). See Service_InternetStatus 48 for details of circumstances in which this service will be issued.

This service should never be claimed.

Related services
Service_InternetStatus 49

SWI calls


DHCPClient_Control
(SWI &55E00)

Controls the DHCPClient interface management
On entry
R0=

Reason code:

ValueMeaning
0Add interface
1Remove interface
2Renew lease/re-try obtaining a lease on an interface

R1=Pointer to zero-terminated interface name
On exit
R0-1preserved
Interrupts
Interrupts are undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant
Use

This SWI is used to add or remove an interface from the DHCPClient's control. Once placed under the control of the DHCPClient the interface will continue to operate according to the DHCP protocol until either the interface is configured manually or it is removed from the module's control by being reconfigured.

Related * commands
*DHCP

DHCPClient_State
(SWI &55E01)

Reads the status of a DHCPClient managed interface
On entry
R0=Pointer to zero-terminated interface name
R1=

Pointer to a list of information types as words, terminated by -1. Information types:

ValueMeaning
0

Interface state (1 word):

ValueMeaning
0sleeping
1initreboot
2init
3rebooting
4selecting
5requesting
6bound
7renewing
8rebinding

1Bound address - 'yiaddr' (1 word)
2Server address - 'siaddr' (1 word)
3Gateway address - 'giaddr' (1 word)
4lease period in centiseconds (1 word)
5T1 period in centiseconds (1 word)
6T2 period in centiseconds (1 word)
7DHCP start (8 bytes; 5 bytes time, 3 bytes padding)
8Lease start (8 bytes; 5 bytes time, 3 bytes padding)
9Lease end (8 bytes; 5 bytes time, 3 bytes padding)
10T1 end (8 bytes; 5 bytes time, 3 bytes padding)
11T2 end (8 bytes; 5 bytes time, 3 bytes padding)

R2=Pointer to buffer for returned data
R3=Size of the output buffer
On exit
R0preserved
R1=Pointer to invalid option, or -1 if all types are valid
R2=Pointer to first free byte in the output block
R3=Space left, or negative space needed if data would not fit
Interrupts
Interrupts are undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant
Use

This SWI is used to read the current DHCP client state for an interface. R1 points to a list of types which will be returned in the output buffer in the order in which they were supplied. If the block was not large enough, a 'Buffer overflow' error will be returned, with R3 set to the -ve size required. If the type of information requested was invalid, an error will return and R1 will point to the invalid entry.

Related * commands
*DHCPStatus

DHCPClient_Enumerate
(SWI &55E02)

Enumerates names of interfaces controlled by DHCPClient
On entry
R0=Pointer to zero-terminated interface name of the last interface, or 0 initially
R1=Pointer to buffer for returned data
R2=Size of the output buffer
On exit
R0=Number of state transitions
R1=pointer to buffer on entry, or 0 if no interfaces remain
R2=Space left, or negative space needed if data would not fit
Interrupts
Interrupts are undefined
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is not re-entrant
Use

This SWI enumerates the interfaces under DHCPClient control.

Related SWIs
DHCPClient_State

*Commands


*DHCP

Modify the DHCP control of an interface
Syntax
*DHCP [-+] <interface>
Parameters
<interface>- Name of the interface to change management of.
Use

This command is used to control whether the DHCPClient module will configure the network automatically using the DHCP protocol.

If no prefix is applied to the interface name the interface will be added to the list of those controlled by the DHCP module.

If a '-' prefix is used, the interface name will be removed from those controlled by the DHCP module and any address which is in use will be removed.

If a '+' prefix is used, an existing DHCP lease on that interface will be renewed, or a new attempt to obtain a lease will be made.

Example
*DHCP eh0
Related APIs
None

*DHCPStatus

Display information on DHCP controlled interfaces
Syntax
*DHCPStatus
Parameters
None
Use

This command is used to display information about interfaces controlled by the DHCPClient module.

Example
*DHCP eh0
Related * commands
*ShowStat

Document information

Maintainer(s):
History:
RevisionDateAuthorChanges
12006GerphInitial version
  • Released as RISC OS Select documentation.
230 Dec 2021GerphPRM-in-XML conversion
  • Created from original Select documentation
Related:http://www.riscos.com/support/developers/riscos6/networking/dhcpclient.html
Disclaimer:

© Gerph, 2021.