3.1.4.37 R_DhcpSetSuperScopeV4 (Opnum 36)

  • Article

The R_DhcpSetSuperScopeV4 method adds, modifies, or deletes the IPv4 subnet to/from the superscope information from the DHCPv4 server.

 DWORD R_DhcpSetSuperScopeV4(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, unique, string] WCHAR* SuperScopeName,
   [in] BOOL ChangeExisting
 );

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

SubnetAddress: This is of type DHCP_IP_ADDRESS (section 2.2.1.2.1), containing the IPv4 address of the subnet that is being set in a superscope or is removed from a superscope.

SuperScopeName: This is of a pointer of WCHAR that points to the location that contains the superscope name. If NULL is specified in this field, the subnet corresponding to the SubnetAddress parameter is removed from any superscope that it was part of.

ChangeExisting: This is a BOOL that MUST be set to TRUE if the IPv4 subnet is already part of any superscope.

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.

0x00004E24

ERROR_DHCP_SUBNET_EXITS

The specified IPv4 subnet already exists.

The opnum field value for this method is 36.

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 entry corresponding to the SubnetAddress parameter from the server ADM element DHCPv4ScopesList. If the required DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If the SuperScopeName parameter is specified as NULL, set the DHCPv4Scope.SuperScopeId ADM element to 0 and return ERROR_SUCCESS.

  • If the ChangeExisting parameter is set to FALSE and if DHCPv4Scope.SuperScopeId ADM element is nonzero, return ERROR_DHCP_SUBNET_EXITS.

  • Retrieve the DHCPv4SuperScope ADM element entry corresponding to the SuperScopeName parameter from the server ADM element DHCPv4SuperScopesList.

  • If the DHCPv4SuperScope ADM element entry is not found, create a DHCPv4SuperScope ADM element object and insert it into the DHCPv4SuperScopesList ADM element. The DHCPv4SuperScope ADM element object is initialized as follows:

    • The DHCPv4SuperScope.SuperScopeName ADM element is set to the SuperScopeName input parameter.

    • The DHCPv4SuperScope.SuperScopeId ADM element is set to the index of this entry in the DHCPv4SuperScopesList ADM element.

  • In the preceding DHCPv4Scope ADM element entry, set the DHCPv4Scope.SuperScopeId ADM element to the SuperScopeId ADM element member of the DHCPv4SuperScope ADM element entry corresponding to the SuperScopeName parameter, and then return ERROR_SUCCESS.

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