3.2.4.116 R_DhcpV4EnumSubnetClients (Opnum 115)

The R_DhcpV4EnumSubnetClients method is used to retrieve all DHCPv4 clients serviced on the specified IPv4 subnet. The information also includes the link-layer filter status info for the DHCPv4 client and the policy, if any, that resulted in the specific IPv4 address assignment.

 DWORD R_DhcpV4EnumSubnetClients(
     [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_PB_ARRAY *ClientInfo,
     [out] DWORD *ClientsRead,
     [out] DWORD *ClientsTotal
 );

ServerIPAddress: The IP address of the DHCP server. This parameter is unused.

SubnetAddress: A DHCP_IP_ADDRESS structure 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: A DHCP_RESUME_HANDLE structure that identifies the enumeration operation. Callers MUST set this value to zero. On success, this method returns the handle value used for subsequent enumeration requests in this parameter. The return value is the last IPv4 address retrieved.

PreferredMaximum: A DWORD value that specifies the preferred maximum number of bytes to return. To retrieve all DHCPv4 clients serviced by a specific IPv4 subnet, clients MUST pass the special value 0xFFFFFFFF. Otherwise, the minimum value is 1024, and the maximum value is 65536. If the input value is less than 1024, it must be treated as 1024. If the input value is greater than 65536 but not equal to 0xFFFFFFFF, it MUST be treated as 65536.

ClientInfo: A pointer to an array of DHCPv4 client lease records.

ClientsRead: A pointer to a DWORD containing the number of DHCPv4 client lease records copied into the ClientInfo parameter. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

ClientsTotal: A pointer to a DWORD containing the number of DHCPv4 client lease records remaining from the current read position. For example, if there are 100 DHCPv4 lease records for an IPv4 subnet, and if 10 records have been read so far, ClientsTotal will hold the value 90 when this method returns. 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 ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully. Otherwise, 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 to any generic failure.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x000000EA

ERROR_MORE_DATA

More client lease records are available to enumerate.

0x00000103

ERROR_NO_MORE_ITEMS

No more client lease records are left to enumerate.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the DHCP server database.

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

  • Validate whether this method is authorized for read access as specified in section 3.5.4. If not, return the error ERROR_ACCESS_DENIED.

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

  • If the ResumeHandle parameter is a null pointer, enumeration MUST start from the first entry of the DHCPv4ClientsList ADM element.

  • If there are no entries in the DHCPv4ClientsList of the DHCPv4Scope entry corresponding to the SubnetAddress parameter, return ERROR_NO_MORE_ITEMS.

  • If the ResumeHandle parameter is not a null pointer, the server MUST continue enumeration based on the value of the ResumeHandle parameter. If the IPv4 Address contained in the location pointed to by the ResumeHandle parameter does not match the ClientIpAddress value of any DHCPv4Client of the DHCPv4Scope entry corresponding to the SubnetAddress parameter or does not match the ClientIpAddress value of any DHCPv4Client of all DHCPv4Scope entries when the specified SubnetAddress value is 0x0, return ERROR_DHCP_JET_ERROR.

  • If the PreferredMaximum parameter is less than 1024, set it to 1024.

  • If the PreferredMaximum parameter is greater than 65536 but is not equal to 0xFFFFFFFF, set it to 65536.

  • Allocate the amount of memory indicated by the PreferredMaximum parameter. If the PreferredMaximum parameter is equal to 0xFFFFFFFF, allocate an amount of memory sufficient to store all of the available client lease records. Note that the actual number of records that will fit into a given amount of memory can be determined only at run time.

  • For each retrieved DHCPv4Client entry, retrieve the DHCPv4Filter entry corresponding to the DHCPv4Client.ClientHardwareAddress ADM element.

  • Add the client information from the DHCPv4Client entries to the memory pointed to by the ClientInfo parameter. Set the FilterStatus field for each client lease record as follows.

    DHCPv4FilterListType

    DHCPv4Filter.AddPatt.IsWildCard

    FilterStatus

    Allow

    0

    0x00000002

    FILTER_STATUS_FULL_MATCH_IN_ALLOW_LIST

    Deny

    0

    0x00000004

    FILTER_STATUS_FULL_MATCH_IN_DENY_LIST

    Allow

    1

    0x00000008

    FILTER_STATUS_WILDCARD_MATCH_IN_ALLOW_LIST

    Deny

    1

    0x00000010

    FILTER_STATUS_WILDCARD_MATCH_IN_DENY_LIST

  • If the DHCPv4Filter entry corresponding to the DHCPv4Client.ClientHardwareAddress ADM element is not found, set the FilterStatus field for each client added to the ClientInfo parameter to FILTER_STATUS_NONE.

  • If the retrieve operation has reached the maximum number of DHCPv4Client entries that fit into the PreferredMaximum amount of memory and there are additional DHCPv4Client entries in any DHCPv4MClientsList, set the ClientsTotal parameter to the number of DHCPv4Client entries that have not yet been enumerated, and set the ClientsRead parameter to the number of DHCPv4Client entries that are enumerated in this retrieve operation. Set the ResumeHandle parameter to the address of the ClientIpAddress member of the last DHCPv4Client 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 all the DHCPv4Client entries, set the ClientsTotal parameter and the ClientsRead parameter to the total number of DHCPv4Client entries enumerated in this retrieve operation. Set the ResumeHandle parameter to the null pointer, and return ERROR_SUCCESS.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].