Share via

3.1.4.13 R_DhcpSetOptionValue (Opnum 12)

  • Article

The R_DhcpSetOptionValue method creates the option value when called for the first time. Otherwise, it modifies the option value for a specific option associated with the default user class and vendor class pair. The values can be set at the default, server, scope, multicast scope, or reservation level on the DHCPv4 server. The ScopeInfo parameter defines the level at which this option value is set. 

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

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 set or modified.

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, default, server, scope, multicast scope, or reservation level) at which this option value is set on.

OptionValue: A pointer to a DHCP_OPTION_DATA (section 2.2.1.2.24) structure that contains the option value to be set. For Dynamic DNS update settings, see section 3.3.1.

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.

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The specified DHCP client is not a reserved client.

The opnum field value for this method is 12.

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 the error ERROR_ACCESS_DENIED.

  • Validate the data pointed to by the OptionValue input parameter. If the Elements member of the DHCP_OPTION_DATA structure is NULL or the NumElements member is 0, return ERROR_INVALID_PARAMETER.

  • Iterate through the server ADM element DHCPv4OptionDefList, and retrieve the DHCPv4ClassedOptDefList ADM element corresponding to the DHCPv4OptionDef ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionDef ADM element entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Iterate through the DHCPv4ClassedOptDefList ADM element, and if there is no DHCPv4ClassedOptDef ADM element entry corresponding to the OptionID parameter, return ERROR_DHCP_OPTION_NOT_PRESENT.

  • If the ScopeInfo parameter contains DhcpDefaultOptions and if there is no DHCPv4ClassedOptDef ADM element entry corresponding to the OptionID parameter in the retrieved DHCPv4ClassedOptDef ADM element, return ERROR_DHCP_OPTION_NOT_PRESENT.

  • If the ScopeInfo parameter contains DhcpDefaultOptions, modify the DHCPv4ClassedOptDef ADM element entry with information in the OptionValue parameter. Return ERROR_SUCCESS (0x00000000).

  • If the ScopeInfo parameter contains DhcpGlobalOptions, iterate through the server 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 entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. If the DHCPv4ClassedOptValue ADM element entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of the retrieved DHCPv4ClassedOptValue ADM element, with information in OptionValue. Return ERROR_SUCCESS (0x00000000).

  • If the ScopeInfo parameter contains DhcpSubnetOptions, retrieve the DHCPv4Scope ADM element entry corresponding to the SubnetScopeInfo member of ScopeInfo parameter from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope ADM element is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT. Iterate through the 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 entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. If the DHCPv4ClassedOptValue ADM element entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of the retrieved DHCPv4ClassedOptValue ADM element with information in the OptionValue parameter. Return ERROR_SUCCESS (0x00000000).

  • If the ScopeInfo parameter contains DhcpReservedOptions, retrieve the DHCPv4Scope ADM element from the server DHCPv4ScopesList ADM element that contains the ReservedIpAddress member of the ScopeInfo parameter. If the DHCPv4Scope ADM element is not found, return ERROR_FILE_NOT_FOUND. 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.

    If the DHCPv4Scope entry ADM element is found and if the ScopeInfo.SubnetAddress ADM element does not match ScopeInfo's ReservedIpSubnetAddress member, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    Iterate through the 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 entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. If the DHCPv4ClassedOptValue entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of the retrieved DHCPv4ClassedOptValue ADM element with information in the OptionValue parameter. Return ERROR_SUCCESS (0x00000000).

  • 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_FILE_NOT_FOUND.

    Iterate through the 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 entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue ADM element entry corresponding to the OptionID parameter from the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. If the DHCPv4ClassedOptValue entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of the retrieved DHCPv4ClassedOptValue ADM element with information in OptionValue. Return ERROR_SUCCESS (0x00000000).

  • If the ScopeInfo parameter does not contain any valid scope type as specified in the preceding processing rules, return ERROR_INVALID_PARAMETER.

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