3.2.4.89 R_DhcpEnumSubnetClientsFilterStatusInfo (Opnum 88)

The R_DhcpEnumSubnetClientsFilterStatusInfo 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.

 DWORD R_DhcpEnumSubnetClientsFilterStatusInfo(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_CLIENT_FILTER_STATUS_INFO_ARRAY* ClientInfo,
   [out] DWORD* ClientRead,
   [out] DWORD* ClientsTotal
 );

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

SubnetAddress: This is of type DHCP_IP_ADDRESS (section 2.2.1.2.1) which contains 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) which 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 field contains the last IPv4 address retrieved.

PreferredMaximum: This is of type DWORD which specifies the preferred maximum number of bytes to return. The minimum value is 1024 bytes (1 kilobyte), and the maximum value is 65536 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 DHCPv4 clients serviced by a specific IPv4 subnet, 0xFFFFFFFF is specified.

ClientInfo: This is a pointer of type LPDHCP_CLIENT_FILTER_STATUS_INFO_ARRAY that points to the location which contains the DHCPv4 client lease record array.

ClientRead: This is a pointer to a DWORD that specifies the number of DHCPv4 client lease records read in ClientInfo. The caller must allocate memory for this parameter that is 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. The caller must allocate memory for this parameter that is equal to the size of data type DWORD. For example, if there are 100 DHCPv4 lease record clients for an IPv4 subnet, and if 10 DHCPv4 lease records are enumerated per call, then for the first time this would have a value of 90.<72>

Return Values: A 32-bit unsigned integer value that indicates return status. A return value ERROR_SUCCESS (0x00000000) indicates 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 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 88.

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

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

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

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

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

  • If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the IPv4 Address contained in the ResumeHandle does not match the ClientIpAddress of any DHCPv4Client of the DHCPv4Scope entry corresponding to the SubnetAddress or does not match the ClientIpAddress of any DHCPv4Client of all DHCPv4Scope entries when the specified SubnetAddress 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.

  • Allocate memory for PreferredMaximum number of bytes.

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

  • Add the client information from DHCPv4Client entries in the ClientInfo structure. The FilterStatus field for each client in ClientInfo is set according to the table that follows:

    DHCPv4Filter.ListType

    DHCPv4Filter.AddPatt.IsWildCard

    FilterStatus

    Allow

    0

    FILTER_STATUS_FULL_MATCH_IN_ALLOW_LIST

    0x00000002

    Deny

    0

    FILTER_STATUS_FULL_MATCH_IN_DENY_LIST

    0x00000004

    Allow

    1

    FILTER_STATUS_WILDCARD_MATCH_IN_ALLOW_LIST

    0x00000008

    Deny

    1

    FILTER_STATUS_WILDCARD_MATCH_IN_DENY_LIST

    0x00000010

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

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

  • If the retrieve operation has reached the maximum number of DHCPv4Client entries that can be accommodated in PreferredMaximum and there are still more DHCPv4Client entries in any DHCPv4MClientsList, set ClientsTotal to the number of DHCPv4Client entries that are not yet enumerated, and set ClientsRead to the number of DHCPv4Client entries that are enumerated in this retrieve operation. Set ResumeHandle to the ClientIpAddress member of the last DHCPv4Client entry, and return ERROR_MORE_DATA.

  • If the number of bytes specified by PreferredMaximum is more than the total memory occupied by DHCPv4Client entries, set ClientsTotal to the total number of DHCPv4Client entries enumerated in that retrieve operation and ClientsRead to the number of DHCPv4Client entries that are enumerated in this retrieve operation. Set ResumeHandle to 0 and return ERROR_SUCCESS.

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