3.1.4.25 R_DhcpSetOptionValues (Opnum 24)

The R_DhcpSetOptionValues method creates the option values when called for the first time. Otherwise, it modifies the option values of one or more options at a specified level for a default user class and vendor class pair (that is, at the default, server, scope, multicast scope, or IPv4 reservation level). The ScopeInfo parameter defines the scope on which these option values are modified. The extension of this method is R_DhcpSetOptionValuesV5 (section 3.2.4.21), which sets/modifies the option values of one or more options for a specific user class and vendor class pair.

 DWORD R_DhcpSetOptionValues(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref] LPDHCP_OPTION_SCOPE_INFO ScopeInfo,
   [in, ref] LPDHCP_OPTION_VALUE_ARRAY OptionValues
 );

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

ScopeInfo: This is a pointer to a DHCP_OPTION_SCOPE_INFO (section 2.2.1.2.41) structure that contains the level (that is, default, server, scope, multicast scope, or IPv4 reservation level) at which the option values are set.

OptionValues: This is a pointer of type DHCP_OPTION_VALUE_ARRAY (section 2.2.1.2.43) structure that points to the location that contains one or more option identifiers along with the values.

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 in 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 24.

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 NumElements member of the DHCP_OPTION_VALUE_ARRAY structure is 0, return ERROR_SUCCESS.

  • Validate the data pointed to by the input parameter OptionValues. If the Values member of the DHCP_OPTION_VALUE_ARRAY structure is NULL and the NumElements member is greater than 0, return ERROR_INVALID_PARAMETER.

  • For each Values member configured in the OptionValues parameter, take the following action:

    • If the ScopeInfo parameter contains DhcpDefaultOptions, iterate though the server Abstract Data Model (ADM) element DHCPv4OptionDefList and retrieve the DHCPv4ClassedOptDefList ADM element corresponding to the DHCPv4OptionDef ADM element entry whose UserClass and VendorClass ADM element fields are NULL. If DHCPv4OptionDef entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND.  Iterate through the DHCPv4ClassedOptDefList ADM element and retrieve the DHCPv4ClassedOptDef ADM element entry corresponding to OptionID member.

    • If the ScopeInfo parameter contains DhcpDefaultOptions, and if the DHCPv4ClassedOptDef ADM element is not found, return ERROR_DHCP_OPTION_NOT_PRESENT.

    • If the ScopeInfo parameter contains DhcpDefaultOptions, modify the DHCPv4ClassedOptDef ADM element entry with information in the Values member for that OptionID member, and return ERROR_SUCCESS.

    • If the ScopeInfo parameter contains DhcpGlobalOptions, iterate through the server ADM element DHCPv4ServerOptValueList and retrieve the DHCPv4OptionValue ADM element entry whose 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 member 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 Values member for that OptionID member, and return ERROR_SUCCESS.

    • If the ScopeInfo parameter contains DhcpSubnetOptions, retrieve the DHCPv4Scope ADM element entry corresponding to the ScopeInfo parameter from the server ADM element DHCPv4ScopesList ADM element. If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    • If ScopeInfo contains DhcpSubnetOptions, iterate through DHCPv4Scope.DHCPv4ScopeOptValuesList and retrieve the DHCPv4OptionValue ADM element entry whose 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 member 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 Values member for that OptionID member, and return ERROR_SUCCESS.

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

    • If the ScopeInfo parameter contains DhcpMScopeOptions, iterate through DHCPv4MScope.DHCPv4MScopeOptValuesList ADM element and retrieve the DHCPv4OptionValue ADM element entry whose 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 OptionID member 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 Values member for that OptionID member, and return ERROR_SUCCESS.

    • 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_FILE_NOT_FOUND. Retrieve the DHCPv4Reservation ADM element entry from the DHCPv4Scope.DHCPv4ReservationsList ADM element corresponding to the ReservedIpAddress member.

    • If the ScopeInfo parameter contains DhcpReservedOptions, and if the ReservedIpAddress member is not part of any 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 ScopeInfo parameter contains DhcpReservedOptions, and if the DHCPv4Scope ADM element entry is found, and if the ScopeInfo.SubnetAddress ADM element does not match the ScopeInfo parameter's ReservedIpSubnetAddress member, then return ERROR_DHCP_SUBNET_NOT_PRESENT.

    •  If the ScopeInfo parameter contains DhcpReservedOptions, iterate through DHCPv4Reservation.DHCPv4ResvOptValuesList ADM element and retrieve the DHCPv4OptionValue ADM element entry whose 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 entry corresponding to OptionID member from the DHCPv4OptionValue.DHCPv4ClassedOptValueList. 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 Values member for that OptionID member, and return ERROR_SUCCESS.

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