<div class="content" name="R_DhcpAddSubnetElement" uuid="d9fde2eb-da3d-48ad-9f4a-2d5e575b5a0b"><p>The <b>R_DhcpAddSubnetElement</b> method adds an IPv4 subnet
element (IPv4 <a href="a9d6a415-4de6-4058-befe-ca2e42764485#gt_4e525014-9425-4eb0-9141-61189c4f04f9" data-linktype="relative-path">reservation</a>,
IPv4 <a href="a9d6a415-4de6-4058-befe-ca2e42764485#gt_64d30865-9640-4009-a80a-861966749767" data-linktype="relative-path">exclusion range</a>, or
IPv4 range) to the IPv4 subnet in the DHCPv4 server. There is an extension of
this method in <a href="429f7260-b473-4f0f-be5f-f07d05cfc0b2" data-linktype="relative-path">R_DhcpAddSubnetElementV4 (section 3.1.4.30)</a>.</p><dl>
<dd>
<div><pre> DWORD R_DhcpAddSubnetElement(
     [in, unique, string]  DHCP_SRV_HANDLE  ServerIpAddress,
     [in]   DHCP_IP_ADDRESS      SubnetAddress,
     [in, ref]   LPDHCP_SUBNET_ELEMENT_DATA  AddElementInfo
 );
</pre></div>
</dd></dl><p><b>ServerIpAddress: </b>The IP address/host name of
the DHCP server. This parameter is unused. </p><p><b>SubnetAddress: </b>This is of type <a href="5122557b-b85d-4982-8ffb-98d8d934e353" data-linktype="relative-path">DHCP_IP_ADDRESS</a>,
containing the IPv4 subnet ID in which the IPv4 subnet element is added.</p><p><b>AddElementInfo: </b>This is a pointer to a
structure <a href="5ce2002b-fd0c-4776-805a-e87546616581" data-linktype="relative-path">DHCP_SUBNET_ELEMENT_DATA (section 2.2.1.2.33)</a>
that contains the IPv4 subnet element that needs to be added to the IPv4
subnet.</p><p><b>Return Values: </b>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 <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>.
This error code value can correspond to a DHCP-specific failure, which takes a
value between 20000 and 20099, or any generic failure.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 ERROR_SUCCESS</td>
  <td>The call was successful.</td>
 </tr><tr>
  <td>0x00004E2D ERROR_DHCP_JET_ERROR</td>
  <td>An error occurred while accessing the DHCP server database.</td>
 </tr><tr>
  <td>0x00004E25 ERROR_DHCP_SUBNET_NOT_PRESENT</td>
  <td>The specified IPv4 subnet does not exist.</td>
 </tr><tr>
  <td>0x00004E37 ERROR_DHCP_INVALID_RANGE</td>
  <td>The specified IPv4 range either overlaps an existing range or is not valid.</td>
 </tr><tr>
  <td>0x00004E35 ERROR_DHCP_IPRANGE_EXITS</td>
  <td>The specified IPv4 address range already exists.</td>
 </tr><tr>
  <td>0x00004E32 ERROR_DHCP_NOT_RESERVED_CLIENT</td>
  <td>The specified DHCPv4 client is not an IPv4 reserved client.</td>
 </tr><tr>
  <td>0x00004E36 ERROR_DHCP_RESERVEDIP_EXITS</td>
  <td>The specified IPv4 address or hardware address is being used by another DHCPv4 client.</td>
 </tr><tr>
  <td>0x00004E51 ERROR_DHCP_IPRANGE_CONV_ILLEGAL</td>
  <td>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.</td>
 </tr><tr>
  <td>0x00004E90 ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT</td>
  <td>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.</td>
 </tr><tr>
  <td>0x00004EA1 ERROR_DHCP_FO_IPRANGE_TYPE_CONV_ILLEGAL</td>
  <td>Conversion of a failover scope to a scope of type BOOTP or BOTH could not be performed. Failover is supported only for DHCP scopes.</td>
 </tr></tbody></table>
