<div class="content" name="R_DhcpEnumSubnetClientsV5" uuid="025ce935-8585-42b5-abfe-326e621de361"><p>The <b>R_DhcpEnumSubnetClientsV5</b> method is used to
retrieve all <a href="a9d6a415-4de6-4058-befe-ca2e42764485#gt_c35fc04f-54fe-4570-afd3-c96ca84c8d83" data-linktype="relative-path">DHCPv4 clients</a>
serviced from the specified IPv4 subnet. This method returns DHCPv4 clients
from all IPv4 subnets if the subnet address specified zero. The caller of this
function can free the memory pointed to by the <i>ClientInfo</i> parameter and
its <b>Clients</b> member by calling the function <b>midl_user_free</b> (see
section <a href="a7e5f2d1-04b7-4363-bdc0-76a1099664eb" data-linktype="relative-path">3</a>).</p><dl>
<dd>
<div><pre> DWORD R_DhcpEnumSubnetClientsV5(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_CLIENT_INFO_ARRAY_V5* ClientInfo,
   [out] DWORD* ClientsRead,
   [out] DWORD* ClientsTotal
 );
</pre></div>
</dd></dl><p><b>ServerIpAddress: </b>The IP address/host name of
the DHCP server. This parameter is unused.</p><p><b>SubnetAddress: </b>This is of <a href="5122557b-b85d-4982-8ffb-98d8d934e353" data-linktype="relative-path">DHCP_IP_ADDRESS (section 2.2.1.2.1)</a>,
containing the IPv4 <a href="a9d6a415-4de6-4058-befe-ca2e42764485#gt_e6a800ef-fd8a-4d87-834c-131e58f304ea" data-linktype="relative-path">subnet
ID</a> from which DHCPv4 clients are enumerated. If this parameter is set to 0,
the DHCPv4 clients from all the IPv4 subnets are returned.</p><p><b>ResumeHandle: </b>This is a pointer of type <a href="a6e4cdc0-4f71-4922-ade1-7a5392f9e920" data-linktype="relative-path">DHCP_RESUME_HANDLE (section 2.2.1.2.6)</a>
that identifies the enumeration operation. Initially, this value MUST be set to
zero, with a successful call returning the handle value used for subsequent
enumeration requests. This parameter contains the last IPv4 address retrieved.</p><p><b>PreferredMaximum: </b>This is of type <a href="../ms-dtyp/262627d8-3418-4627-9218-4ffe110850b2" data-linktype="relative-path">DWORD</a>,
specifying the preferred maximum number of bytes to return. The minimum value is
1,024 bytes (1 kilobyte), and the maximum value is 65,536 bytes (64 kilobytes).
If the input value is greater or less than this range, it MUST be set to the
maximum or minimum value, respectively. To retrieve all the DHCPv4 clients
serviced by a specific IPv4 subnet, 0xFFFFFFFF is specified.</p><p><b>ClientInfo: </b>This is a pointer of type <b>LPDHCP_CLIENT_INFO_ARRAY_V5</b>
(section <a href="de354c76-2e46-4662-ada5-3fb5ba14f259" data-linktype="relative-path">2.2.1.2.17</a>)
that points to the location that contains the DHCPv4 client lease record array.</p><p><b>ClientsRead: </b>This is a pointer to a DWORD that
specifies the number of DHCPv4 client lease records read in the <i>ClientInfo</i>
parameter. The caller MUST allocate memory for this parameter equal to the size
of data type DWORD.</p><p><b>ClientsTotal: </b>This is a pointer to a DWORD
that specifies the number of DHCPv4 client lease records remaining from the
current position. For example, if there are 100 DHCPv4 lease record clients for
an IPv4 subnet, and if 10 DHCPv4 lease records are enumerated per call, for the
first time this would have a value of 90.<a id="Appendix_A_Target_45"></a><a aria-label="Product behavior note 45" href="afab0546-79ae-4764-8dab-27a85cca5145#Appendix_A_45" data-linktype="relative-path">&lt;45&gt;</a> The
caller MUST allocate memory for this parameter equal to the size of data type
DWORD.</p><p><b>Return Values: </b>A 32-bit unsigned integer value
that indicates return status. A return value of ERROR_SUCCESS (0x00000000)
indicates that the operation was completed successfully, else it contains a
Win32 error code, as specified in <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>.
This error code value can correspond to a DHCP-specific failure, which takes a
value between 20000 and 20099, or any generic failure.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 ERROR_SUCCESS</td>
  <td>The call was successful.</td>
 </tr><tr>
  <td>0x000000EA ERROR_MORE_DATA</td>
  <td>There are more elements available to enumerate.</td>
 </tr><tr>
  <td>0x00000103 ERROR_NO_MORE_ITEMS</td>
  <td>There are no more elements left to enumerate.</td>
 </tr><tr>
  <td>0x00004E2D ERROR_DHCP_JET_ERROR</td>
  <td>An error occurred while accessing the DHCP server database.</td>
 </tr></tbody></table>
