dhcpclib.html

vxworks相关论文

OK if notification hook removed, 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="dhcpcCacheHookAdd"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>dhcpcCacheHookAdd</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>dhcpcCacheHookAdd</i>(&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><i><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a></i>(&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><i><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a></i>(&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.
<p>
<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>.
<p>
<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.
<p>
<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.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>dhcpcCacheHookDelete</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>dhcpcCacheHookDelete</i>(&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="dhcpcOptionSet"></a>
<p align=right>
<a href="rtnIndex.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>dhcpcOptionSet</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>dhcpcOptionSet</i>(&nbsp;)</strong> - add an option to the option request list</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS dhcpcOptionSet
    (
    void * pCookie, /* identifier returned by dhcpcInit() */
    int    option,  /* RFC 1533 tag of desired option */
    long   value,   /* numeric value for option */
    long   length,  /* length of data (if any) or 0 if unused */
    char * pData    /* option data, or NULL if none */
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine sets most client-to-server transmission options for the lease 
indicated by the <i>pCookie</i> parameter.  The <i>option</i> parameter specifies an 
option tag as defined in RFC 1533 and the updates published in the Internet 
Draft of November 1996.   For a listing of defined aliases for the known 
option tags, see <b>dhcp/dhcp.h</b>.  This routine cannot set the options associated 
with the following tags: 
<p>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_PAD_TAG</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_OPT_OVERLOAD_TAG</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_MSGTYPE_TAG</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_SERVER_ID_TAG</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_REQ_LIST_TAG</b>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_MAXMSGSIZE_TAG</b><br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_END_TAG</b>
<p>
Most options only require specification of the appropriate tag in the 
<i>option</i> parameter.  In those cases, the <b><i><a href="./dhcpcLib.html#dhcpcOptionSet">dhcpcOptionSet</a></i>(&nbsp;)</b> call adds the 
specified option tag to the option request list, if possible.  However, some 
options require additional information.  The tags for these options are: 
<p>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_VENDOR_SPEC_TAG</b>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_REQUEST_IPADDR_TAG</b>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_LEASE_TIME_TAG</b>&nbsp;&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_ERRMSG_TAG</b>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_CLASS_ID_TAG</b>&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;<b>_DHCP_CLIENT_ID_TAG</b>&nbsp;
<p>
The <b>_DHCP_LEASE_TIME_TAG</b> and <b>_DHCP_CLIENT_ID_TAG</b> options each use the
<i>value</i> parameter.  For <b>_DHCP_LEASE_TIME_TAG</b>, <i>value</i> specifies the desired 
lease length.  For <b>_DHCP_CLIENT_ID_TAG</b>, <i>value</i> specifies the type for a 
type/value pair.  No other options use this parameter.
<p>
The <b>_DHCP_VENDOR_SPEC_TAG</b>, <b>_DHCP_CLASS_ID_TAG</b> and <b>_DHCP_CLIENT_ID_TAG</b>
tags each require a value for the <i>length</i> parameter to specify the number 
of bytes of data provided.  No other options use this parameter.
<p>
The <i>pData</i> parameter is relevant to the following option tags:
<dl>
<dt>
<b>_DHCP_VENDOR_SPEC_TAG</b>
<dd>

The <i>pData</i> parameter references a list of <i>length</i> bytes of options 
in the format specified by RFC 1533. 
<p>
<dt>
<b>_DHCP_REQUEST_IPADDR_TAG</b>
<dd>

The <i>pData</i> parameter indicates the string representation of the 
desired Internet address for the client in dot notation.
<p>
<dt>
<b>_DHCP_ERRMSG_TAG</b>
<dd>

The <i>pData</i> parameter indicates the error message to send to the server 
when releasing the current IP address.  That location must be valid until
the release is completed, since the message is not copied or stored in 
any way.
<p>
<dt>
<b>_DHCP_CLASS_ID_TAG</b>
<dd>

The <i>pData</i> parameter references <i>length</i> bytes used as the value 
for the vendor class identifier.
<p>
<dt>
<b>_DHCP_CLIENT_ID_TAG</b>
<dd>

The <i>pData</i> parameter references <i>length</i> bytes used as the value 
of a type/value pair.
<p>
<dt>
-
<dd>
 The <i>pData</i> parameter is not used by any other options. 
</dl>

<p>

</blockquote><h4>NOTE</h4><blockquote><p>
With the exception of the <b>_DHCP_ERRMSG_TAG</b> option, the DHCP 
specification forbids changing options after a lease has been 
established.  Therefore, this routine should not be used after the 
<b><i><a href="./dhcpcLib.html#dhcpcBind">dhcpcBind</a></i>(&nbsp;)</b> call.  Changing any option other than the error message at
that point could have unpredictable results.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK if the option was set successfully, or ERROR if the option
is invalid or storage failed.
<p>
</blockquote><h4>ERRNO</h4><blockquote><p>
S_dhcpcLib_BAD_OPTION, S_dhcpcLib_OPTION_NOT_STORED
</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.html"><i>Libraries :  Routines</i></a></p>

</blockquote><h1><i>dhcpcBind</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>dhcpcBind</i>(&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><i><a href="./dhcpcLib.html#dhcpcInit">dhcpcInit</a></i>(&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