3.1.4.1 R_DhcpCreateSubnet (Opnum 0)

  • Article

The R_DhcpCreateSubnet method is used to create a new IPv4 subnet on the DHCPv4 server.

 DWORD R_DhcpCreateSubnet(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, ref] LPDHCP_SUBNET_INFO SubnetInfo
 );

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

SubnetAddress: A DHCP_IP_ADDRESS that contains the IPv4 subnet address.

SubnetInfo: This is a pointer to a structure of type LPDHCP_SUBNET_INFO (section 2.2.1.2.8) that contains information about the IPv4 subnet, including the IPv4 subnet mask and the IPv4 address of the subnet. The structure DHCP_HOST_INFO (section 2.2.1.2.7) (referred by PrimaryHost) stored in SubnetInfo MUST be ignored by both the caller and the server.

This method does not perform any checks to ensure that the SubnetState field in SubnetInfo is as specified in DHCP_SUBNET_STATE (section 2.2.1.1.2). It is the caller's responsibility to ensure that a valid SubnetState value is passed to this method in SubnetInfo. If SubnetState does not contain a valid value, as specified in DHCP_SUBNET_STATE), the behavior is undefined.

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.

0x00004E54

ERROR_DHCP_SUBNET_EXISTS

The IPv4 scope parameters are incorrect. Either the IPv4 scope already exists, corresponding to the SubnetAddress and SubnetMask members of the structure DHCP_SUBNET_INFO (section 2.2.1.2.8), or there is a range overlap of IPv4 addresses between those associated with the SubnetAddress and SubnetMask fields of the new IPv4 scope and the subnet address and mask of an already existing IPv4 scope.

The opnum field value for this method is 0.

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

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

  • If the SubnetAddress input field is 0, return ERROR_INVALID_PARAMETER.

  • If the SubnetInfo input parameter is NULL, return ERROR_INVALID_PARAMETER.

  • If the SubnetAddress input field is not the same as the SubnetAddress member of the SubnetInfo input field, return ERROR_INVALID_PARAMETER.

  • If the bitwise AND operation of the SubnetAddress input field with the SubnetMask member of the SubnetInfo input field is not the same as the SubnetAddress input field, return ERROR_INVALID_PARAMETER.

  • Iterate through the server ADM element DHCPv4ScopesList, and validate that the range of IPv4 addresses that correspond to the specified SubnetAddress and SubnetMask fields of SubnetInfo does not overlap the range of IPv4 addresses that correspond to the subnet address and mask of any DHCPv4Scope ADM element entry present in the DHCPv4ScopesList ADM element. If an overlap is detected, return ERROR_DHCP_SUBNET_EXISTS.

  • Create a DHCPv4Scope ADM element object and insert it into the DHCPv4ScopesList ADM element. The DHCPv4Scope ADM element object is initialized as follows:

    • The DHCPv4Scope.ScopeInfo ADM element is initialized with the information contained in the SubnetInfo input parameter. The QuarantineOn member of the DHCPv4Scope.ScopeInfo ADM element is set to 0.

    • DHCPv4Scope.DelayOffer ADM element is set to 0.

    • DHCPv4Scope.SuperScopeId ADM element is set to 0.

    • DHCPv4Scope.DHCPv4IpRangesList ADM element is set to empty list.

    • DHCPv4Scope.DHCPv4ExclusionRangesList ADM element is set to empty list.

    • DHCPv4Scope.DHCPv4ReservationsList ADM element is set to empty list.

    • DHCPv4Scope.DHCPv4ClientsList ADM element is set to empty list.

    • DHCPv4Scope.DHCPv4OptionValuesList ADM element is set to empty list.

  • Return ERROR_SUCCESS.

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