</dd></dl><p>The opnum field value for this method is 0.</p><p>When processing this call, the DHCP server MUST do the
following:</p><ul><li><p><span><span> 
</span></span>Validate that this method is authorized for read access per
section <a href="baec2112-1146-4c42-b77e-b706e170a590" data-linktype="relative-path">3.5.4</a>. If not,
return ERROR_ACCESS_DENIED.</p>
</li><li><p><span><span> 
</span></span>Retrieve the <b>DHCPv4ClientsList</b> ADM element member of the <b>DHCPv4Scope</b>
ADM element entry corresponding to the <i>SubnetAddress</i> parameter from the
server ADM element <b>DHCPv4ScopesList</b>. If the <i>SubnetAddress</i>
parameter is zero, retrieve the <b>DHCPv4ClientsList</b> ADM element member
from all the <b>DHCPv4Scope</b> ADM element entries in the server ADM element <b>DHCPv4ScopesList</b>.</p>
</li><li><p><span><span> 
</span></span>If the <i>ResumeHandle</i> parameter points to 0x00000000, the
enumeration MUST start from the first entry of <b>DHCPv4ClientsList</b>.</p>
</li><li><p><span><span> 
</span></span>If the <i>ResumeHandle</i> parameter points to 0x00000000 and
there are no entries in the <b>DHCPv4ClientsList</b> ADM element of all the <b>DHCPv4Scope</b>
ADM element entries present in the <b>DHCPv4ScopesList</b> ADM element, then
return ERROR_NO_MORE_ITEMS. If there are no entries in the <b>DHCPv4ClientsList</b>
ADM element of the <b>DHCPv4Scope</b> ADM element entry corresponding to the <i>SubnetAddress</i>
parameter, the <b>DHCPv4Client</b> ADM element entry in the <b>DHCPv4ClientsList</b>
ADM element, or other <b>DHCPv4Scope</b> ADM element entries configured on the
server, then return ERROR_NO_MORE_ITEMS.<a id="Appendix_A_Target_46"></a><a aria-label="Product behavior note 46" href="afab0546-79ae-4764-8dab-27a85cca5145#Appendix_A_46" data-linktype="relative-path">&lt;46&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the <i>ResumeHandle</i> parameter points to a nonzero value,
the server MUST continue enumeration based on the value of the <i>ResumeHandle</i>
parameter. If the IPv4 Address contained in the <i>ResumeHandle</i> parameter
value does not match a <b>ClientIpAddress</b> ADM element of any <b>DHCPv4Client</b>
ADM element of the <b>DHCPv4Scope</b> ADM element object entry corresponding to
the <i>SubnetAddress</i> parameter, or <b>ClientIpAddress</b> ADM element of any
<b>DHCPv4Client</b> ADM element of all <b>DHCPv4Scope</b> ADM element entries
when the specified <i>SubnetAddress</i> parameter value is 0x0, then return
ERROR_DHCP_JET_ERROR.</p>
</li><li><p><span><span> 
</span></span>The <i>PreferredMaximum</i> parameter specifies the maximum
number of bytes that the server can allocate and return to the caller
containing the data related to the DHCPv4 client lease records.</p>
</li><li><p><span><span> 
</span></span>If <i>PreferredMaximum</i> is less than 1024, it is assigned
1024, and if <i>PreferredMaximum</i> is greater than 65536, it is assigned
65536.</p>
</li><li><p><span><span> 
</span></span>The actual number of records that corresponds to a given <i>PreferredMaximum</i>
value can be determined only at runtime.</p>
</li><li><p><span><span> 
</span></span>Allocate memory for <i>PreferredMaximum</i> number of bytes.</p>
</li><li><p><span><span> 
</span></span>Copy the <b>DHCPv4Client</b> ADM element entry from the <b>DHCPv4ClientsList</b>
ADM element entries corresponding to the <i>SubnetAddress</i> parameter in the
allocated memory, and then proceed to the next record. If the <i>SubnetAddress</i>
parameter is 0, copy the <b>DHCPv4Client</b> ADM element entry from all <b>DHCPv4ClientsList</b>
members of all the <b>DHCPv4Scope</b> ADM element entries in the server ADM
element <b>DHCPv4ScopesList</b>.</p>
</li><li><p><span><span> 
</span></span>If the retrieve operation has reached the maximum number of <b>DHCPv4Client</b>
ADM element entries that can be accommodated in the <i>PreferredMaximum</i>
parameter, and there are still more <b>DHCPv4Client</b> ADM element entries in <b>DHCPv4ClientsList</b>
ADM element entries, set the <i>ClientsTotal</i> parameter to the number of <b>DHCPv4Client</b>
ADM element entries that are not yet enumerated, and set the <i>ClientsRead</i>
parameter as well as the <b>NumElements</b> member of the <i>ClientInfo</i>
parameter to the number of <b>DHCPv4Client</b> ADM element entries that are
enumerated in this retrieve operation. Set the <i>ResumeHandle</i> parameter to
the <b>ClientIpAddress</b> ADM element member of the last <b>DHCPv4Client</b>
ADM element entry read, and return ERROR_MORE_DATA.</p>
</li><li><p><span><span> 
</span></span>If the number of bytes specified by the <i>PreferredMaximum</i>
parameter is more than the total memory occupied by the DHCPv4 client lease
record on the DHCPv4 server available in the DHCPv4 server database, update the
<i>ClientsTotal</i> parameter to the total number of DHCPv4 client lease
records enumerated in that retrieve operation, and also update the <i>ClientsRead</i>
parameter and the <b>NumElements</b> member of the <i>ClientInfo</i> parameter
to the number of DHCPv4 client lease records that are enumerated in this
retrieve operation. Update the <i>ResumeHandle</i> parameter to 0, and return
ERROR_SUCCESS.</p>
</li></ul><p><b>Exceptions Thrown:</b> No exceptions SHOULD be thrown
beyond those thrown by the underlying RPC protocol specified in <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>.</p></div>