Share via

3.2.4.83 R_DhcpAddFilterV4 (Opnum 82)

  • Article

The R_DhcpAddFilterV4 method is used to add a link-layer address/pattern to allow list or deny list. The DHCPv4 server allows the DHCPv4 clients whose link-layer address is in the allow list to be given leases and blocks DHCPv4 clients whose link-layer address is in the deny list provided the respective lists are enabled using the R_DhcpSetFilterV4 (section 3.2.4.85) method. This method is also used to exempt one or more hardware types from filtering. However, hardware type 1 (Ethernet 10 Mb) cannot be exempted.

 DWORD R_DhcpAddFilterV4(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_FILTER_ADD_INFO* AddFilterInfo,
   [in] BOOL ForceFlag
 );

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

AddFilterInfo: This is a pointer to a DHCP_FILTER_ADD_INFO (section 2.2.1.2.90) that contains link-layer address/pattern , hardware type information, or both to be added to the database.

ForceFlag: This is of type BOOL that defines the behavior of this method. If the flag is set to TRUE and the filter exists, then it will be overwritten, else if the flag is FALSE and the filter already exists, then it will remain the same and will return error ERROR_DHCP_LINKLAYER_ADDDRESS_EXISTS.

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

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the DHCP server database.

0x00004E7E

ERROR_DHCP_LINKLAYER_ADDRESS_EXISTS

Address or Address pattern is already contained in one of the lists.

0x00000057

ERROR_INVALID_PARAMETER

Invalid input - address/pattern

0x00004E85

ERROR_DHCP_HARDWARE_ADDRESS_TYPE_ALREADY_EXEMPT

Hardware type already exempted from filtering.

The opnum field value for this method is 82.

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

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

  • If AddFilterInfo is NULL, return ERROR_INVALID_PARAMETER.

  • If the MatchHWType field of AddFilterInfo is FALSE, return ERROR_INVALID_PARAMETER.

  • An exemption for hardware types other than hardware type 1 (Ethernet 10 Mb) can be added if the AddrPatt member of the AddFilterInfo parameter contains an HWType value other than 1 and the value of the IsWildCard member of AddFilterInfo is TRUE, the hardware type specified by ListType is allowed, and the value of the Length member is 0. For any other value of IsWildCard, ListType, or Length, return ERROR_INVALID_PARAMETER.

  • If the AddrPatt member specified in AddFilterInfo contains an HWType value of 1, the value of the IsWildCard member of AddFilterInfo is FALSE, and Length value is not equal to 6, return ERROR_INVALID_PARAMETER.

  • If the AddrPatt member specified in AddFilterInfo contains an HWType value of 1, the value of the IsWildCard member of AddFilterInfo is TRUE, and Length value is greater than 5 or less than 1, return ERROR_INVALID_PARAMETER.

  • Iterate through the server ADM element DHCPv4FiltersList and if there is any DHCPv4Filter entry in which the AddrPatt.Pattern field matches the AddrPatt.Pattern field of AddFilterInfo input parameter, the AddrPatt.HwType field matches the AddrPatt.HwType field of AddFilterInfo input parameter, and the ForceFlag is set to FALSE, then return ERROR_DHCP_LINKLAYER_ADDRESS_EXISTS. Otherwise, if the ForceFlag is set to TRUE, modify the fields of the DHCPv4Filter with information in AddFilterInfo input parameter. A record can only be added to the deny list or the allow list. The same record cannot exist in both the lists.

    If no entry exists in which the AddrPatt.Pattern field matches the AddrPatt.Pattern field of AddFilterInfo input parameter and the AddrPatt.HwType field matches AddrPatt.HwType field of AddFilterInfo input parameter, then create a DHCPv4Filter object and insert it into the DHCPv4FiltersList. Set the fields of DHCPv4Filter objects to values in AddFilterInfo input parameter.

  • If the AddrPatt.HwType field of the AddFilterInfo input parameter is not equal to 1 and there is a DHCPv4Filter entry in which the AddrPatt.HwType field matches the AddrPatt.HwType field of AddFilterInfo input parameter and the ForceFlag parameter is FALSE, return ERROR_DHCP_HARDWARE_ADDRESS_TYPE_ALREADY_EXEMPT. Otherwise, if ForceFlag is set to TRUE, return ERROR_SUCCESS. If the DHCPv4Filter entry is not found, create a DHCPv4Filter object and insert it into the DHCPv4FiltersList. Set the fields of DHCPv4Filter objects to values in AddFilterInfo input parameter.

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