Share via

3.2.4.20 R_DhcpSetOptionValueV5 (Opnum 19)

  • Article

The R_DhcpSetOptionValueV5 method creates the option value, when called for the first time. Otherwise, it modifies the option value of a specific option on the DHCPv4 server for a specific user class and vendor class. ScopeInfo defines the scope on which this option value is set. If the user class or vendor class is not provided, a default user class or vendor class is taken.

 DWORD R_DhcpSetOptionValueV5(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in] DHCP_OPTION_ID OptionId,
   [in, string, unique] WCHAR* ClassName,
   [in, string, unique] WCHAR* VendorName,
   [in] LPDHCP_OPTION_SCOPE_INFO ScopeInfo,
   [in] LPDHCP_OPTION_DATA OptionValue
 );

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 value is set for a specific or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

Option definition is 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 definition is set for a specific vendor class.

OptionId: This is of type DHCP_OPTION_ID (section 2.2.1.2.3), containing the option identifier of the option being set or modified.

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 value is 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 the vendor class is not specified, the option value is 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.

OptionValue: A pointer to DHCP_OPTION_DATA (section 2.2.1.2.24) structure that contains the option value that is set for an option corresponding to the OptionId. For Dynamic DNS update settings, see section 3.3.1.

The method does not perform any checks to ensure that the OptionValue passed in is of the same OptionType as that of the option corresponding to the OptionId passed in. It is the responsibility of the caller to ensure that the correct OptionType is used for the OptionValue passed in. In case the OptionType of the OptionValue passed in is different from that of the option corresponding to the OptionId, the behavior is undefined.

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.

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

The opnum field value for this method is 19.

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

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

  • Validate the data pointed to by the input parameter OptionValue. If the Elements member of the DHCP_OPTION_DATA structure is NULL or the NumElements member is 0, return 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 vendor class (see section 3.1.1.11).

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

  • 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 there is no DHCPv4OptionDef entry corresponding to the specified user and vendor classes, return ERROR_DHCP_CLASS_NOT_FOUND. Iterate through the DHCPv4ClassedOptDefList and if there is no DHCPv4ClassedOptDef entry corresponding to OptionId, return ERROR_DHCP_OPTION_NOT_PRESENT.

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

  • If ScopeInfo contains DhcpDefaultOptions, modify the DHCPv4ClassedOptDef entry with information in OptionValue, and return ERROR_SUCCESS.

  • If ScopeInfo contains DhcpGlobalOptions, iterate through the server ADM element DHCPv4ServerOptValueList 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 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 OptionValue, and return ERROR_SUCCESS.

  • If ScopeInfo contains DhcpSubnetOptions, retrieve the DHCPv4Scope entry corresponding to ScopeInfo from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope ADM element is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT. 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 OptionValue, 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 the ReservedIpAddress is not part of any of the DHCPv4Scope, or if there is no DHCPv4Reservation corresponding to 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 the 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 OptionValue, 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 OptionValue, and return ERROR_SUCCESS.

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