3.2.4.21 R_DhcpSetOptionValuesV5 (Opnum 20)

  • Article

The R_DhcpSetOptionValuesV5 method creates the option value when called for the first time, else it modifies it. It creates or modifies one or more options for a specific user class and vendor class. If the user class or the vendor class is not specified, the option values are set or modified for the default user class or vendor class. ScopeInfo defines the scope on which this option value is modified.

 DWORD R_DhcpSetOptionValuesV5(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in, string, unique] WCHAR* ClassName,
   [in, string, unique] WCHAR* VendorName,
   [in] LPDHCP_OPTION_SCOPE_INFO ScopeInfo,
   [in] LPDHCP_OPTION_VALUE_ARRAY OptionValues
 );

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

Flags:  This is of type DWORD that specifies that the option values are set for a specific or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

Option definitions are set for the default vendor class.

DHCP_FLAGS_OPTION_IS_VENDOR

0x00000003

If a bitwise AND operation with this bitmask yields a nonzero value, it indicates that the option definitions are set for a specific vendor class.

ClassName: A pointer to a null-terminated Unicode string that contains the name of the user class to which the option value is being set. This parameter is optional. If the ClassName parameter is not specified, the option values are set for the default user class.

VendorName: A pointer to a null-terminated Unicode string that contains the name of the vendor class to which the option value is being set. This parameter is optional. If a vendor class is not specified, the option values are set for a default vendor class.

ScopeInfo: This is a pointer to a DHCP_OPTION_SCOPE_INFO (section 2.2.1.2.41) structure that contains information describing the DHCPv4 scope this option value is set on. This value 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) that points to 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.

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.

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

The opnum field value for this method is 20.

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.

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

  • The Flags parameter MUST pass one of the validations given in the Flags field description. Otherwise, the method returns ERROR_INVALID_PARAMETER.

  • If ClassName is not NULL, retrieve the DHCPv4ClassDef entry corresponding to the ClassName from the server ADM element DHCPv4ClassDefList. If the DHCPv4ClassDef entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. If ClassName is NULL, it refers to the default user class (see section 3.1.1.9).

  • If VendorName is not NULL, retrieve the DHCPv4ClassDef entry corresponding to the VendorName from the server ADM element DHCPv4ClassDefList. If the DHCPv4ClassDef entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. If VendorName is NULL, it refers to the default vendor class (see section 3.1.1.9).

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

  • If ScopeInfo contains DhcpDefaultOptions, iterate through the server ADM element DHCPv4OptionDefList and retrieve DHCPv4OptionDef.DHCPv4ClassedOptDefList corresponding to the user and vendor class specified by ClassName and VendorName respectively. If ClassName or VendorName is NULL, it refers to the default user class or vendor class respectively, as specified in section 3.1.1.9. If the DHCPv4OptionValue entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Iterate through DHCPv4ClassedOptDefList and retrieve the DHCPv4ClassedOptDef entry corresponding to OptionID.

  • If ScopeInfo contains DhcpDefaultOptions, and if DHCPv4ClassedOptDef is not found, return ERROR_DHCP_OPTION_NOT_PRESENT.

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

  • If ScopeInfo contains DhcpGlobalOptions, iterate through the server ADM element DHCPv4ServerOptValueList and retrieve the DHCPv4OptionValue corresponding to the user and vendor class specified by ClassName and VendorName respectively. If ClassName or VendorName is NULL, it refers to the default user class or vendor class respectively, as specified in section 3.1.1.9. If the DHCPv4OptionValue entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue entry corresponding to the OptionID from DHCPv4OptionValue.DHCPv4ClassedOptValueList. If the DHCPv4ClassedOptValue entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of retrieved DHCPv4ClassedOptValue with information in Values for that OptionID, and return ERROR_SUCCESS.

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

  • If ScopeInfo contains DhcpSubnetOptions, iterate through DHCPv4Scope.DHCPv4ScopeOptValuesList and retrieve DHCPv4OptionValue corresponding to the user and vendor class specified by ClassName and VendorName respectively. If ClassName or VendorName is NULL, it refers to the default user class or vendor class respectively, as specified in section 3.1.1.9. If the DHCPv4OptionValue entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue entry corresponding to OptionID from DHCPv4OptionValue.DHCPv4ClassedOptValueList. If the DHCPv4ClassedOptValue entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of retrieved DHCPv4ClassedOptValue with information in Values for that OptionID, and return ERROR_SUCCESS.

  • If ScopeInfo contains DhcpMScopeOptions, retrieve the DHCPv4MScope entry corresponding to the ScopeInfo parameter from the server ADM element DHCPv4MScopesList. If the DHCPv4MScope entry is not found, return ERROR_FILE_NOT_FOUND.

  • If ScopeInfo contains DhcpMScopeOptions, iterate through DHCPv4MScope.DHCPv4MScopeOptValuesList and retrieve DHCPv4OptionValue corresponding to the user and vendor class specified by ClassName and VendorName respectively. If ClassName or VendorName is NULL, it refers to the default user class or vendor class respectively, as specified in section 3.1.1.9. If the DHCPv4OptionValue entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue entry corresponding to OptionID from DHCPv4OptionValue.DHCPv4ClassedOptValueList. If the DHCPv4ClassedOptValue entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of retrieved DHCPv4ClassedOptValue with information in Values for that OptionID, and return ERROR_SUCCESS.

  • If ScopeInfo contains DhcpReservedOptions, retrieve the DHCPv4Scope entry from the server ADM element DHCPv4ScopesList that contains the ReservedIpAddress field of the ScopeInfo parameter. If the DHCPv4Scope entry is not found, return ERROR_FILE_NOT_FOUND. Retrieve the DHCPv4Reservation entry from DHCPv4Scope.DHCPv4ReservationsList corresponding to ReservedIpAddress.

  • If ScopeInfo contains DhcpReservedOptions, and if ReservedIpAddress is not part of DHCPv4Scope, or if there is no DHCPv4Reservation corresponding to the ReservedIpAddress, return ERROR_DHCP_NOT_RESERVED_CLIENT.

  • If ScopeInfo contains DhcpReservedOptions, and if the DHCPv4Scope entry is found and if the ScopeInfo.SubnetAddress does not match with ScopeInfo's ReservedIpSubnetAddress field, then return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If ScopeInfo contains DhcpReservedOptions, iterate through DHCPv4Reservation.DHCPv4ResvOptValuesList and retrieve DHCPv4OptionValue corresponding to the user and vendor class specified by ClassName and VendorName respectively. If ClassName or VendorName is NULL, it refers to the default user class or vendor class respectively, as specified in section 3.1.1.9. If the DHCPv4OptionValue entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. Retrieve the DHCPv4ClassedOptValue entry corresponding to OptionID from DHCPv4OptionValue.DHCPv4ClassedOptValueList. If the DHCPv4ClassedOptValue entry is not found, return ERROR_DHCP_OPTION_NOT_PRESENT. Modify the Value member of retrieved DHCPv4ClassedOptValue with information in Values for that OptionID, and return ERROR_SUCCESS.

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