3.1.4.5 R_DhcpAddSubnetElement (Opnum 4)

  • Article

The R_DhcpAddSubnetElement method adds an IPv4 subnet element (IPv4 reservation, IPv4 exclusion range, or IPv4 range) to the IPv4 subnet in the DHCPv4 server. There is an extension of this method in R_DhcpAddSubnetElementV4 (section 3.1.4.30).

 DWORD R_DhcpAddSubnetElement(
     [in, unique, string]  DHCP_SRV_HANDLE  ServerIpAddress,
     [in]   DHCP_IP_ADDRESS      SubnetAddress,
     [in, ref]   LPDHCP_SUBNET_ELEMENT_DATA  AddElementInfo
 );

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

SubnetAddress: This is of type DHCP_IP_ADDRESS, containing the IPv4 subnet ID in which the IPv4 subnet element is added.

AddElementInfo: This is a pointer to a structure DHCP_SUBNET_ELEMENT_DATA (section 2.2.1.2.33) that contains the IPv4 subnet element that needs to be added to the IPv4 subnet.

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.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist.

0x00004E37

ERROR_DHCP_INVALID_RANGE

The specified IPv4 range either overlaps an existing range or is not valid.

0x00004E35

ERROR_DHCP_IPRANGE_EXITS

The specified IPv4 address range already exists.

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The specified DHCPv4 client is not an IPv4 reserved client.

0x00004E36

ERROR_DHCP_RESERVEDIP_EXITS

The specified IPv4 address or hardware address is being used by another DHCPv4 client.

0x00004E51

ERROR_DHCP_IPRANGE_CONV_ILLEGAL

Conversion of a BOOTP scope to a DHCP-only scope is illegal, since BOOTP clients exist in the scope. Manually delete BOOTP clients from the scope when converting the range to a DHCP-only range.

0x00004E90

ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT

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

0x00004EA1

ERROR_DHCP_FO_IPRANGE_TYPE_CONV_ILLEGAL

Conversion of a failover scope to a scope of type BOOTP or BOTH could not be performed. Failover is supported only for DHCP scopes.

The opnum field value for this method is 4.

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

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

  • Retrieve the server Abstract Data Model (ADM) element DHCPv4Scope entry corresponding to the SubnetAddress parameter from the server ADM element DHCPv4ScopesList.

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

  • If the ElementType member in the AddElementInfo parameter is set to the DhcpSecondaryHosts enumeration value, return ERROR_CALL_NOT_IMPLEMENTED.

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

  • If the ElementType member is set to DhcpIpRanges or DhcpIpRangesDhcpOnly or DhcpIpRangesDhcpBootp or DhcpIpRangesBootpOnly, and the IpRange member is NULL, return ERROR_INVALID_PARAMETER.

  • If EndAddress member of any kind of IPv4 range is less than StartAddress member, return ERROR_DHCP_INVALID_RANGE.

  • If the IsFailover member of the DHCPv4Scope ADM element is set to TRUE and if the ElementType member of the AddElementInfo parameter is set to DhcpIpRangesBootpOnly or DhcpIpRangesDhcpBootp, return ERROR_DHCP_FO_IPRANGE_TYPE_CONV_ILLEGAL.<25>

  • If the ElementType member is set to DhcpIpRangesDhcpOnly, DhcpIpRanges, DhcpIpRangesBootpOnly, or DhcpIpRangesDhcpBootp, and if the IpRange member is the same as the DHCPv4IpRange.RangeInfo ADM element in the first entry of DHCPv4Scope.DHCPv4IpRangesList ADM element, return ERROR_DHCP_IPRANGE_EXITS.

  • If the ElementType member is set to DhcpIpRangesDhcpOnly, DhcpIpRangesBootpOnly or DhcpIpRangesDhcpBootp, change the ElementType member to DhcpIpRanges.

  • If the ElementType member is set to DhcpIpRanges and there is a DHCPv4Client ADM element object entry in the DHCPv4Scope.DHCPv4ClientsList ADM element, with the bClientType member matching CLIENT_TYPE_BOOTP, then return ERROR_DHCP_IPRANGE_CONV_ILLEGAL.

  • If the ElementType member is set to DhcpIpRanges, iterate over the entries in the global DHCPv4Scope.DHCPv4ScopePolicyList ADM element. For each DHCPv4Policy object found, iterate over the object's DHCPv4Policy.Ranges member. If the StartAddress or EndAddress of any of the object's ranges is found to lie outside the new IP address range given by the StartAddress and EndAddress members of the DHCP_IP_RANGE structure within the AddElementInfo parameter, return ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT.<26>

  • If the ElementType member is set to DhcpIpRanges, the DHCPv4Scope.DHCPv4IpRangesList ADM element is not empty, and the new IP address range is not the same as the DHCPv4IpRange.RangeInfo ADM element of an existing IP address range, the new IP address range (specified by the StartAddress and EndAddress members of the DHCP_IP_RANGE structure) has to either be completely within the existing address range or completely contain the existing address range; if neither condition is met, return error ERROR_DHCP_INVALID_RANGE.

  • If the ElementType member is set to DhcpIpRanges and the DHCPv4Scope.DHCPv4IpRangesList ADM element is empty, create a new DHCPv4IpRange ADM element object, set the StartAddress and EndAddress members of the DHCPv4IpRange.RangeInfo ADM element to the StartAddress and EndAddress members of IpRange, set DHCPv4IpRange.RangeInfo.BootPAllocated to 0, set DHCPv4IpRange.RangeInfo.MaxBootpAllowed to 0xFFFFFFFF, and populate the DHCPv4IpRange.BitMask ADM element with bits corresponding to all the addresses within the newly created range and initialize each bit to 0, indicating the availability of its corresponding address for allocation to a DHCPv4 client. Insert the new object into the DHCPv4Scope.DHCPv4IpRangesList ADM element.

  • If the ElementType member is set to DhcpIpRanges and the DHCPv4Scope.DHCPv4IpRangesList ADM element is not empty, then set the StartAddress and EndAddress members of the existing DHCPv4IpRange.RangeInfo ADM element to the StartAddress and EndAddress members of IpRange ADM element, set DHCPv4IpRange.RangeInfo.BootPAllocated to 0, and set DHCPv4IpRange.RangeInfo.MaxBootpAllowed to 0xFFFFFFFF. The DHCPv4IpRange.BitMask ADM element needs to be expanded or contracted according to the new IpRange.StartAddress and IpRange.EndAddress. Accordingly, add or remove bits from the DHCPv4IpRange.BitMask ADM element. If adding bits for expansion, initialize them to 0 indicating the availability of their corresponding addresses for allocation to a DHCPv4 client.

  • If the ElementType member is set to DhcpExcludedIpRanges, create a DHCPv4ExclusionRange ADM element object, set it to the ExcludeIpRange member, and insert it into the DHCPv4ExclusionRangesList ADM element.

  • If the ElementType member is set to DhcpReservedIps, and ReservedIpAddress specified in the ReservedIp member field in the Element union does not fall within the range specified by the DHCPv4IpRange.RangeInfo ADM element of the first entry of the DHCPv4Scope.DHCPv4IpRangesList ADM element and is not an existing reserved address, return ERROR_DHCP_NOT_RESERVED_CLIENT.<27>

  • If the ElementType member is set to DhcpReservedIps, and there is a DHCPv4Reservation ADM element in the DHCPv4ReservationsList ADM element that corresponds to the reserved IPv4 address and/or hardware address specified in the ReservedIp member, return ERROR_DHCP_RESERVEDIP_EXITS; else, create a DHCPv4Reservation ADM element object and set it to the ReservedIp member input field. The DHCPv4Reservation.bAllowedClientTypes ADM element is set to CLIENT_TYPE_BOTH. Insert the object in the DHCPv4ReservationsList ADM element.

  • If the ElementType member is set to DhcpReservedIps and the previous steps resulted in a DHCPv4Reservation ADM element object being inserted into the DHCPv4Scope.DHCPv4ReservationsList ADM element, construct a temporary DHCPv4 client unique ID (section 2.2.1.2.5.2) by combining the DHCPv4Scope.ScopeInfo.SubnetAddress ADM element and the ReservedForClient member input field. If a DHCPv4Client ADM element object corresponding to the ReservedForClient member input field and the temporary unique ID does not exist within the DHCPv4Scope.DHCPv4ClientsList ADM element, create one and insert it into the list, thereby marking the address as unavailable to other clients. The DHCPv4Client ADM element object is initialized as follows:

    • The DHCPv4Client.ClientIpAddress ADM element is set to the ReservedIpAddress member input field.

    • The DHCPv4Client.SubnetMask ADM element is set to the DHCPv4Scope.Scopeinfo.SubnetMask ADM element.

    • The DHCPv4Client.ClientHardwareAddress ADM element is set to the temporary DHCPv4 client unique ID constructed above.

    • The DHCPv4Client.ClientLeaseExpires ADM element is set to 0.

    • The DHCPv4Client.ClientName ADM element is set to NULL.

    • The DHCPv4Client.ClientComment ADM element is set to NULL.

    • The DHCPv4Client.OwnerHost.NetBiosName ADM element is set to the NetBIOS name of the DHCPv4 server.

    • The DHCPv4Client.OwnerHost.IpAddress ADM element is set to 255.255.255.255.

    • The DHCPv4Client.bClientType ADM element is set to CLIENT_TYPE_NONE.

    • The DHCPv4Client.AddressState ADM element is set to ADDRESS_STATE_ACTIVE.

    • The DHCPv4Client.QuarantineCapable ADM element is set to FALSE.

    • The DHCPv4Client.Status ADM element is set to NOQUARANTINE.

    • The DHCPv4Client.ProbationEnds ADM element is set to 0.

    • The DHCPv4Client.SentPotExpTime ADM element is set to 0.

    • The DHCPv4Client.AckPotExpTime ADM element is set to 0.

    • The DHCPv4Client.RecvPotExpTime ADM element is set to 0.

    • The DHCPv4Client.StartTime ADM element is set to 0.

    • The DHCPv4Client.CltLastTransTime ADM element is set to 0.

    • The DHCPv4Client.LastBndUpdTime ADM element is set to 0.

    • The DHCPv4Client.flags ADM element is set to 0.

    • The DHCPv4Client.bndMsgStatus ADM element is set to 0.

    • The DHCPv4Client.PolicyName ADM element is set to NULL.

  • In continuation of the previous step, if the ReservedIp member input field falls within the limits of a range element contained in the DHCPv4Scope.DHCPv4IpRangesList ADM element, then set the bit corresponding to the IPv4 address in that DHCPv4IpRange.Bitmask ADM element to 1 to indicate the unavailability of the address when selecting a fresh address for allocation to DHCPv4 clients.

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