3.1.4.7 R_DhcpRemoveSubnetElement (Opnum 6)

The R_DhcpRemoveSubnetElement method removes an IPv4 subnet element from an IPv4 subnet defined on the DHCPv4 server.

 DWORD R_DhcpRemoveSubnetElement(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, ref] LPDHCP_SUBNET_ELEMENT_DATA RemoveElementInfo,
   [in] DHCP_FORCE_FLAG ForceFlag
 );

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) that contains the IPv4 subnet ID from which subnet elements are enumerated.

RemoveElementInfo: This is a pointer of type DHCP_SUBNET_ELEMENT_DATA (section 2.2.1.2.33), containing the IPv4 subnet element that needs to be removed from the IPv4 subnet.

ForceFlag: This is of type DHCP_FORCE_FLAG (section 2.2.1.1.9), defining the behavior of this method. If the flag is set to DhcpNoForce and this subnet has served the IPv4 address to some DHCPv4\BOOTP clients, the IPv4 range is not deleted; if the flag is set to DhcpFullForce, the IPv4 range is deleted along with DHCPv4 client lease record on the DHCPv4 server.

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.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist.

0x00004E27

ERROR_DHCP_ELEMENT_CANT_REMOVE

  • The specified IPv4 subnet element cannot be removed because at least one IPv4 address has been leased out to a client from the subnet.

  • The starting address of the specified IPv4 exclusion range is not part of any exclusion range configured on the server.

  • There is an error in deleting the exclusion range from the database.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the DHCP server database.

0x00004E37

ERROR_DHCP_INVALID_RANGE

The specified IPv4 range does not match an existing IPv4 range.

0x00004E90

ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT

There is an IP address range configured for a policy in this scope. This operation cannot be performed until the policy IP range is suitably modified.

The opnum field value for this method is 6.

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

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

  • Retrieve the DHCPv4Scope ADM element entry corresponding to the SubnetAddress parameter from the DHCPv4ScopesList server ADM element.

  • If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpReservedIps and the DHCPv4ReservationsList ADM element contains a DHCPv4Reservation ADM element entry corresponding to the ReservedIp member input field, then delete the DHCPv4Reservation ADM element entry corresponding to the ReservedIp member input field from the DHCPv4ReservationsList ADM element. Further, if the ReservedIp member input field falls within the limits of a range element contained in DHCPv4Scope.DHCPv4IpRangesList ADM element, then set the bit corresponding to the IPv4 address in that DHCPv4IpRange.Bitmask ADM element to 0 to indicate the availability of the address for allocation to DHCPv4 clients.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpReservedIps and the preceding steps resulted in a DHCPv4Reservation ADM element entry being deleted from the DHCPv4ReservationsList ADM element, then also locate a DHCPv4Client ADM element in the DHCPv4ClientsList ADM element that matches the ReservedIp member input field. If the DHCPv4Client.ClientLeaseExpires ADM element is set to 0, then delete the DHCPv4Client ADM element object, or else set the DHCPv4Client.ClientLeaseExpires ADM element to the lease expiry time applicable to the DHCPv4Scope ADM element. If no such DHCPv4Client ADM element is located, return ERROR_DHCP_JET_ERROR.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpReservedIps and the DHCPv4ReservationsList ADM element does not contain any DHCPv4Reservation ADM element entry corresponding to the ReservedIp member input field, then delete any DHCPv4 client lease record with the client IP address that is the same as the ReservedIp member input field by calling R_DhcpDeleteClientInfo (section 3.1.4.20). Return the result of deleting the lease information.

  • If the ElementType member in RemoveElementInfo parameter is set to DhcpExcludedIpRanges and the ExcludeIpRange member in the RemoveElementInfo parameter is equal to NULL, return ERROR_INVALID_PARAMETER.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpExcludedIpRanges and the starting address of the IPv4 exclusion range in the ExcludeIpRange member of the RemoveElementInfo parameter is not part of any IPv4 exclusion range configured for the subnet, return ERROR_DHCP_ELEMENT_CANT_REMOVE.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpExcludedIpRanges and the IPv4 exclusion range in the ExcludeIpRange member of RemoveElementInfo parameter does not match the starting and ending address of any IPv4 exclusion range configured for that subnet, then return ERROR_INVALID_PARAMETER.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpExcludedIpRanges, delete the DHCPv4ExclusionRange ADM element entry corresponding to the ExcludeIpRange member input field from the DHCPv4ExclusionRangesList ADM element. If there is an error in deleting the IPv4 exclusion range from the DHCP server database, then return ERROR_DHCP_ELEMENT_CANT_REMOVE.

  • If the ElementType member in RemoveElementInfo parameter is set to DhcpSecondaryHosts, return ERROR_CALL_NOT_IMPLEMENTED.

  • If the ElementType member in RemoveElementInfo parameter is set to DhcpIpUsedClusters, return ERROR_INVALID_PARAMETER.

  • If the ElementType member is set to DhcpIpRanges, DhcpIpRangesDhcpOnly, DhcpIpRangesDhcpBootp, or DhcpIpRangesBootpOnly, iterate over the entries in the global DHCPv4Scope.DHCPv4ScopePolicyList ADM element. If any of the DHCPv4Policy objects in the list contains a DHCPv4Policy.Ranges member with a NumElements member greater than zero, return ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT.<28>

  • If the ElementType member in RemoveElementInfo parameter is set to one of the values from DhcpIpRanges, DhcpIpRangesDhcpBootp, DhcpIpRangesDhcpOnly, or DhcpIpRangesBootpOnly (section 2.2.1.1.7), and the range of the IPv4 subnet specified in the RemoveElementInfo parameter does not match the DHCPv4IpRange.RangeInfo ADM element of any entry in the DHCPv4Scope.DHCPv4IpRangesList ADM element, return ERROR_DHCP_INVALID_RANGE.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpIpRanges, DhcpIpRangesDhcpOnly, DhcpIpRangesDhcpBootp, or DhcpIpRangesBootpOnly, ForceFlag (section 2.2.1.1.9) is set to DhcpNoForce, and if there is any entry in the DHCPv4ClientsList ADM element having an IPv4 address from that IPv4 range, return ERROR_DHCP_ELEMENT_CANT_REMOVE; otherwise, delete the DHCPv4IpRange ADM element entry from the DHCPv4IpRangesList ADM element. Return ERROR_SUCCESS.

  • If the ElementType member in the RemoveElementInfo parameter is set to DhcpIpRanges, DhcpIpRangesDhcpOnly, DhcpIpRangesDhcpBootp, or DhcpIpRangesBootpOnly, and ForceFlag (section 2.2.1.1.9) is set to DhcpFullForce, delete the DHCPv4IpRange ADM element entry from the DHCPv4IpRangesList ADM element. Return ERROR_SUCCESS.

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