3.2.4.87 R_DhcpEnumFilterV4 (Opnum 86)

The R_DhcpEnumFilterV4 method enumerates all the filter records from either allow list or deny list. It also returns a list of hardware types presently exempted from filtering. These entries are present in the allow list. Exemption entries have a pattern of Length 0 and IsWildCard set to TRUE; both are specified in the AddrPatt field of the DHCP_FILTER_RECORD (section 2.2.1.2.92) structure.

 DWORD R_DhcpEnumFilterV4(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, out] LPDHCP_ADDR_PATTERN ResumeHandle,
   [in] DWORD PreferredMaximum,
   [in] DHCP_FILTER_LIST_TYPE ListType,
   [out] LPDHCP_FILTER_ENUM_INFO* EnumFilterInfo,
   [out] DWORD* ElementsRead,
   [out] DWORD* ElementsTotal
 );

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

ResumeHandle: This is a pointer of type DHCP_ADDR_PATTERN (section 2.2.1.2.89) which identifies the enumeration operation. Initially, this value MUST be set to zero, with a successful call returning the address/pattern value used for subsequent enumeration requests.

PreferredMaximum: This is of type DWORD which specifies the preferred maximum number of bytes to return. If the number of remaining unenumerated filter information size is less than this value, then all the filters configured on the specific list on the DHCPv4 server are returned. The maximum value for this is 64 kilobytes and the minimum value is 1 kilobyte. To retrieve all filter records, 0xFFFFFFFF is specified.

ListType: This is of type DHCP_FILTER_LIST_TYPE (section 2.2.1.1.17), which specifies the list to be enumerated.

EnumFilterInfo: This is a pointer of type LPDHCP_FILTER_ENUM_INFO that points to the location in which the link-layer filter info configured on the DHCPv4 server is returned.

ElementsRead: This is a pointer to a DWORD value that specifies the number of link-layer filter entries returned in EnumFilterInfo. The caller must allocate memory for this parameter that is equal to the size of data type DWORD.

ElementsTotal: This is a pointer to a DWORD value that specifies the number of link-layer filter entries defined on the DHCPv4 server that have not yet been enumerated with respect to the resume handle that is returned. The caller must allocate memory for this parameter that is equal to the size of data type DWORD.

Return Values: A 32-bit unsigned integer value that indicates return status. A return value ERROR_NO_MORE_ITEMS (0x00000103) 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 any generic failure.

Return value/code

Description

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 86.

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 all the DHCPv4Filter entries in which the ListType field is equal to the ListType input parameter from the server ADM element DHCPv4FiltersList and start enumerating from ResumeHandle filter.

  • If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry in the retrieved list.

  • If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle is greater than the number of DHCPv4Filter entries, then return ERROR_NO_MORE_ITEMS.

  • 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 configured link-layer filters.

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

  • Allocate memory for EnumFilterInfo equal to the size of structure DHCP_FILTER_ENUM_INFO.

  • Copy the retrieved DHCPv4Filter entries in EnumFilterInfo, copy the numbers of read DHCPv4Filter entries in ElementsRead, and copy the numbers of DHCPv4Filter entries that have not been enumerated in ElementsTotal. Update the ResumeHandle to the AddrPatt field of the last DHCPv4Filter entry read. If the size of link-layer filters to be enumerated exceeds PreferredMaximum, enumerate DHCPv4Filter entries with total size less than or equal to PreferredMaximum and return ERROR_MORE_DATA. If the size of DHCPv4Filter entries to be enumerated is less than or equal to PreferredMaximum, enumerate all the DHCPv4Filter entries and return ERROR_NO_MORE_ITEMS.

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