</dd></dl><p>The opnum field value for this method is 4.</p><p>When processing this call, the DHCP server MUST do the
following:</p><ul><li><p><span><span> 
</span></span>Validate that this method is authorized for read/write access per
section <a href="38840bd0-0a5a-47ed-bc69-0dd870d33aec" data-linktype="relative-path">3.5.5</a>. If not,
return the error ERROR_ACCESS_DENIED.</p>
</li><li><p><span><span> 
</span></span>Retrieve the server Abstract Data Model (ADM) element <b>DHCPv4Scope</b>
entry corresponding to the <i>SubnetAddress</i> parameter from the server ADM
element <b>DHCPv4ScopesList</b>.</p>
</li><li><p><span><span> 
</span></span>If the <b>DHCPv4Scope</b> ADM element entry is not found, return
ERROR_DHCP_SUBNET_NOT_PRESENT.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member in the <i>AddElementInfo</i>
parameter is set to the DhcpSecondaryHosts enumeration value, return
ERROR_CALL_NOT_IMPLEMENTED.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpUsedClusters,
return ERROR_INVALID_PARAMETER.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRanges or
DhcpIpRangesDhcpOnly or DhcpIpRangesDhcpBootp or DhcpIpRangesBootpOnly, and the
<b>IpRange</b> member is NULL, return ERROR_INVALID_PARAMETER.</p>
</li><li><p><span><span> 
</span></span>If <b>EndAddress</b> member of any kind of IPv4 range is less
than <b>StartAddress</b> member, return ERROR_DHCP_INVALID_RANGE.</p>
</li><li><p><span><span> 
</span></span>If the <b>IsFailover</b> member of the <b>DHCPv4Scope</b> ADM
element is set to TRUE and if the <b>ElementType</b> member of the <i>AddElementInfo</i>
parameter is set to DhcpIpRangesBootpOnly or DhcpIpRangesDhcpBootp, return
ERROR_DHCP_FO_IPRANGE_TYPE_CONV_ILLEGAL.<a id="Appendix_A_Target_25"></a><a aria-label="Product behavior note 25" href="afab0546-79ae-4764-8dab-27a85cca5145#Appendix_A_25" data-linktype="relative-path">&lt;25&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRangesDhcpOnly,
DhcpIpRanges, DhcpIpRangesBootpOnly, or DhcpIpRangesDhcpBootp, and if the <b>IpRange</b>
member is the same as the <b>DHCPv4IpRange.RangeInfo</b> ADM element in the
first entry of <b>DHCPv4Scope.DHCPv4IpRangesList</b> ADM element, return
ERROR_DHCP_IPRANGE_EXITS.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRangesDhcpOnly,
DhcpIpRangesBootpOnly or DhcpIpRangesDhcpBootp, change the <b>ElementType</b>
member to DhcpIpRanges.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRanges and there
is a <b>DHCPv4Client</b> ADM element object entry in the <b>DHCPv4Scope.DHCPv4ClientsList</b>
ADM element, with the <b>bClientType</b> member matching CLIENT_TYPE_BOOTP,
then return ERROR_DHCP_IPRANGE_CONV_ILLEGAL.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRanges, iterate
over the entries in the global <b>DHCPv4Scope.DHCPv4ScopePolicyList</b> ADM
element. For each <b>DHCPv4Policy</b> object found, iterate over the object&#39;s <b>DHCPv4Policy.Ranges</b>
member. If the <b>StartAddress</b> or <b>EndAddress</b> of any of the object&#39;s
ranges is found to lie outside the new IP address range given by the <b>StartAddress</b>
and <b>EndAddress</b> members of the <b>DHCP_IP_RANGE</b> structure within the <i>AddElementInfo</i>
parameter, return ERROR_SCOPE_RANGE_POLICY_RANGE_CONFLICT.<a id="Appendix_A_Target_26"></a><a aria-label="Product behavior note 26" href="afab0546-79ae-4764-8dab-27a85cca5145#Appendix_A_26" data-linktype="relative-path">&lt;26&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRanges, the <b>DHCPv4Scope.DHCPv4IpRangesList</b>
ADM element is not empty, and the new IP address range is not the same as the <b>DHCPv4IpRange.RangeInfo</b>
ADM element of an existing IP address range, the new IP address range
(specified by the <b>StartAddress</b> and <b>EndAddress</b> members of the <a href="29a03b34-249e-4bd8-a118-e708dadbf22b" data-linktype="relative-path">DHCP_IP_RANGE</a> 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. </p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRanges and the <b>DHCPv4Scope.DHCPv4IpRangesList</b>
ADM element is empty, create a new <b>DHCPv4IpRange</b> ADM element object, set
the <b>StartAddress</b> and <b>EndAddress</b> members of the <b>DHCPv4IpRange.RangeInfo</b>
ADM element to the <b>StartAddress</b> and <b>EndAddress</b> members of <b>IpRange</b>,
set <b>DHCPv4IpRange.RangeInfo.BootPAllocated</b> to 0, set <b>DHCPv4IpRange.RangeInfo.MaxBootpAllowed</b>
to 0xFFFFFFFF, and populate the <b>DHCPv4IpRange.BitMask</b> 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 <b>DHCPv4Scope.DHCPv4IpRangesList</b>
ADM element.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpIpRanges and the <b>DHCPv4Scope.DHCPv4IpRangesList</b>
ADM element is not empty, then set the <b>StartAddress</b> and <b>EndAddress</b>
members of the existing <b>DHCPv4IpRange.RangeInfo</b> ADM element to the <b>StartAddress</b>
and <b>EndAddress</b> members of <b>IpR</b>ange ADM element, set <b>DHCPv4IpRange.RangeInfo.BootPAllocated</b>
to 0, and set <b>DHCPv4IpRange.RangeInfo.MaxBootpAllowed</b> to 0xFFFFFFFF. The
<b>DHCPv4IpRange.BitMask</b> ADM element needs to be expanded or contracted
according to the new <b>IpRange.StartAddress</b> and <b>IpRange.EndAddress</b>.
Accordingly, add or remove bits from the <b>DHCPv4IpRange.BitMask</b> ADM
element. If adding bits for expansion, initialize them to 0 indicating the
availability of their corresponding addresses for allocation to a DHCPv4
client.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpExcludedIpRanges,
create a <b>DHCPv4ExclusionRange</b> ADM element object, set it to the <b>ExcludeIpRange</b>
member, and insert it into the <b>DHCPv4ExclusionRangesList</b> ADM element.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpReservedIps, and <b>ReservedIpAddress</b>
specified in the <b>ReservedIp</b> member field in the Element union does not
fall within the range specified by the <b>DHCPv4IpRange.RangeInfo</b> ADM
element of the first entry of the <b>DHCPv4Scope.DHCPv4IpRangesList</b> ADM
element and is not an existing reserved address, return
ERROR_DHCP_NOT_RESERVED_CLIENT.<a id="Appendix_A_Target_27"></a><a aria-label="Product behavior note 27" href="afab0546-79ae-4764-8dab-27a85cca5145#Appendix_A_27" data-linktype="relative-path">&lt;27&gt;</a></p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpReservedIps, and
there is a <b>DHCPv4Reservation</b> ADM element in the <b>DHCPv4ReservationsList</b>
ADM element that corresponds to the reserved IPv4 address and/or hardware
address specified in the <b>ReservedIp</b> member, return
ERROR_DHCP_RESERVEDIP_EXITS; else, create a <b>DHCPv4Reservation</b> ADM
element object and set it to the <b>ReservedIp</b> member input field. The <b>DHCPv4Reservation.bAllowedClientTypes</b>
ADM element is set to CLIENT_TYPE_BOTH. Insert the object in the <b>DHCPv4ReservationsList</b>
ADM element.</p>
</li><li><p><span><span> 
</span></span>If the <b>ElementType</b> member is set to DhcpReservedIps and
the previous steps resulted in a <b>DHCPv4Reservation</b> ADM element object
being inserted into the <b>DHCPv4Scope.DHCPv4ReservationsList</b> ADM element,
construct a temporary DHCPv4 client unique ID (section <a href="651865ec-6404-4191-ad30-113578a94556" data-linktype="relative-path">2.2.1.2.5.2</a>) by combining
the <b>DHCPv4Scope.ScopeInfo.SubnetAddress</b> ADM element and the <b>ReservedForClient</b>
member input field. If a <b>DHCPv4Client</b> ADM element object corresponding
to the <b>ReservedForClient</b> member input field and the temporary unique ID
does not exist within the <b>DHCPv4Scope.DHCPv4ClientsList</b> ADM element,
create one and insert it into the list, thereby marking the address as
unavailable to other clients. The <b>DHCPv4Client</b> ADM element object is
initialized as follows:</p>
<ul><li><p><span><span>  </span></span>The
<b>DHCPv4Client.ClientIpAddress</b> ADM element is set to the <b>ReservedIpAddress</b>
member input field.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.SubnetMask</b> ADM element is set to the <b>DHCPv4Scope.Scopeinfo.SubnetMask</b>
ADM element.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.ClientHardwareAddress</b> ADM element is set to the temporary
DHCPv4 client unique ID constructed above.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.ClientLeaseExpires</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.ClientName</b> ADM element is set to NULL.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.ClientComment</b> ADM element is set to NULL.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.OwnerHost.NetBiosName</b> ADM element is set to the <a href="a9d6a415-4de6-4058-befe-ca2e42764485#gt_b86c44e6-57df-4c48-8163-5e3fa7bdcff4" data-linktype="relative-path">NetBIOS</a> name of the DHCPv4
server.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.OwnerHost.IpAddress</b> ADM element is set to 255.255.255.255.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.bClientType</b> ADM element is set to CLIENT_TYPE_NONE.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.AddressState</b> ADM element is set to ADDRESS_STATE_ACTIVE.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.QuarantineCapable</b> ADM element is set to FALSE.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.Status</b> ADM element is set to NOQUARANTINE.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.ProbationEnds</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.SentPotExpTime</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.AckPotExpTime</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.RecvPotExpTime</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.StartTime</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.CltLastTransTime</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.LastBndUpdTime</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.flags</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.bndMsgStatus</b> ADM element is set to 0.</p>
</li><li><p><span><span>  </span></span>The
<b>DHCPv4Client.PolicyName</b> ADM element is set to NULL.</p>
</li></ul></li><li><p><span><span> 
</span></span>In continuation of the previous step, if the <b>ReservedIp</b>
member input field falls within the limits of a range element contained in the <b>DHCPv4Scope.DHCPv4IpRangesList</b>
ADM element, then set the bit corresponding to the IPv4 address in that <b>DHCPv4IpRange.Bitmask</b>
ADM element to 1 to indicate the unavailability of the address when selecting a
fresh address for allocation to DHCPv4 clients.</p>
</li></ul><p><b>Exceptions Thrown:</b> No exceptions are thrown beyond
those thrown by the underlying RPC protocol <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>.</p></div>