VxWorks Reference Manual : Libraries
dhcpcLib - Dynamic Host Configuration Protocol (DHCP) run-time client API
dhcpcLibInit( ) - DHCP client library initialization
dhcpcInit( ) - assign network interface and setup lease request
dhcpcEventHookAdd( ) - add a routine to handle configuration parameters
dhcpcEventHookDelete( ) - remove the configuration parameters handler
dhcpcCacheHookAdd( ) - add a routine to store and retrieve lease data
dhcpcCacheHookDelete( ) - delete a lease data storage routine
dhcpcBind( ) - obtain a set of network configuration parameters with DHCP
dhcpcVerify( ) - renew an established lease
dhcpcRelease( ) - relinquish specified lease
dhcpcInformGet( ) - obtain additional configuration parameters with DHCP
dhcpcShutdown( ) - disable DHCP client library
dhcpcOptionGet( ) - retrieve an option provided to a client and store in a buffer
dhcpcServerGet( ) - retrieve the current DHCP server
dhcpcTimerGet( ) - retrieve current lease timers
dhcpcParamsGet( ) - retrieve current configuration parameters
This library implements the run-time access to the client side of the Dynamic Host Configuration Protocol (DHCP). DHCP is an extension of BOOTP. Like BOOTP, the protocol allows a host to initialize automatically by obtaining its IP address, boot file name, and boot host's IP address over a network. Additionally, DHCP provides a client with the complete set of parameters defined in the Host Requirements RFCs and allows automatic reuse of network addresses by specifying individual leases for each set of configuration parameters. The compatible message format allows DHCP participants to interact with BOOTP participants. The dhcpcLibInit( ) routine links this library into the VxWorks image. This happens automatically if INCLUDE_DHCPC is defined at the time the image is built.
When used during run time, the DHCP client library establishes and maintains one or more DHCP leases. Each lease provides access to a set of configuration parameters. If requested, the parameters retrieved will be used to reconfigure the associated network interface, but may also be handled separately through an event hook. The dhcpcEventHookAdd( ) routine specifies a function which is invoked whenever the lease status changes. The dhcpcEventHookDelete( ) routine will disable that notification. The automatic reconfiguration must be limited to one lease for a particular network interface. Otherwise, multiple leases would attempt to reconfigure the same device, with unpredictable results.
To access the DHCP client during run time, an application must first call the dhcpcInit( ) routine with a pointer to the network interface to be used for communication with a DHCP server. Each call to the initialization routine returns a unique identifier to be used in subsequent calls to the DHCP client routines. Next, the application must specify a client identifier for the lease using the dhcpcOptionSet( ) call. Typically, the link-level hardware address is used for this purpose. Additional calls to the option set routine may be used to request specific DHCP options. After all calls to that routine are completed, a call to dhcpcBind( ) will retrieve a set of configuration parameters according to the client-server interaction detailed in RFC 1541.
Each sequence of the three function calls described above, if successful, will retrieve a set of configuration parameters from a DHCP server. The dhcpcServerGet( ) routine retrieves the address of the server that provided a particular lease. The dhcpcTimerGet( ) routine will retrieve the current values for both lease timers.
Alternatively, the dhcpcParamsGet( ) and dhcpcOptionGet( ) routines will access any options provided by a DHCP server. In addition to the lease identifier obtained from the initialization routine, the dhcpcParamsGet( ) routine accepts a parameter descriptor structure that selects any combination of the options described in RFC 1533 for retrieval. Similarly, the dhcpcOptionGet( ) routine retrieves the values associated with a single option.
This library also contains several routines which explicitly generate DHCP messages. The dhcpcVerify( ) routine causes the client to renew a particular lease, regardless of the time remaining. The dhcpcRelease( ) routine relinquishes the specified lease. The associated parameters are no longer valid. If those parameters were used by the underlying network device, the routine also shuts off all network processing for that interface. Finally, the dhcpcShutdown( ) routine will release all active leases and disable all the DHCP client library routines.
The dhcpcCacheHookAdd( ) routine registers a function that the client will use to store and retrieve lease data. The client can then re-use this information if it is rebooted. The dhcpcCacheHookDelete( ) routine prevents the re-use of lease data. Initially, a function to access permanent storage is not provided.
dhcpcLib.h
dhcpcLib, RFC 1541, RFC 1533
dhcpcLibInit( ) - DHCP client library initialization
STATUS dhcpcLibInit ( int serverPort, /* port used by DHCP servers (default 67) */ int clientPort, /* port used by DHCP clients (default 68) */ int maxLeases, /* max number of simultaneous leases allowed */ int maxSize, /* largest DHCP message supported, in bytes */ int offerTimeout, /* interval to get additional DHCP offers */ int defaultLease, /* default value for requested lease length */ int minLease /* minimum accepted lease length */ )
This routine creates and initializes the global data structures used by the DHCP client library to maintain multiple leases, up to the limit specified by the maxLeases parameter. Every subsequent lease attempt will collect additional DHCP offers until the interval specified by offerTimeout expires and will request the lease duration indicated by defaultLease. The maxSize parameter specifies the maximum length supported for any DHCP message, including the UDP and IP headers and the largest link level header for all supported devices. The maximum length of the DHCP options field is based on this value or the MTU size for a lease's underlying interface, whichever is less. The smallest valid value for the maxSize parameter is 576 bytes, corresponding to the minimum IP datagram a host must accept. Larger values will allow the client to handle longer DHCP messages.
This routine must be called before calling any other library routines. The routine is called automatically if INCLUDE_DHCPC is defined at the time the system is built and assigns the global lease settings to the values specified by DHCPC_SPORT, DHCPC_CPORT, DHCPC_MAX_LEASES, DHCPC_MAX_MSGSIZE, DHCPC_DEFAULT_LEASE, and DHCPC_OFFER_TIMEOUT.
OK, or ERROR if initialization fails.
S_dhcpcLib_MEM_ERROR
dhcpcInit( ) - assign network interface and setup lease request
void * dhcpcInit ( struct ifnet * pIf, /* network device used by client */ BOOL autoConfig /* reconfigure network device? */ )
This routine creates the data structures used to obtain a set of parameters with DHCP and must be called before each attempt at establishing a DHCP lease, but after the dhcpcLibInit( ) routine has initialized the global data structures.
The pIf argument indicates the network device which will be used for transmission and reception of DHCP messages during the lifetime of the lease. The DHCP client supports devices attached to the IP protocol with the MUX/END interface. The specified device must be capable of sending broadcast messages. It also supports BSD Ethernet devices attached to the IP protocol. The MTU size of any interface must be large enough to receive a minimum IP datagram of 576 bytes. If the interface MTU size is less than the maximum message size set in the library initialization it also determines the maximum length of the DHCP options field.
If the autoConfig parameter is set to TRUE, any address information obtained will automatically be applied to the specified interface. The autoConfig parameter also selects the default option request list for a lease. If set to FALSE, no specific lease options are requested since any configuration parameters obtained are not intended for the underlying network device. In that case, any specific options required may be added to the request list at any time before the corresponding dhcpcBind( ) call. If autoConfig is TRUE, this routine sets the configuration parameters to request the minimal address information (subnet mask and broadcast address) necessary for reconfiguring the network device specified by pIf.
The internal lease identifier returned by this routine must be used in subsequent calls to the DHCP client library.
This routine is called automatically during system startup if the DHCP client was used to obtain the VxWorks boot parameters. The resulting lease will always reconfigure the network boot device. Therefore, any further calls to this routine which specify the network boot device for use in obtaining additional DHCP leases must set autoConfig to FALSE. Otherwise, that device will be unable to maintain a stable configuration. The global variable pDhcpcBootCookie provides access to the configuration parameters for any DHCP lease created during system startup.
Lease handle for later use, or NULL if lease setup fails.
S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_BAD_DEVICE, S_dhcpcLib_BAD_OPTION,
S_dhcpcLib_MAX_LEASES_REACHED, S_dhcpcLib_MEM_ERROR
dhcpcLib, dhcpcOptionSet( ), dhcpcEventHookAdd( )
dhcpcEventHookAdd( ) - add a routine to handle configuration parameters
STATUS dhcpcEventHookAdd ( void * pCookie, /* identifier returned by dhcpcInit() */ FUNCPTR pEventHook /* routine to handle lease parameters */ )
This routine installs a hook routine to handle changes in the configuration parameters provided for the lease indicated by pCookie. The hook provides an alternate configuration method for DHCP leases and uses the following interface:
void dhcpcEventHookRtn ( int leaseEvent, /* new or expired parameters */ void * pCookie /* lease identifier from dhcpcInit() */ )The routine is called with the leaseEvent parameter set to DHCPC_LEASE_NEW whenever a lease is successfully established. The DHCPC_LEASE_NEW event does not occur when a lease is renewed by the same DHCP server, since the parameters do not change in that case. However, it does occur if the client rebinds to a different DHCP server. The DHCPC_LEASE_INVALID event indicates that the configuration parameters for the corresponding lease may no longer be used. That event occurs when a lease expires or a renewal or verification attempt fails, and coincides with re-entry into the initial state of the negotiation process.If the lease initialization specified automatic configuration of the corresponding network interface, any installed hook routine will be invoked after the new address information is applied.
OK if notification hook added, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED
dhcpcEventHookDelete( ) - remove the configuration parameters handler
STATUS dhcpcEventHookDelete ( void * pCookie /* identifier returned by dhcpcInit() */ )
This routine removes the hook routine that handled changes in the configuration parameters for the lease indicated by pCookie. If the lease initialization specified automatic configuration of the corresponding network interface, the assigned address could change without warning after this routine is executed.
OK if notification hook removed, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED
dhcpcCacheHookAdd( ) - add a routine to store and retrieve lease data
STATUS dhcpcCacheHookAdd ( FUNCPTR pCacheHookRtn /* routine to store/retrieve lease data */ )
This routine adds a hook routine that is called at the bound state (to store the lease data) and during the INIT_REBOOT state (to re-use the parameters if the lease is still active). The calling sequence of the input hook routine is:
STATUS dhcpcCacheHookRtn ( int command, /* requested cache operation */ unsigned long *pTimeStamp, /* lease timestamp data */ int *pDataLen, /* length of data to access */ char *pBuffer /* pointer to data buffer */ )The hook routine should return OK if the requested operation is completed successfully, or ERROR otherwise. All the supplied pointers reference memory locations that are reused upon return from the hook. The hook routine must copy the data elsewhere.
The setting of the cache hook routine during a dhcpcInit( ) call is recorded and used by the resulting lease throughout its lifetime. Since the hook routine is intended to store a single lease record, a separate hook routine should be specified before the dhcpcInit( ) call for each lease which will re-use its parameters across reboots.
The command parameter specifies one of the following operations:
- DHCP_CACHE_WRITE
- Save the indicated data. The write operation must preserve the value referenced by pTimeStamp and the contents of pBuffer. The pDataLen parameter indicates the number of bytes in that buffer.
- DHCP_CACHE_READ
- Restore the saved data. The read operation must copy the data from the most recent write operation into the location indicated by pBuffer, set the contents of pDataLen to the amount of data provided, and store the corresponding timestamp value in pTimeStamp.
- -
- The read operation has very specific requirements. On entry, the value referenced by pDataLen indicates the maximum buffer size available at pBuffer. If the amount of data stored by the previous write exceeds this value, the operation must return ERROR. A read must also return ERROR if the saved timestamp value is 0. Finally, the read operation must return ERROR if it is unable to retrieve all the data stored by the write operation or if the previous write was unsuccessful.
- DHCP_CACHE_ERASE
- Ignore all stored data. Following this operation, subsequent read operations must return ERROR until new data is written. All parameters except command are NULL.
OK, always.
N/A
dhcpcCacheHookDelete( ) - delete a lease data storage routine
STATUS dhcpcCacheHookDelete (void)
This routine deletes the hook used to store lease data, preventing re-use of the configuration parameters across system reboots for all subsequent lease attempts. Currently active leases will continue to use the routine specified before the lease initialization.
OK, always.
N/A
dhcpcBind( ) - obtain a set of network configuration parameters with DHCP
STATUS dhcpcBind ( void * pCookie, /* identifier returned by dhcpcInit() */ BOOL syncFlag /* synchronous or asynchronous execution */ )
This routine initiates a DHCP negotiation according to the process described in RFC 1541. The pCookie argument contains the return value of an earlier dhcpcInit( ) call and is used to identify a particular lease.
The syncFlag parameter specifies whether the DHCP negotiation started by this routine will execute synchronously or asynchronously. An asynchronous execution will return after starting the DHCP negotiation, but a synchronous execution will only return once the negotiation process completes.
When a new lease is established, any event hook provided for the lease will be called to process the configuration parameters. The hook is also called when the lease expires or the negotiation process fails. The results of an asynchronous DHCP negotiation are not available unless an event hook is installed.
If automatic configuration of the underlying network interface was specified during the lease initialization, this routine will prevent all higher-level protocols from accessing the underlying network interface used during the initial lease negotiation until that process is complete. In addition, any addressing information obtained will be applied to that network interface, which will remain disabled if the initial negotiation fails. Finally, the interface will be disabled if the lease expires.
If the DHCP client is used to obtain the VxWorks boot parameters, this routine is called automatically during system startup using the automatic reconfiguration. Therefore, any calls to this routine which use the network boot device for message transfer when the DHCP client was used at boot time must not request automatic reconfiguration during initialization. Otherwise, the resulting lease settings will conflict with the configuration maintained by the lease established during system startup.
OK if routine completes, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_BAD_OPTION
dhcpcVerify( ) - renew an established lease
STATUS dhcpcVerify ( void * pCookie /* identifier returned by dhcpcInit() */ )
This routine schedules the lease identified by the pCookie parameter for immediate renewal according to the process described in RFC 1541. If the renewal is unsuccessful, the lease negotiation process restarts. The routine is valid as long as the lease is currently active. The routine is also called automatically in response to a dhcpcBind( ) call for an existing lease.
This routine is only intended for active leases obtained with the dhcpcBind( ) routine. It should not be used for parameters resulting from the dhcpcInformGet( ) routine.
This routine will disable the underlying network interface if the verification fails and automatic configuration was requested. This may occur without warning if no event hook is installed.
OK if verification scheduled, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_NOT_BOUND
dhcpcRelease( ) - relinquish specified lease
STATUS dhcpcRelease ( void * pCookie /* identifier returned by dhcpcInit() */ )
This routine schedules the lease identified by the pCookie parameter for immediate release, regardless of time remaining, and removes all the associated data structures. After the release completes, a new call to dhcpcInit( ) is required before attempting another lease.
This routine will disable the underlying network interface if automatic configuration was requested. This may occur without warning if no event hook is installed.
OK if release scheduled, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED
dhcpcInformGet( ) - obtain additional configuration parameters with DHCP
STATUS dhcpcInformGet ( void * pCookie, /* identifier returned by dhcpcInit() */ char * pAddrString, /* known address assigned to client */ BOOL syncFlag /* synchronous or asynchronous execution? */ )
This routine uses DHCP to retrieve additional configuration parameters for a client with the externally configured network address given by the pAddrString parameter. It sends an INFORM message and waits for a reply following the process described in RFC 2131. The pCookie argument contains the return value of an earlier dhcpcInit( ) call and is used to access the resulting configuration. Unlike the dhcpcBind( ) call, this routine does not establish a lease with a server.
The syncFlag parameter specifies whether the message exchange started by this routine will execute synchronously or asynchronously. An asynchronous execution will return after sending the initial message, but a synchronous execution will only return once the process completes.
When a server responds with an acknowledgement message, any event hook provided will be called to process the configuration parameters. The hook is also called if the message exchange fails. The results of an asynchronous execution are not available unless an event hook is installed.
This routine is designed as an alternative to the dhcpcBind( ) routine. It should not be used for any dhcpcInit( ) identifer corresponding to an active or pending lease.
OK if routine completes, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_BAD_OPTION
dhcpcShutdown( ) - disable DHCP client library
STATUS dhcpcShutdown (void)
This routine schedules the lease monitor task to clean up memory and exit, after releasing all currently active leases. The network boot device will be disabled if the DHCP client was used to obtain the VxWorks boot parameters and the resulting lease is still active. Any other interfaces using the addressing information from leases set for automatic configuration will also be disabled. Notification of a disabled interface will not occur unless an event hook has been installed. After the processing started by this request completes, the DHCP client library is unavailable until restarted with the dhcpcLibInit( ) routine.
OK if shutdown scheduled, or ERROR otherwise.
S_dhcpcLib_NOT_INITIALIZED
dhcpcOptionGet( ) - retrieve an option provided to a client and store in a buffer
STATUS dhcpcOptionGet ( void * pCookie, /* identifier returned by dhcpcInit() */ int option, /* RFC 2132 option tag */ int * pLength, /* size of provided buffer and data returned */ char * pBuf /* location for option data */ )
This routine retrieves the data for a specified option from a lease indicated by the pCookie parameter. The option parameter specifies an option tag as defined in RFC 2132. See the dhcp/dhcp.h include file for a listing of defined aliases for the available option tags. This routine will not accept the following option values, which are either used by the server for control purposes or only supplied by the client:
_DHCP_PAD_TAG
_DHCP_REQUEST_IPADDR_TAG
_DHCP_OPT_OVERLOAD_TAG
_DHCP_MSGTYPE_TAG
_DHCP_REQ_LIST_TAG
_DHCP_MAXMSGSIZE_TAG
_DHCP_CLASS_ID_TAG
_DHCP_CLIENT_ID_TAG
_DHCP_END_TAGIf the option is found, the data is stored in the provided buffer, up to the limit specified in the pLength parameter. The option is not available if the DHCP client is not in the bound state or if the server did not provide it. After returning, the pLength parameter indicates the amount of data actually retrieved. The provided buffer may contain IP addresses stored in network byte order. All other numeric values are stored in host byte order. See RFC 2132 for specific details on the data retrieved.
OK if option available, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_NOT_BOUND,
S_dhcpcLib_OPTION_NOT_PRESENT
dhcpcLib, dhcpcOptionSet( )
dhcpcServerGet( ) - retrieve the current DHCP server
STATUS dhcpcServerGet ( void * pCookie, /* identifier returned by dhcpcInit() */ struct in_addr * pServerAddr /* location for address of server */ )
This routine returns the DHCP server that supplied the configuration parameters for the lease specified by the pCookie argument. This information is available only if the lease is in the bound state.
OK if in bound state and server available, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_NOT_BOUND
dhcpcTimerGet( ) - retrieve current lease timers
STATUS dhcpcTimerGet ( void * pCookie, /* identifier returned by dhcpcInit() */ int * pT1, /* time until lease renewal */ int * pT2 /* time until lease rebinding */ )
This routine returns the number of clock ticks remaining on the timers governing the DHCP lease specified by the pCookie argument. This information is only available if the lease is in the bound state. Therefore, this routine will return ERROR if a BOOTP reply was accepted.
OK if in bound state and values available, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_NOT_BOUND,
S_dhcpcLib_OPTION_NOT_PRESENT, S_dhcpcLib_TIMER_ERROR
dhcpcParamsGet( ) - retrieve current configuration parameters
STATUS dhcpcParamsGet ( void * pCookie, /* identifier returned by dhcpcInit() */ struct dhcp_param * pParamList /* requested parameters */ )
This routine copies the current configuration parameters for the lease specified by the pCookie argument to the user-supplied and allocated dhcp_param structure referenced in pParamList. Within this structure, defined in h/dhcp/dhcpc.h, you should supply buffer pointers for the parameters that interest you. Set all other structure members to zero. When dhcpcParamsGet( ) returns, the buffers you specified in the submitted dhcpc_param structure will contain the information you requested. This assumes that the specified lease is in the bound state and that DHCP knows that the lease parameters are good.
The temp_sname and temp_file members of the dhcp_param structure are for internal use only. They reference temporary buffers for options that are passed using the sname and file members. Do not request either temp_sname or temp_file. Instead, request either sname or file if you want those parameters.
Many of the parameters within the user-supplied structure use one of the following secondary data types: struct in_addrs, struct u_shorts, and struct vendor_list. Each of those structures accepts a length designation and a data pointer. For the first two data types, the num member indicates the size of the buffer in terms of the number of underlying elements. For example, the STATIC_ROUTE option returns one or more IP address pairs. Thus, setting the num member to 2 in the static_route entry would indicate that the corresponding buffer contained 16 bytes. By contrast, the len member in the struct vendor_list data type consists of the buffer size, in bytes. See RFC 1533 for specific details on the types of data for each option.
On return, each of the length designators are set to indicate the amount of data returned. For instance, the num member in the static_route entry could be set to 1 to indicate that only one IP address pair of 8 bytes was available.
OK if in bound state, or ERROR otherwise.
S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_NOT_BOUND