📄 dhcpclib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/dhcpcLib.html - generated by refgen from dhcpcLib.c --> <title> dhcpcLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>VxWorks Reference Manual : Libraries</i></a></p></blockquote><h1>dhcpcLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>dhcpcLib</strong> - Dynamic Host Configuration Protocol (DHCP) run-time client API </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><i><a href="./dhcpcLib.html#dhcpcLibInit">dhcpcLibInit</a></i>( )</b> - DHCP client library initialization<br><b><i><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a></i>( )</b> - assign network interface and setup lease request<br><b><i><a href="./dhcpcLib.html#dhcpcEventHookAdd">dhcpcEventHookAdd</a></i>( )</b> - add a routine to handle configuration parameters<br><b><i><a href="./dhcpcLib.html#dhcpcEventHookDelete">dhcpcEventHookDelete</a></i>( )</b> - remove the configuration parameters handler<br><b><i><a href="./dhcpcLib.html#dhcpcCacheHookAdd">dhcpcCacheHookAdd</a></i>( )</b> - add a routine to store and retrieve lease data<br><b><i><a href="./dhcpcLib.html#dhcpcCacheHookDelete">dhcpcCacheHookDelete</a></i>( )</b> - delete a lease data storage routine<br><b><i><a href="./dhcpcLib.html#dhcpcOptionSet">dhcpcOptionSet</a></i>( )</b> - add an option to the option request list<br><b><i><a href="./dhcpcLib.html#dhcpcBind">dhcpcBind</a></i>( )</b> - obtain a set of network configuration parameters with DHCP<br><b><i><a href="./dhcpcLib.html#dhcpcVerify">dhcpcVerify</a></i>( )</b> - renew an established lease<br><b><i><a href="./dhcpcLib.html#dhcpcRelease">dhcpcRelease</a></i>( )</b> - relinquish specified lease<br><b><i><a href="./dhcpcLib.html#dhcpcShutdown">dhcpcShutdown</a></i>( )</b> - disable DHCP client library<br><b><i><a href="./dhcpcLib.html#dhcpcOptionGet">dhcpcOptionGet</a></i>( )</b> - retrieve an option provided to a client and store in a buffer<br><b><i><a href="./dhcpcLib.html#dhcpcServerGet">dhcpcServerGet</a></i>( )</b> - retrieve the current DHCP server<br><b><i><a href="./dhcpcLib.html#dhcpcTimerGet">dhcpcTimerGet</a></i>( )</b> - retrieve current lease timers<br><b><i><a href="./dhcpcLib.html#dhcpcParamsGet">dhcpcParamsGet</a></i>( )</b> - retrieve current configuration parameters<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>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 obtainingits IP address, boot file name, and boot host's IP address over a network. Additionally, DHCP provides a client with the complete set of parametersdefined 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 <b><i><a href="./dhcpcLib.html#dhcpcLibInit">dhcpcLibInit</a></i>( )</b> routine links this library into the VxWorks image. This happens automatically if <b>INCLUDE_DHCPC</b> is defined at the time the image is built.<p></blockquote><h4>CONFIGURATION INTERFACE</h4><blockquote><p>When used during run time, the DHCP client library establishes and maintainsone 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 <b><i><a href="./dhcpcLib.html#dhcpcEventHookAdd">dhcpcEventHookAdd</a></i>( )</b> routine specifies a function which is invoked whenever the lease status changes. The <b><i><a href="./dhcpcLib.html#dhcpcEventHookDelete">dhcpcEventHookDelete</a></i>( )</b> 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.<p></blockquote><h4>HIGH-LEVEL INTERFACE</h4><blockquote><p>To access the DHCP client during run time, an application must first call the <b><i><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a></i>( )</b> 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 <b><i><a href="./dhcpcLib.html#dhcpcOptionSet">dhcpcOptionSet</a></i>( )</b> 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 <b><i><a href="./dhcpcLib.html#dhcpcBind">dhcpcBind</a></i>( )</b> will retrieve a set of configuration parameters according to the client-server interaction detailed in RFC 1541.<p>Each sequence of the three function calls described above, if successful,will retrieve a set of configuration parameters from a DHCP server. The<b><i><a href="./dhcpcLib.html#dhcpcServerGet">dhcpcServerGet</a></i>( )</b> routine retrieves the address of the server that provided a particular lease. The <b><i><a href="./dhcpcLib.html#dhcpcTimerGet">dhcpcTimerGet</a></i>( )</b> routine will retrieve the current values for both lease timers. <p>Alternatively, the <b><i><a href="./dhcpcLib.html#dhcpcParamsGet">dhcpcParamsGet</a></i>( )</b> and <b><i><a href="./dhcpcLib.html#dhcpcOptionGet">dhcpcOptionGet</a></i>( )</b> routines will access any options provided by a DHCP server. In addition to the lease identifierobtained from the initialization routine, the <b><i><a href="./dhcpcLib.html#dhcpcParamsGet">dhcpcParamsGet</a></i>( )</b> routine accepts a parameter descriptor structure that selects any combination of the options described in RFC 1533 for retrieval. Similarly, the <b><i><a href="./dhcpcLib.html#dhcpcOptionGet">dhcpcOptionGet</a></i>( )</b> routine retrieves the values associated with a single option.<p></blockquote><h4>LOW-LEVEL INTERFACE</h4><blockquote><p>This library also contains several routines which explicitly generate DHCP messages. The <b><i><a href="./dhcpcLib.html#dhcpcVerify">dhcpcVerify</a></i>( )</b> routine causes the client to renew a particularlease, regardless of the time remaining. The <b><i><a href="./dhcpcLib.html#dhcpcRelease">dhcpcRelease</a></i>( )</b> 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 <b><i><a href="./dhcpcLib.html#dhcpcShutdown">dhcpcShutdown</a></i>( )</b> routine will release all active leases and disable allthe DHCP client library routines.<p></blockquote><h4>OPTIONAL INTERFACE</h4><blockquote><p>The <b><i><a href="./dhcpcLib.html#dhcpcCacheHookAdd">dhcpcCacheHookAdd</a></i>( )</b> routine registers a function that the client willuse to store and retrieve lease data. The client can then re-use this information if it is rebooted. The <b><i><a href="./dhcpcLib.html#dhcpcCacheHookDelete">dhcpcCacheHookDelete</a></i>( )</b> routine prevents the re-use of lease data. Initially, a function to access permanent storage is not provided.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>dhcpcLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>, RFC 1541, RFC 1533<hr><a name="dhcpcLibInit"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>dhcpcLibInit</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>dhcpcLibInit</i>( )</strong> - DHCP client library initialization</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 offerTimeout, /* interval to get additional DHCP offers */ int defaultLease, /* default value for requested lease length */ int minLease /* minimum accepted lease length */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>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 <i>maxLeases</i> parameter. Every subsequent lease attempt willcollect additional DHCP offers until the interval specified by <i>offerTimeout</i>expires and will request the lease duration indicated by <i>defaultLease</i>.This routine must be called before calling any other library routines. The routine is called automatically if <b>INCLUDE_DHCPC</b> is defined at the time the system is built and assigns the global lease settings to the values specifiedby <b>DHCPC_SPORT</b>, <b>DHCPC_CPORT</b>, <b>DHCPC_MAX_LEASES</b>, <b>DHCPC_DEFAULT_LEASE</b>, and <b>DHCPC_OFFER_TIMEOUT</b>.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if initialization fails.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_dhcpcLib_MEM_ERROR</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./dhcpcLib.html#top">dhcpcLib</a></b><hr><a name="dhcpcInit"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>dhcpcInit</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>dhcpcInit</i>( )</strong> - assign network interface and setup lease request</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>void * dhcpcInit ( struct ifnet * pIf, /* network device used by client */ BOOL autoConfig /* reconfigure network device? */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>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 <b><i><a href="./dhcpcLib.html#dhcpcLibInit">dhcpcLibInit</a></i>( )</b> routine has initialized the global datastructures. The <i>pIf</i> argument indicates the network device which will be used for transmission and reception of DHCP messages during the lifetime of the lease. If the <i>autoConfig</i> parameter is set to TRUE, any address information obtained will automatically be applied to that interface. The specified interface must access a device capable of sending broadcast messages. Currently, only Ethernet devices and the shared-memory networkdrivers are supported.<p>The routine also uses the <i>autoConfig</i> parameter to select 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 <b><i><a href="./dhcpcLib.html#dhcpcBind">dhcpcBind</a></i>( )</b> call. If <i>autoConfig</i> 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 <i>pIf</i>.<p>The internal lease identifier returned by this routine must be used insubsequent calls to the DHCP client library.<p></blockquote><h4>NOTE</h4><blockquote><p>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, anyfurther calls to this routine which specify the network boot device for use in obtaining additional DHCP leases must set <i>autoConfig</i> 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.<p></blockquote><h4>RETURNS</h4><blockquote><p>Lease handle for later use, or NULL if lease setup fails.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_dhcpcLib_NOT_INITIALIZED, S_dhcpcLib_NO_DEVICE, S_dhcpcLib_BAD_OPTION,<br> S_dhcpcLib_MAX_LEASES_REACHED, S_dhcpcLib_MEM_ERROR<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>, <b><i><a href="./dhcpcLib.html#dhcpcOptionSet">dhcpcOptionSet</a></i>( )</b>, <b><i><a href="./dhcpcLib.html#dhcpcEventHookAdd">dhcpcEventHookAdd</a></i>( )</b><hr><a name="dhcpcEventHookAdd"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>dhcpcEventHookAdd</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>dhcpcEventHookAdd</i>( )</strong> - add a routine to handle configuration parameters</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS dhcpcEventHookAdd ( void * pCookie, /* identifier returned by dhcpcInit() */ FUNCPTR pEventHook /* routine to handle lease parameters */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine installs a hook routine to handle changes in the configurationparameters provided for the lease indicated by <i>pCookie</i>. The hook provides an alternate configuration method for DHCP leases and uses the following interface:<pre>void dhcpcEventHookRtn ( int leaseEvent, /* new or expired parameters */ void * pCookie /* lease identifier from dhcpcInit() */ )</pre>The routine is called with the <i>leaseEvent</i> parameter set to <b>DHCPC_LEASE_NEW</b>whenever a lease is successfully established. The <b>DHCPC_LEASE_NEW</b> eventdoes not occur when a lease is renewed by the same DHCP server, since theparameters do not change in that case. However, it does occur if the client rebinds to a different DHCP server. The <b>DHCPC_LEASE_INVALID</b> eventindicates that the configuration parameters for the corresponding lease mayno longer be used. That event occurs when a lease expires or a renewalor verification attempt fails, and coincides with re-entry into the initial state of the negotiation process.<p>If the lease initialization specified automatic configuration of thecorresponding network interface, any installed hook routine will be invokedafter the new address information is applied.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK if notification hook added, or ERROR otherwise.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_dhcpcLib_BAD_COOKIE, S_dhcpcLib_NOT_INITIALIZED</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./dhcpcLib.html#top">dhcpcLib</a></b><hr><a name="dhcpcEventHookDelete"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>dhcpcEventHookDelete</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>dhcpcEventHookDelete</i>( )</strong> - remove the configuration parameters handler</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS dhcpcEventHookDelete ( void * pCookie /* identifier returned by dhcpcInit() */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine removes the hook routine that handled changes in the configuration parameters for the lease indicated by <i>pCookie</i>.If the lease initialization specified automatic configuration of thecorresponding network interface, the assigned address could changewithout warning after this routine is executed.<p></blockquote><h4>RETURNS</h4><blockquote><p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -