Share via

3.1.4.30 R_DhcpAddSubnetElementV4 (Opnum 29)

  • Article

The R_DhcpAddSubnetElementV4 method adds an IPv4 subnet element (IPv4 reservation for DHCPv4 or BOOTP clients, IPv4 exclusion range, or IPv4 range) to the IPv4 subnet in the DHCPv4 server. There is an extension of this method in R_DhcpAddSubnetElementV5 (section 3.2.4.38).

 DWORD R_DhcpAddSubnetElementV4(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, ref] LPDHCP_SUBNET_ELEMENT_DATA_V4 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 DHCP_SUBNET_ELEMENT_DATA_V4 (section 2.2.1.2.35) structure 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.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist on the DHCP server.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the DHCP server database.

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The specified DHCP client is not a reserved client.

0x00004E35

ERROR_DHCP_IPRANGE_EXITS

The specified IPv4 address range already exists.

0x00004E36

ERROR_DHCP_RESERVEDIP_EXITS

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

0x00004E37

ERROR_DHCP_INVALID_RANGE

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

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

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

0x00004EA1

ERROR_DHCP_FO_IPRANGE_TYPE_CONV_ILLEGAL

Conversion of a failover scope to a BOOTP-only or BOTH scope cannot be performed. Failover is supported only for DHCP scopes.

The opnum field value for this method is 29.

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 the error ERROR_ACCESS_DENIED.

  • Retrieve the DHCPv4Scope ADM element object corresponding to the SubnetAddress parameter 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 DhcpSecondaryHosts, 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, DhcpIpRangesDhcpOnly, DhcpIpRangesDhcpBootp or DhcpIpRangesBootpOnly, and the IpRange member is NULL, return ERROR_INVALID_PARAMETER.

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

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

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

  • If the ElementType member is set to DhcpIpRangesDhcpOnly or 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 DHCPv4Scope.DHCPv4ScopePolicyList. For each DHCPv4Policy object found, iterate over the DHCPv4Policy.Ranges member. If the StartAddress or EndAddress member of any range is outside the new IP address range, as given by the StartAddress and EndAddress members of the DHCP_IP_RANGE structure within the AddElementInfo parameter, return ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT.<34>

  • 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 the IpRange member, set the DHCPv4IpRange.RangeInfo.BootPAllocated ADM element to 0, set the DHCPv4IpRange.RangeInfo.MaxBootpAllowed ADM element 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, and return ERROR_SUCCESS.

  • If the ElementType member is set to DhcpIpRanges and the DHCPv4Scope.DHCPv4IpRangesList ADM element is not empty, set the StartAddress and EndAddress members of the existing DHCPv4IpRange.RangeInfo ADM element to the StartAddress and EndAddress members of the IpRange member, set the DHCPv4IpRange.RangeInfo.BootPAllocated ADM element to 0, and set the DHCPv4IpRange.RangeInfo.MaxBootpAllowed ADM element to 0xFFFFFFFF. The DHCPv4IpRange.BitMask ADM element needs to be expanded or contracted according to the new IpRange.StartAddress ADM element and IpRange.EndAddress ADM element. 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, and return ERROR_SUCCESS.

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

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

  • If the ElementType member is set to DhcpReservedIps, and there is a DHCPv4Reservation ADM element in DHCPv4ReservationsList ADM element that corresponds to the reserved IPv4 address and/or hardware address specified in the ReservedIpAddress member (section 2.2.1.2.32), return ERROR_DHCP_RESERVEDIP_EXITS; else create a DHCPv4Reservation ADM element object and set it to the ReservedIp member input field. 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:

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

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

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

    • DHCPv4Client.ClientLeaseExpires ADM element is set to 0.

    • DHCPv4Client.ClientName ADM element is set to NULL.

    • DHCPv4Client.ClientComment ADM element is set to NULL.

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

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

    • DHCPv4Client.bClientType ADM element is set to CLIENT_TYPE_NONE.

    • DHCPv4Client.AddressState ADM element is set to ADDRESS_STATE_ACTIVE.

    • DHCPv4Client.QuarantineCapable ADM element is set to FALSE.

    • DHCPv4Client.Status ADM element is set to NOQUARANTINE.

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

  • Return ERROR_SUCCESS.

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