3.2.4.111 R_DhcpV4SetPolicy (Opnum 110)

The R_DhcpV4SetPolicy method modifies the specified DHCPv4 policy.

 DWORD R_DhcpV4SetPolicy(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD FieldsModified,
   [in] BOOL ServerPolicy,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in, unique, string] LPWSTR PolicyName,
   [in] LPDHCP_POLICY Policy
 );

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

FieldsModified: This is of type DWORD and contains the bit mask that specifies the fields to be modified as specified in the DHCP_POLICY_FIELDS_TO_UPDATE enumeration (section 2.2.1.1.21).

ServerPolicy: This is of type BOOL and specifies whether the server policy or scope policy is being modified.

SubnetAddress: This is of type DHCP_IP_ADDRESS data type (section 2.2.1.2.1) and identifies the IPv4 subnet from which the policy is being modified.

PolicyName: A pointer to a null-terminated Unicode string that contains the name of the policy requested.

Policy: This is a pointer to a type DHCP_POLICY structure (section 2.2.1.2.110) that contains the policy data to be modified.

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.

0x00004E8C

ERROR_DHCP_RANGE_INVALID_IN_SERVER_POLICY

A policy range has been specified for a server level policy.

0x00004E8D

ERROR_DHCP_INVALID_POLICY_EXPRESSION

The specified conditions or expressions of the policy are invalid.

0x00004E8B

ERROR_DHCP_POLICY_RANGE_BAD

The specified policy range is not contained within the IP address range of the scope, or the specified policy range is invalid.

0x00004E89

ERROR_DHCP_POLICY_NOT_FOUND

The specified policy name does not exist at the specified level (server or scope).

0x00004E8A

ERROR_DHCP_POLICY_RANGE_EXISTS

The specified policy range overlaps the policy ranges of an existing policy at the specified scope.

0x00004E8E

ERROR_DHCP_INVALID_PROCESSING_ORDER

The specified processing order is greater than the maximum processing order of the existing policies at the specified level (server or scope).

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The vendor class or user class reference in the conditions of the policy does not exist.

0x00004EA9

ERROR_DHCP_POLICY_EDIT_FQDN_UNSUPPORTED

A FQDN-based condition is being added to a policy that has ranges or options configured.

