3.1.4.16 R_DhcpRemoveOptionValue (Opnum 15)

  • Article

The R_DhcpRemoveOptionValue method removes the option value for a specific option on the DHCPv4 server for the default user class and vendor class. ScopeInfo defines the level (that is, server, scope, multicast scope, or IPv4 reservation level) on which this option value is removed.

 DWORD R_DhcpRemoveOptionValue(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_OPTION_ID OptionID,
   [in, ref] LPDHCP_OPTION_SCOPE_INFO ScopeInfo
 );

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

OptionID: This is of type DHCP_OPTION_ID (section 2.2.1.2.3), containing the option identifier for the option being removed.

ScopeInfo: This is a pointer to a DHCP_OPTION_SCOPE_INFO (section 2.2.1.2.41) structure that contains information describing the level (that is, server, scope, multicast scope, or IPv4 reservation level) from which this option value is removed.

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.

0x00004E2A

ERROR_DHCP_OPTION_NOT_PRESENT

The specified option definition does not exist on the DHCP server database.

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The specified DHCP client is not a reserved client.

The opnum field value for this method is 15.

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

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

  • If the ScopeInfo parameter contains DhcpDefaultOptions, return the error ERROR_INVALID_PARAMETER.

  • If the ScopeInfo parameter contains DhcpGlobalOptions, iterate through the server Abstract Data Model (ADM) element DHCPv4ServerOptValueList and retrieve the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionValue ADM element is not found, return ERROR_DHCP_OPTION_NOT_PRESENT, else retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. Go to the last step.

  • If the ScopeInfo parameter contains DhcpSubnetOptions, retrieve the DHCPv4Scope ADM element entry corresponding to the SubnetScopeInfo member of the ScopeInfo parameter from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT, else iterate through DHCPv4Scope.DHCPv4ScopeOptValuesList ADM element and retrieve the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionValue ADM element is not found, return ERROR_DHCP_OPTION_NOT_PRESENT, else retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. Go to the last step.

  • If the ScopeInfo parameter contains DhcpMScopeOptions, retrieve the DHCPv4MScope ADM element entry corresponding to the ScopeInfo parameter from the server ADM element DHCPv4MScopesList. If the DHCPv4MScope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT, else iterate through DHCPv4MScope.DHCPv4MScopeOptValuesList ADM element and retrieve the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionValue ADM element is not found, return ERROR_DHCP_OPTION_NOT_PRESENT, else retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. Go to the last step.

  • If the ScopeInfo parameter contains DhcpReservedOptions, retrieve the DHCPv4Scope ADM element entry from the server ADM element DHCPv4ScopesList that contains the ReservedIpAddress member of the ScopeInfo parameter. If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_NOT_RESERVED_CLIENT, else if the ScopeInfo.SubnetAddress ADM element does not match with the ScopeInfo's ReservedIpSubnetAddress member, return ERROR_DHCP_SUBNET_NOT_PRESENT, else retrieve the DHCPv4Reservation ADM element entry from the DHCPv4Scope.DHCPv4ReservationsList ADM element corresponding to the ReservedIpAddress member. If the ReservedIpAddress member is not part of the DHCPv4Scope ADM element, or if there is no DHCPv4Reservation ADM element corresponding to the ReservedIpAddress member, return ERROR_DHCP_NOT_RESERVED_CLIENT, else iterate through DHCPv4Reservation.DHCPv4ResvOptValuesList ADM element and retrieve the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionValue ADM element is not found, return ERROR_DHCP_OPTION_NOT_PRESENT, else retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element.

  • If the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter is not present, then return ERROR_DHCP_OPTION_NOT_PRESENT.<30> Otherwise, delete the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4ClassedOptValueList ADM element, and return ERROR_SUCCESS.

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