dhcpclib.html

Vxworks API操作系统和驱动程序设计API。压缩的HTML文件

<b>S_dhcpcLib_BAD_COOKIE</b>, <b>S_dhcpcLib_NOT_INITIALIZED</b>
</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.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>dhcpcEventHookDelete(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>dhcpcEventHookDelete(&nbsp;)</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 the
corresponding network interface, the assigned address could change
without warning after this routine is executed.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK if notification hook removed, or ERROR otherwise.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
<b>S_dhcpcLib_BAD_COOKIE</b>, <b>S_dhcpcLib_NOT_INITIALIZED</b>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>

<hr>
<a name="dhcpcCacheHookAdd"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>dhcpcCacheHookAdd(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>dhcpcCacheHookAdd(&nbsp;)</strong> - add a routine to store and retrieve lease data</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS dhcpcCacheHookAdd
    (
    FUNCPTR pCacheHookRtn     /* routine to store/retrieve lease data */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine adds a hook routine that is called at the bound state
(to store the lease data) and during the <b>INIT_REBOOT</b> state (to re-use the
parameters if the lease is still active).  The calling sequence of the 
input hook routine is:
<pre>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 */
    )

</pre>
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.
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
The setting of the cache hook routine during a <b><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a>(&nbsp;)</b> 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 <b><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a>(&nbsp;)</b>
call for each lease which will re-use its parameters across reboots.
<p>
</blockquote><h4>IMPLEMENTATION</h4><blockquote><p>
The <i>command</i> parameter specifies one of the following operations:
<dl>
<dt>
<b>DHCP_CACHE_WRITE</b>
<dd>
Save the indicated data.  The write operation must preserve the value
referenced by <i>pTimeStamp</i> and the contents of <i>pBuffer</i>.  The <i>pDataLen</i> 
parameter indicates the number of bytes in that buffer.
<dt>
<b>DHCP_CACHE_READ</b>
<dd>
Restore the saved data.  The read operation must copy the data from the
most recent write operation into the location indicated by <i>pBuffer</i>,
set the contents of <i>pDataLen</i> to the amount of data provided, and store 
the corresponding timestamp value in <i>pTimeStamp</i>.
<dt>
-
<dd>
The read operation has very specific requirements.  On entry, the value 
referenced by <i>pDataLen</i> indicates the maximum buffer size available at
<i>pBuffer</i>.  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.
<dt>
<b>DHCP_CACHE_ERASE</b>
<dd>
Ignore all stored data.  Following this operation, subsequent read operations
must return ERROR until new data is written.  All parameters except 
<i>command</i> are NULL.
</dl>

<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, always.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
N/A
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>

<hr>
<a name="dhcpcCacheHookDelete"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>dhcpcCacheHookDelete(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>dhcpcCacheHookDelete(&nbsp;)</strong> - delete a lease data storage routine</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS dhcpcCacheHookDelete (void)</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, always.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
N/A
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>

<hr>
<a name="dhcpcBind"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>dhcpcBind(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>dhcpcBind(&nbsp;)</strong> - obtain a set of network configuration parameters with DHCP</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS dhcpcBind
    (
    void * pCookie,           /* identifier returned by dhcpcInit() */
    BOOL   syncFlag           /* synchronous or asynchronous execution */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine initiates a DHCP negotiation according to the process described 
in RFC 1541.  The <i>pCookie</i> argument contains the return value of an earlier 
<b><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a>(&nbsp;)</b> call and is used to identify a particular lease.
<p>
The <i>syncFlag</i> 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.
<p>
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.
<p>
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.
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
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. 
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK if routine completes, or ERROR otherwise.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
<b>S_dhcpcLib_BAD_COOKIE</b>, <b>S_dhcpcLib_NOT_INITIALIZED</b>, <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<b>S_dhcpcLib_BAD_OPTION</b>,&nbsp;<b>S_dhcpcLib_BAD_DEVICE</b>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>

<hr>
<a name="dhcpcVerify"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>dhcpcVerify(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>dhcpcVerify(&nbsp;)</strong> - renew an established lease</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS dhcpcVerify
    (
    void * pCookie            /* identifier returned by dhcpcInit() */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine schedules the lease identified by the <i>pCookie</i> 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 <b><a href="./dhcpcLib.html#dhcpcBind">dhcpcBind</a>(&nbsp;)</b> call
for an existing lease.
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
This routine is only intended for active leases obtained with the
<b><a href="./dhcpcLib.html#dhcpcBind">dhcpcBind</a>(&nbsp;)</b> routine. It should not be used for parameters resulting
from the <b><a href="./dhcpcLib.html#dhcpcInformGet">dhcpcInformGet</a>(&nbsp;)</b> routine.
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
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.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK if verification scheduled, or ERROR otherwise.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
<b>S_dhcpcLib_BAD_COOKIE</b>, <b>S_dhcpcLib_NOT_INITIALIZED</b>, <b>S_dhcpcLib_NOT_BOUND</b>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./dhcpcLib.html#top">dhcpcLib</a></b>

<hr>
<a name="dhcpcRelease"></a>
<p align=right>
<a href="rtnIndex.htm"><i>OS Libraries :  Routines</i></a></p>

</blockquote><h1>dhcpcRelease(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong>dhcpcRelease(&nbsp;)</strong> - relinquish specified lease</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS dhcpcRelease
    (
    void * pCookie            /* identifier returned by dhcpcInit() */
    )
</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine schedules the lease identified by the <i>pCookie</i> parameter
for immediate release, regardless of time remaining, and removes all
the associated data structures.  After the release completes, a new
call to <b><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a>(&nbsp;)</b> is required before attempting another lease.
<p>
</blockquote><h4>NOTE</h4><blockquote><p>
This routine will disable the underlying network interface if automatic 
configuration was requested.  This may occur without warning if no event 
hook is installed.