The opnum field value for this method is 110.

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

  • If the ServerPolicy parameter is TRUE and the SubnetAddress parameter is not NULL, return ERROR_INVALID_PARAMETER.

  • If the ServerPolicy parameter is FALSE and the SubnetAddress parameter is NULL, return ERROR_INVALID_PARAMETER.

  • If the PolicyName parameter is NULL or if the Policy parameter is NULL, return ERROR_INVALID_PARAMETER.

  • Validate whether this method is authorized for write/read access as specified in section 3.5.5. If not, return ERROR_ACCESS_DENIED.

  • If the ServerPolicy parameter is TRUE, retrieve the DHCPv4ServerPolicyList ADM element and get the DHCPv4Policy ADM element from the DHCPv4ServerPolicyList ADM element for the specified PolicyName parameter. If there is no policy with the specified name, return ERROR_DHCP_POLICY_NOT_FOUND.

  • If the ServerPolicy parameter is FALSE, retrieve the DHCPv4ScopesList ADM element and get the DHCPv4Scope ADM element from the DHCPv4ScopesList ADM element where the SubnetAddress ADM element member in the DHCPv4Scope ADM element matches the specified SubnetAddress parameter. If there is no DHCPv4Scope ADM element that has the specified SubnetAddress parameter value, return ERROR_DHCP_SUBNET_NOT_PRESENT. Retrieve the DHCPv4Scope.DHCPv4ScopePolicyList ADM element, and get the DHCPv4Policy ADM element from the DHCPv4Scope.DHCPv4ScopePolicyList ADM element that has the same name as the specified PolicyName parameter. If there is no policy with the specified name, return ERROR_DHCP_POLICY_NOT_FOUND.

  • If the DhcpUpdatePolicyRanges enumeration value bit in the FieldsModified parameter is set:

    • If the Ranges member inside the Policy parameter is NULL, return ERROR_INVALID_PARAMETER.

    • If the ServerPolicy parameter is TRUE and the NumElements member in the Ranges member of the Policy parameter is not 0, return ERROR_DHCP_RANGE_INVALID_IN_SERVER_POLICY.

    • If the StartAddress member of any of the Ranges members in the pPolicy parameter is greater than the EndAddress member, return ERROR_DHCP_POLICY_RANGE_BAD.

    • If any of the Ranges member array element addresses in the pPolicy parameter overlaps any other Ranges member array element addresses in the pPolicy parameter, return ERROR_DHCP_POLICY_RANGE_BAD.

    • If the updated policy contains a Conditions member that includes a condition where the Type is set to the value DhcpAttrFqdn or DhcpAttrFqdnSingleLabel as defined in the DHCP_POL_ATTR_TYPE (section 2.2.1.1.23) enumeration, and the NumElements member of the Ranges member is not 0, return ERROR_DHCP_POLICY_EDIT_FQDN_UNSUPPORTED.<80>

    • Retrieve the DHCPv4Scope.DHCPv4IPRangesList ADM element. Check whether the Ranges member specified is within at least one of the DHCPv4IPRange ADM elements in the DHCPv4Scope.DHCPv4IPRangesList ADM element. Return ERROR_DHCP_POLICY_RANGE_BAD if this check fails.

    • Retrieve the DHCPv4Policy.Policy.Ranges ADM element. Check whether the Range elements in the Ranges member specified in the Policy parameter overlap any of the Range ADM elements in the DHCPv4Policy.Policy.Ranges ADM element. Return ERROR_DHCP_POLICY_RANGE_EXISTS if the check succeeds.

    • If the DhcpUpdatePolicyExpr enumeration value bit in the FieldsModified parameter is set:

      • If the Expressions member or Conditions member of the Policy parameter is NULL or the NumElements member in the Expressions member or in the Conditions member are 0, return ERROR_DHCP_INVALID_POLICY_EXPRESSION.

      • If the Conditions member includes a condition where the Type is set to the value DhcpAttrFqdn or DhcpAttrFqdnSingleLabel as defined in the DHCP_POL_ATTR_TYPE enumeration, the updated policy MUST be validated to ensure that it does not contain any ranges or any options apart from the options that specify DNS settings (81) and lease time (51). If the validation fails, return ERROR_DHCP_POLICY_EDIT_FQDN_UNSUPPORTED.<81>

      • For each condition element in the Conditions member in the Policy parameter:<82>

        • If the ParentExpr member in the Conditions member is greater than the NumElements member in the Expressions member

        • If the Type member is not one of the values defined for the DHCP_POL_ATTR_TYPE enumeration

        • If the Type member is not set to the DhcpAttrOption or DhcpAttrSubOption value of the DHCP_POL_ATTR_TYPE enumeration, and the values for both the OptionID and SubOptionID members are not 0

        • If the Type member is not set to the DhcpAttrOption value of the DHCP_POL_ATTR_TYPE enumeration; the OptionID member is not equal to the vendor class identifier option (60), user class identifier option (77), client identifier option (61), or relay agent information option (82); or the SubOptionID member is not equal to 0

        • If the Type member is not set to the DhcpAttrSubOption value of the DHCP_POL_ATTR_TYPE enumeration, the OptionID member is not equal to the relay agent information option (82), or the SubOptionID member is not equal to the agent circuit ID suboption (2), agent remote ID suboption (2), or subscriber ID suboption

        • If the Type member is set to the DhcpAttrHWAddr value of the DHCP_POL_ATTR_TYPE enumeration, and the Operator member is set to the DhcpCompEqual or DhcpCompNotEqual value of the DHCP_POL_COMPARATOR (section 2.2.1.1.22) enumeration, and the ValueLength member is not equal to 6

        • If the Type member is set to the DhcpAttrHWAddr value of the DHCP_POL_ATTR_TYPE enumeration, and the Operator member is set to the DhcpCompBeginsWith, DhcpCompNotBeginWith, DhcpCompEndsWith, or DhcpCompNotEndWith value of the DHCP_POL_COMPARATOR enumeration, and the ValueLength member is equal to or greater than 6<83>

        • If there are other Conditions member array elements with the ParentExpr member having the same condition, and if

          • The OptionID member is the relay agent information option (82)

          • The OptionID member or SubOptionID member or Type member or VendorName member is different for the conditions

          • If the Operator member for the condition is set to the DhcpCompEqual value of the DHCP_POL_COMPARATOR enumeration, the Operator member of all other conditions (with the same ParentExpr member) is not set to the DhcpCompEqual, DhcpCompBeginsWith, or DhpcCompEndsWith value of the DHCP_POL_COMPARATOR enumeration<84>

          • If the Operator member for the condition is set to the DhcpCompNotEqual value of the DHCP_POL_COMPARATOR enumeration, the Operator member of all other conditions (with the same ParentExpr member) is not set to the DhcpCompNotEqual, DhcpCompNotBeginWith, or DhcpCompNotEndWith value of the DHCP_POL_COMPARATOR enumeration<85>

            For each expression element in the Expressions member:

          • If there are no other expression elements or condition elements that have the index of this expression element in their ParentExpr member

          • If the Operator member of an expression element is not the DhcpLogicalAnd enumeration value or DhcpLogicalOr enumeration value

          • If the ParentExpr member value is not 0

            If the expression element is not the first element in the array and if the Operator member of the expression is not the DhcpLogicalAnd enumeration value

            Return ERROR_DHCP_INVALID_POLICY_EXPRESSION.

  • If the DhcpUpdatePolicyOrder enumeration value bit in the FieldsModified parameter is set, if scope level policy is being modified, get the maximum ProcessingOrder ADM element of all the DHCPv4Policy ADM elements in the DHCPv4Scope.DHCPv4ScopePolicyList ADM element. If the ProcessingOrder member in the Policy parameter is greater than the maximum ProcessingOrder ADM element plus 1, return ERROR_DHCP_INVALID_PROCESSING_ORDER. Perform the same step for DHCPv4ServerPolicyList if server level policy is being modified.

  • If the DhcpUpdatePolicyName enumeration value bit in the FieldsModified parameter is set, and if the PolicyName parameter is NULL, return ERROR_INVALID_PARAMETER.

  • Update the server or scope level DHCPv4Policy ADM element retrieved earlier according to the following:

    • If the DhcpUpdatePolicyName enumeration value is set in the FieldsModified parameter, update the name of the policy in the DHCPv4Policy.Policy.PolicyName ADM element.

    • If the DhcpUpdatePolicyOrder enumeration value is set in the FieldsModified parameter, update the processing order of the policy in the DHCPv4Policy.Policy.ProcessingOrder ADM element.

    • If the DhcpUpdatePolicyExpr enumeration value is set in the FieldsModified parameter:

      • Update the policy expressions in the DHCPv4Policy.Expressions ADM element and the policy conditions in the DHCPv4Policy.Conditions ADM element.

      • If the Policy parameter contains only one condition record with the Operator member set to DhcpCompEqual, iterate over the global ADM element DHCPv4ClassDefList and retrieve a DHCPv4ClassDef ADM object whose DHCPv4ClassDef.IsVendor is FALSE and whose DHCPv4ClassDef.ClassData is the same as the Value member of that condition. If such a DHCPv4ClassDef object exists, set the object's DHCPv4Policy.ClassName value to the DHCPv4ClassDef.ClassName of the retrieved user class. Otherwise, set DHCPv4Policy.ClassName to NULL.

    • If the DhcpUpdatePolicyRanges enumeration value is set in the FieldsModified parameter, update the IP ranges of the policy in the DHCPv4Policy.Policy.Ranges ADM element.

    • If the DhcpUpdatePolicyStatus enumeration value is set in the FieldsModified parameter, update the state (enabled/disabled) of the policy in DHCPv4Policy.Policy.Enabled.

  • If the FieldsModified parameter is set to any value other than DhcpUpdatePolicyName, DhcpUpdatePolicyOrder, DhcpUpdatePolicyExpr, DhcpUpdatePolicyRanges, DhcpUpdatePolicyDescr, or DhcpUpdatePolicyStatus, as defined in the DHCP_POLICY_FIELDS_TO_UPDATE (section 2.2.1.1.21) enumeration, return ERROR_INVALID_PARAMETER.

  • Return ERROR_SUCCESS.

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