Share via

3.2.4.109 R_DhcpV4CreatePolicy (Opnum 108)

  • Article

The R_DhcpV4CreatePolicy method creates the policy according to the data specified in the policy data structure.

 DWORD R_DhcpV4CreatePolicy(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] LPDHCP_POLICY pPolicy
 );

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

pPolicy: This is a pointer to a type DHCP_POLICY (section 2.2.1.2.110) and contains the members of the policy to be created.

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 IP range is not contained within the IP address range of the scope, or the specified policy IP range is invalid.

0x00004E89

ERROR_DHCP_POLICY_EXISTS

The specified policy name exists at the specified level (server or scope).

0x00004E8A

ERROR_DHCP_POLICY_RANGE_EXISTS

The specified policy IP range overlaps the policy IP 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.

0x00004EAC

ERROR_DHCP_POLICY_FQDN_RANGE_UNSUPPORTED

Ranges are not allowed to be set on the given policy.

The opnum field value for this method is 108.

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

  • Check whether the PolicyName, Conditions, Expressions, or Ranges member inside the pPolicy parameter is NULL. If any of these is NULL, return ERROR_INVALID_PARAMETER.

  • Check whether the NumElements member of the Conditions member or the Expressions member inside the pPolicy parameter is 0. If any of these is 0, return ERROR_INVALID_PARAMETER.

  • Check whether the Elements member of the Conditions member or the Expressions member inside the pPolicy parameter is NULL. If any of these is NULL, return 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 the Conditions member and the Expressions member in the pPolicy parameter data structure by returning ERROR_DHCP_INVALID_POLICY_EXPRESSION if any of the following are true:

    • For each condition element in the Conditions member in the pPolicy parameter<75>:

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

      • If the Type member is not set to one of the values defined for the DHCP_POL_ATTR_TYPE (section 2.2.1.1.23) 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 set to the DhcpAttrOption value of the DHCP_POL_ATTR_TYPE enumeration, and the OptionID member is not equal to the vendor class identifier option (60), the user class identifier option (77), the client identifier option (61), or the relay agent information option (82), or the SubOptionID member is not equal to 0

      • If the Type member is set to the DhcpAttrSubOption value of the DHCP_POL_ATTR_TYPE enumeration and 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 (12), agent remote ID suboption (2), or subscriber ID suboption (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 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<76>

      • If there are other conditions with the ParentExpr member that are the same as this condition and if:

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

        • The OptionID member or the SubOptionID member or the Type member or the 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 of all other conditions (with the same ParentExpr member) is not set to the DhcpCompEqual, DhcpCompBeginsWith, or DhcpCompEndsWith value of the DHCP_POL_COMPARATOR enumeration<77>

        • If the Operator member for the condition element is not set to the DhcpCompNotEqual value of the DHCP_POL_COMPARATOR enumeration, the operator 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.<78>

    • For each expression in the Expressions member:

      • If the NumElements member is 0, there are no other Expressions members or Conditions members that have the index of this expression element in their ParentExpr member.

      • If the Operator member of the 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 DhcpLogicalAnd enumeration value

  • Validate the Ranges member of the pPolicy parameter according to the following:

    • If the IsGlobalPolicy member of the pPolicy parameter is TRUE, indicating that this is a server level policy, check whether the NumElements member of the Ranges member of the pPolicy parameter is 0. Return ERROR_DHCP_RANGE_INVALID_IN_SERVER_POLICY if the NumElements member of the Ranges member is not 0.

    • If the IsGlobalPolicy member of the pPolicy parameter is TRUE and the Subnet member of the pPolicy parameter is not 0, return ERROR_INVALID_PARAMETER.

    • If the IsGlobalPolicy member of the pPolicy parameter is FALSE and the Subnet member of the pPolicy parameter is 0, return ERROR_INVALID_PARAMETER.

    • If the IsGlobalPolicy member of the pPolicy parameter is FALSE and the Subnet member of the pPolicy parameter is not 0, perform the following checks:

      • If the StartAddress member of any of the Ranges member elements specified is greater than the EndAddress member, return ERROR_DHCP_POLICY_RANGE_BAD.

      • If any of the Ranges member elements in the pPolicy parameter is overlapping another Ranges member element in the pPolicy parameter, return ERROR_DHCP_POLICY_RANGE_BAD.

    • If the Conditions member contains a condition element 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_FQDN_RANGE_UNSUPPORTED.<79>

  • Validate the PolicyName member of the pPolicy parameter according to the following:

    • If the IsGlobalPolicy member of the pPolicy parameter is set to TRUE, retrieve the server ADM element DHCPv4ServerPolicyList and check whether any of the policies have the same name as the name specified in the PolicyName member of the pPolicy parameter. Return ERROR_DHCP_POLICY_EXISTS if there is a server policy by the same name.

    • If the IsGlobalPolicy member of the pPolicy parameter is set to FALSE and a Subnet member of the pPolicy parameter is specified, retrieve the server ADM element DHCPv4ScopesList. Retrieve the DHCPv4Scope ADM element from the DHCPv4ScopesList ADM element where the SubnetAddress ADM element member in the ScopeInfo ADM element of the DHCPv4Scope ADM element is the same as the Subnet member in the pPolicy parameter. If there is no DHCPv4Scope ADM element that matches the Subnet member address of the pPolicy parameter, return ERROR_DHCP_SUBNET_NOT_PRESENT. Retrieve the DHCPv4Scope.DHCpv4ScopePolicyList ADM element for the matched DHCPv4Scope ADM element. Check whether the DHCPv4Policy.Policy.PolicyName ADM element of any of the policies in the DHCPv4Scope.DHCPv4ScopePolicyList ADM element is the same as the PolicyName member in the pPolicy parameter. Return ERROR_DHCP_POLICY_EXISTS if there is a policy by the same name.

  • Validate the Ranges member of the pPolicy parameter according to the following:

    • Retrieve the DHCPv4Scope ADM element for the Subnet member address specified in the pPolicy parameter. Retrieve the DHCPv4Scope.DHCPv4ScopeIPRangesList ADM element. Check whether the Ranges member specified in the pPolicy parameter is within at least one of the DHCPv4IPRange ADM elements in the DHCPv4Scope.DHCPv4ScopeIPRangesList ADM element. Return ERROR_DHCP_POLICY_RANGE_BAD if this check fails.

    • Retrieve the DHCPv4Scope.DHCPv4ScopePolicyList ADM element. For each DHCPv4Policy ADM element in the DHCPv4Scope.DHCPv4ScopePolicyList ADM element, retrieve the DHCPv4Policy.Policy.Ranges ADM element member. Check whether each range element in the Ranges member specified in the pPolicy parameter overlaps any of the Range ADM element members in the DHCPv4Policy.Policy.Ranges ADM element. Return ERROR_DHCP_POLICY_RANGE_EXISTS if the check succeeds.

  • Validate the ProcessingOrder member of the pPolicy parameter according to the following:

    • If this is a scope level policy, retrieve the DHCPv4Scope ADM element for the Subnet member address specified in the pPolicy parameter. Get the maximum ProcessingOrder ADM element of all the DHCPv4Policy ADM elements in the DHCPv4Scope.DHCPv4ScopePolicyList ADM element. If the ProcessingOrder member in the pPolicy parameter is greater than the maximum ProcessingOrder ADM element plus 1, return ERROR_DHCP_INVALID_PROCESSING_ORDER.

    • If this is a server level policy, retrieve the server ADM element DHCPv4ServerPolicyList. Get the maximum ProcessingOrder ADM element of all the DHCPv4Policy ADM elements in the DHCPv4ServerPolicyList ADM element. If the ProcessingOrder member in the pPolicy parameter is greater than the maximum processing order plus 1, return ERROR_DHCP_INVALID_PROCESSING_ORDER.

  • For each condition element in the Conditions member in the pPolicy parameter, retrieve the server ADM element DHCPv4ClassDefList and check whether the VendorName member of the condition exists in the DHCPv4ClassDefList ADM element. If the vendorname member specified does not exist in the DHCPv4ClassDefList ADM element, return ERROR_DHCP_CLASS_NOT_FOUND.

  • Create a DHCPv4Policy ADM element, and populate the ADM elements of DHCPv4Policy with the members in the pPolicy parameter.

  • If the pPolicy 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 value is set to FALSE and whose DHCPv4ClassDef.ClassData value is the same as the Value member of that condition. If such a DHCPv4ClassDef object exists, set the object's DHCPv4Policy.ClassName to the DHCPv4ClassDef.ClassName of the retrieved user class. Otherwise, set DHCPv4Policy.ClassName to NULL.

  • If the IsGlobalPolicy member is TRUE, add the DHCPv4Policy ADM element to the DHCPv4ServerPolicyList ADM element.

  • If the IsGlobalPolicy member is FALSE, retrieve the DHCPv4Scope ADM element for the subnet identified by the Subnet member address in the pPolicy parameter and add the DHCPv4Policy ADM element to the DHCPv4Scope.DHCPv4ScopePolicyList ADM element.

  • Modify the processing order of existing policies as follows:

    • If a scope level policy is being created, retrieve the DHCPv4Scope ADM element for the subnet identified by the Subnet member address in the pPolicy parameter. For policies in the DHCPv4Scope.DHCPv4ScopePolicyList ADM element whose DHCPv4Policy.Policy.ProcessingOrder ADM element is greater than or equal to the ProcessingOrder member specified in the pPolicy parameter, increment the ProcessingOrder ADM element by 1.

    • If a server level policy is being created, for policies in the DHCPv4ServerPolicyList ADM element whose DHCPv4Policy.Policy.ProcessingOrder ADM element is greater than or equal to the ProcessingOrder member specified in the pPolicy parameter, increment the ProcessingOrder ADM element by 1.

  • Return ERROR_SUCCESS.

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