The R_DhcpEnumSubnetClientsV5 method is used to retrieve all DHCPv4 clients 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 ClientInfo parameter and its Clients member by calling the function midl_user_free (see section 3).

 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
 );

ServerIpAddress: The IP address/host name of the DHCP server. This parameter is unused.

SubnetAddress: This is of DHCP_IP_ADDRESS (section 2.2.1.2.1), containing the IPv4 subnet ID from which DHCPv4 clients are enumerated. If this parameter is set to 0, the DHCPv4 clients from all the IPv4 subnets are returned.

ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (section 2.2.1.2.6) 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.

PreferredMaximum: This is of type DWORD, 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.

ClientInfo: This is a pointer of type LPDHCP_CLIENT_INFO_ARRAY_V5 (section 2.2.1.2.17) that points to the location that contains the DHCPv4 client lease record array.

ClientsRead: This is a pointer to a DWORD that specifies the number of DHCPv4 client lease records read in the ClientInfo parameter. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

ClientsTotal: 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.<45> The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

Return Values: 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 [MS-ERREF]. This error code value can correspond to a DHCP-specific failure, which takes a value between 20000 and 20099, or any generic failure.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The call was successful.
0x000000EA ERROR_MORE_DATA	There are more elements available to enumerate.
0x00000103 ERROR_NO_MORE_ITEMS	There are no more elements left to enumerate.
0x00004E2D ERROR_DHCP_JET_ERROR	An error occurred while accessing the DHCP server database.

The opnum field value for this method is 0.

When processing this call, the DHCP server MUST do the following:

• Validate that this method is authorized for read access per section 3.5.4. If not, return ERROR_ACCESS_DENIED.

• Retrieve the DHCPv4ClientsList ADM element member of the DHCPv4Scope ADM element entry corresponding to the SubnetAddress parameter from the server ADM element DHCPv4ScopesList. If the SubnetAddress parameter is zero, retrieve the DHCPv4ClientsList ADM element member from all the DHCPv4Scope ADM element entries in the server ADM element DHCPv4ScopesList.

• If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of DHCPv4ClientsList.

• If the ResumeHandle parameter points to 0x00000000 and there are no entries in the DHCPv4ClientsList ADM element of all the DHCPv4Scope ADM element entries present in the DHCPv4ScopesList ADM element, then return ERROR_NO_MORE_ITEMS. If there are no entries in the DHCPv4ClientsList ADM element of the DHCPv4Scope ADM element entry corresponding to the SubnetAddress parameter, the DHCPv4Client ADM element entry in the DHCPv4ClientsList ADM element, or other DHCPv4Scope ADM element entries configured on the server, then return ERROR_NO_MORE_ITEMS.<46>

• If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of the ResumeHandle parameter. If the IPv4 Address contained in the ResumeHandle parameter value does not match a ClientIpAddress ADM element of any DHCPv4Client ADM element of the DHCPv4Scope ADM element object entry corresponding to the SubnetAddress parameter, or ClientIpAddress ADM element of any DHCPv4Client ADM element of all DHCPv4Scope ADM element entries when the specified SubnetAddress parameter value is 0x0, then return ERROR_DHCP_JET_ERROR.

• The PreferredMaximum 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.

• If PreferredMaximum is less than 1024, it is assigned 1024, and if PreferredMaximum is greater than 65536, it is assigned 65536.

• The actual number of records that corresponds to a given PreferredMaximum value can be determined only at runtime.

• Allocate memory for PreferredMaximum number of bytes.

• Copy the DHCPv4Client ADM element entry from the DHCPv4ClientsList ADM element entries corresponding to the SubnetAddress parameter in the allocated memory, and then proceed to the next record. If the SubnetAddress parameter is 0, copy the DHCPv4Client ADM element entry from all DHCPv4ClientsList members of all the DHCPv4Scope ADM element entries in the server ADM element DHCPv4ScopesList.

• If the retrieve operation has reached the maximum number of DHCPv4Client ADM element entries that can be accommodated in the PreferredMaximum parameter, and there are still more DHCPv4Client ADM element entries in DHCPv4ClientsList ADM element entries, set the ClientsTotal parameter to the number of DHCPv4Client ADM element entries that are not yet enumerated, and set the ClientsRead parameter as well as the NumElements member of the ClientInfo parameter to the number of DHCPv4Client ADM element entries that are enumerated in this retrieve operation. Set the ResumeHandle parameter to the ClientIpAddress ADM element member of the last DHCPv4Client ADM element entry read, and return ERROR_MORE_DATA.

• If the number of bytes specified by the PreferredMaximum 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 ClientsTotal parameter to the total number of DHCPv4 client lease records enumerated in that retrieve operation, and also update the ClientsRead parameter and the NumElements member of the ClientInfo parameter to the number of DHCPv4 client lease records that are enumerated in this retrieve operation. Update the ResumeHandle parameter to 0, and return ERROR_SUCCESS.

Exceptions Thrown: No exceptions SHOULD be thrown beyond those thrown by the underlying RPC protocol specified in [MS-RPCE].