3.2.4.5 R_DhcpAddMScopeElement (Opnum 4)

  • Article

The R_DhcpAddMScopeElement method adds an IPv4 multicast subnet element (IPv4 range or IPv4 exclusion range) to the IPv4 multicast subnet in the MADCAP server. 

 DWORD R_DhcpAddMScopeElement(
     [in, unique, string]  DHCP_SRV_HANDLE ServerIpAddress,
     [in, ref, string]    LPWSTR *MScopeName,
     [in, ref] LPDHCP_SUBNET_ELEMENT_DATA_V4 AddElementInfo
 );

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

MScopeName: This is a pointer to a Unicode string that contains the name of the IPv4 multicast subnet in which the element is added. There is no restriction on the length of this parameter.

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

Return Values: A 32-bit unsigned integer value that indicates return status. A return value of 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.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the MADCAP server database.

0x00004E37

ERROR_DHCP_INVALID_RANGE

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

0x00004E56

ERROR_MSCOPE_RANGE_TOO_SMALL

The multicast scope range MUST have at least 256 IPv4 addresses.

0x00004E35

ERROR_DHCP_IPRANGE_EXITS

The specified multicast range already exists.

The opnum field value for this method is 4.

When processing this call, the MADCAP 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.

  • If the MScopeName and AddElementInfo parameters are NULL, return ERROR_INVALID_PARAMETER.

  • Retrieve the DHCPv4MScope ADM element entry corresponding to MScopeName from the server ADM element DHCPv4MScopesList.

  • If the DHCPv4MScope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If the ElementType field in the AddElementInfo parameter is set to DhcpSecondaryHosts, return ERROR_CALL_NOT_IMPLEMENTED.

  • If ElementType is set to DhcpReservedIps or DhcpIpUsedClusters, return ERROR_INVALID_PARAMETER.

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

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

  • If ElementType is set to DhcpIpRanges, check that the start and end addresses of the range are valid multicast addresses as defined in [RFC2780]. That is, the IPv4 addresses fall within the range of 224.0.0.0 through 239.255.255.255. If the check fails, return ERROR_INVALID_PARAMETER.

  • If the ElementType is set to DhcpIpRanges, DhcpIpRangesDhcpOnly, DhcpIpRangesBootpOnly, or DhcpIpRangesDhcpBootp, and the end address falls within the administratively scoped IPv4 multicast address space, ensure that the range contains 256 or more addresses. The administratively scoped IPv4 multicast address space ranges from 239.0.0.0 through 239.255.255.255, as defined in [RFC2365]. If the check fails, return ERROR_MSCOPE_RANGE_TOO_SMALL.

  • If there is a DHCPv4IPRange ADM element entry in DHCPv4MScope.DHCPv4IPRangesList that has RangeInfo.StartAddress and RangeInfo.EndAddress fields that match the StartAddress and EndAddress fields of AddElementInfo.IpRange, return ERROR_DHCP_IPRANGE_EXITS.

  • If the DHCPv4MScope.DHCPv4IPRangesList ADM element is not empty and the new IPv4 multicast range is not the same as the DHCPv4IPRange.RangeInfo of an entry in DHCPv4MScope.DHCPv4IPRangesList, the new IPv4 multicast range (specified by the StartAddress and EndAddress members of the DHCP_IP_RANGE structure) has to either be completely within the range specified by the DHCPv4IPRange entry or completely contain the range specified by the DHCPv4IPRange entry; if neither condition is met return error ERROR_DHCP_INVALID_RANGE.

  • If DHCPv4MScope.DHCPv4IpRangesList is empty, create a new DHCPv4IpRange object, set the StartAddress and EndAddress fields of DHCPv4IpRange.RangeInfo to the StartAddress and EndAddress fields of IpRange, DHCPv4IpRange.RangeInfo.BootPAllocated to 0, DHCPv4IpRange.RangeInfo.MaxBootpAllowed to 0xFFFFFFFF and populate the DHCPv4IpRange.BitMask 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 MADCAP client. Insert the new object into DHCPv4MScope.DHCPv4IpRangesList.

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

  • If the ElementType is DhcpIpRanges and the end address falls within the administratively scoped IPv4 multicast address space defined in [RFC2365], then automatically insert an exclusion range for the last 256 elements. Create a DHCPv4ExclusionRange ADM element object and insert it into an DHCPv4MScope.DHCPv4ExclusionRangesList ADM element. The DHCPv4ExclusionRange object is initialized as follows:

    • DHCPv4ExclusionRange.StartAddress is set to AddElementInfo.IpRange.EndAddress – 255.

    • DHCPv4ExclusionRange.EndAddress is set to AddElementInfo.IpRange.EndAddress.

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

  • Return ERROR_SUCCESS.

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