The R_DhcpV4SetOptionValue method sets the option value for a policy at the specified level (scope or server).

  
 DWORD R_DhcpV4SetOptionValue(
     [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
     [in] DWORD Flags,
     [in] DHCP_OPTION_ID OptionID,
     [in, string, unique] WCHAR* PolicyName,
     [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	The 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.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

The 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 data type (section 2.2.1.2.3), containing the option ID of the option being set or modified.

PolicyName: A pointer to a null-terminated Unicode string that contains the name of the policy inside the subnet identified by the SubnetScopeInfo member of the ScopeInfo parameter for which the option value is being set.

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

ScopeInfo: This is a pointer to a type DHCP_OPTION_SCOPE_INFO structure (section 2.2.1.2.41) that contains information describing the DHCPv4 scope for which this option value is set. This value contains the server or scope level at which the option value is to be set.

OptionValue: A pointer to a type DHCP_OPTION_DATA structure (section 2.2.1.2.24) that contains the option value that is set for an option corresponding to the OptionId parameter.

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

Return Values: A 32-bit unsigned integer value that indicates return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully. Otherwise, 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 to 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.
0x00004E8FL ERROR_DHCP_POLICY_NOT_FOUND	The specified policy name does not exist.
0x00004EA8L ERROR_DHCP_POLICY_FQDN_OPIION_UNSUPPORTED	The option value cannot be specified because the policy contains an FQDN-based condition.

The opnum field value for this method is 101.

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

The Flags parameter MUST pass one of the validations given in the Flags parameter description. Otherwise, the method returns ERROR_INVALID_PARAMETER.
If the ScopeType member in the ScopeInfo parameter is DhcpReservedOptions enumeration value or DhcpMScopeOptions enumeration value and the PolicyName parameter is not NULL, the method returns ERROR_INVALID_PARAMETER.
Validate whether this method is authorized for read/write access as specified in section 3.5.5. If not, return ERROR_ACCESS_DENIED.
Validate whether the policy specified in the PolicyName parameter contains a condition of Type DhcpAttrFqdn or DhcpAttrFqdnSingleLabel, as defined in the DHCP_POL_ATTR_TYPE (section 2.2.1.1.23) enumeration. If it does, and if the value of the OptionId parameter does not specify DNS settings (81) or lease time (51), return ERROR_DHCP_POLICY_FQDN_OPTION_UNSUPPORTED.<73>
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 the VendorName parameter is not NULL, retrieve the DHCPv4ClassDef ADM element entry corresponding to the VendorName parameter from the server ADM element DHCPv4ClassDefList. If the DHCPv4ClassDef ADM element entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. If VendorName parameter is NULL, it refers to the default vendor class (see section 3.1.1.11).
If the ScopeType member in the ScopeInfo parameter is DhcpDefaultOptions:
- Iterate through the server ADM element DHCPv4OptionDefList and retrieve the DHCPv4OptionDef.DHCPv4ClassedOptDefList ADM element corresponding to the vendor class specified by the VendorName parameter. If there is no DHCPv4OptionDef ADM element entry corresponding to the specified vendor class, 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.
- Modify the DHCPv4ClassedOptDef entry with the information in the OptionValue parameter, and return ERROR_SUCCESS.
If the ScopeType member in the ScopeInfo parameter contains DhcpGlobalOptions enumeration value:
- Retrieve the server ADM element DHCPv4ServerPolicyList. Retrieve the DHCPv4Policy ADM element from the DHCPv4ServerPolicyList ADM element that has the same name as the PolicyName parameter. If there is no policy with the specified name, return ERROR_DHCP_POLICY_NOT_FOUND.
- Retrieve each DHCPv4PolicyOptionValue ADM element from the server ADM element DHCPv4ServerPolicyOptionValuesList. Get the DHCPv4PolicyOptionValue ADM element for which the DHCPv4PolicyOptionValue.PolicyName ADM element and the DHCPv4PolicyOptionValue.VendorName ADM element match the PolicyName parameter and the VendorName parameter passed to the method.
- From the DHCPv4PolicyOptionValue.DHCPv4ClassedOptionValues ADM element list, if there is a DHCPv4ClassedOptValue ADM element that contains the same OptionID ADM element as the OptionId parameter passed to the method, delete the DHCPv4ClassedOptValue ADM element.
- Create a DHCPv4ClassedOptValue ADM element with the OptionID ADM element set to the OptionId parameter passed to the method and the data member of the DHCPv4ClassedOptValue ADM element set to the OptionValue parameter passed to the method.
- Add the created DHCPv4ClassedOptValue ADM element to the DHCPv4PolicyOptionValue.DHCPv4ClassedOptionValues ADM element list, and return ERROR_SUCCESS.
If the ScopeInfo parameter contains the SubnetScopeInfo member:
- Retrieve the server ADM element DHCPv4ScopesList. Retrieve the DHCPv4Scope ADM element that contains the same IP address as the IP address in the SubnetScopeInfo member. If there is no scope with the specified IP address, return ERROR_DHCP_SUBNET_NOT_PRESENT.
- Retrieve the DHCPv4Scope.DHCPv4ScopePolicyList ADM element. Retrieve the DHCPv4Policy ADM element from the DHCPv4Scope.DHCPv4ScopePolicyList ADM element with the specified PolicyName ADM element. If there is no policy with the specified name, return ERROR_DHCP_POLICY_NOT_FOUND.
- Retrieve each DHCPv4PolicyOptionValue ADM element from the DHCPv4Scope ADM element DHCPv4Scope.DHCPv4ScopePolicyOptionValuesList. Get the DHCPv4PolicyOptionValue ADM element for which the DHCPv4PolicyOptionValue.PolicyName ADM element and the DHCPv4PolicyOptionValue.VendorName ADM element match the PolicyName parameter and the VendorName parameter passed to the method.
- From the DHCPv4PolicyOptionValue.DHCPv4ClassedOptionValues ADM element list, if there is a DHCPv4ClassedOptValue ADM element that contains the same OptionID ADM element as the OptionId parameter passed to the method, delete the DHCPv4ClassedOptValue ADM element.
- Create a DHCPv4ClassedOptValue ADM element with the OptionID ADM element set to the OptionId parameter passed to the method and the data member of the DHCPv4ClassedOptValue ADM element set to the OptionValue parameter passed to the method.
- Add the created DHCPv4ClassedOptValue ADM element to the DHCPv4PolicyOptionValue.DHCPv4ClassedOptionValues ADM element list, and return ERROR_SUCCESS.

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