The method R_DhcpV4EnumPolicies returns an enumerated list of all configured server level policies or scope level policies. The caller of this function can free the memory pointed to by the EnumInfo parameter by calling the function midl_user_free (section 3).

 DWORD R_DhcpV4EnumPolicies(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, out] LPDWORD ResumeHandle,
   [in] DWORD PreferredMaximum,
   [in] BOOL ServerPolicy,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [out] LPDHCP_POLICY_ARRAY EnumInfo,
   [out] DWORD* ElementsRead,
   [out] DWORD* ElementsTotal
 );

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

ResumeHandle: This is a pointer of type DWORD (see DHCP_RESUME_HANDLE data type, section 2.2.1.2.6) that identifies the enumeration operation. Initially, this value MUST be set to zero, with a successful call returning the handle value used for subsequent enumeration requests.

PreferredMaximum: This is of type DWORD specifying the preferred maximum number of policies to be returned. If the number of remaining unenumerated policies is less than the value of this parameter, then all the policies for the DHCPv4 server or for the specific subnet are returned. To retrieve all the policies on the DHCPv4 server or the specific subnet, 0xFFFFFFFF SHOULD be specified.

ServerPolicy: This is of type BOOL and indicates whether the server level policy or scope level policy is being requested.

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

EnumInfo: This is a pointer of type LPDHCP_POLICY_ARRAY (section 2.2.1.2.111) in which policy information is retrieved.

ElementsRead: This is a pointer to a DWORD value that specifies the number of policies returned in the EnumInfo parameter. The caller MUST allocate memory for this parameter that is equal to the size of the DWORD data type.

ElementsTotal: This is a pointer to a DWORD value that specifies the number of policies that have not yet been enumerated. The caller MUST allocate memory for this parameter that is equal to the size of the DWORD data type.

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 any generic failure.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The call was successful.
0x000000EA ERROR_MORE_DATA	There are more elements available to enumerate.
0x00000103 ERROR_NO_MORE_ITEMS	There are no more elements left to enumerate.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x000000EA

ERROR_MORE_DATA

There are more elements available to enumerate.

0x00000103

ERROR_NO_MORE_ITEMS

There are no more elements left to enumerate.

The opnum field value for this method is 112.

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

If the EnumInfo parameter, ResumeHandle parameter, ElementsRead parameter and ElementsTotal parameter are NULL, return ERROR_INVALID_PARAMETER.
If the ServerPolicy parameter is TRUE and SubnetAddress parameter is not NULL, return ERROR_INVALID_PARAMETER.
If the ServerPolicy parameter is FALSE and SubnetAddress parameter is NULL, return ERROR_INVALID_PARAMETER.
Validate whether this method is authorized for read access as specified in section 3.5.4. If not, return ERROR_ACCESS_DENIED.
If the ServerPolicy parameter is TRUE, retrieve the DHCPv4ServerPolicyList ADM element and start enumerating from the ResumeHandle parameter. If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the beginning of the DHCPv4ServerPolicyList ADM element.
If the ServerPolicy parameter is FALSE, retrieve the DHCPv4ScopesList ADM element and get the DHCPv4Scope ADM element from DHCPv4ScopesList ADM element where the SubnetAddress ADM element in DHCPv4Scope ADM element matches the specified SubnetAddress parameter. If the SubnetAddress parameter does not match any of the DHCPv4Scope ADM element entries in DHCPv4ScopesList ADM element return ERROR_DHCP_SUBNET_NOT_PRESENT. Retrieve the DHCPv4Scope.DHCPv4ScopePolicyList ADM element and start enumerating from the ResumeHandle parameter. If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the beginning of DHCPv4Scope.DHCPv4ScopePolicyList ADM element.
If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of the ResumeHandle parameter. If the ResumeHandle parameter is greater than or equal to the number of DHCPv4Policy ADM element objects in the retrieved list of policies, then return ERROR_NO_MORE_ITEMS.
If the PreferredMaximum parameter is 0 and the number of entries remaining in the retrieved list of policies is greater than 0, then ERROR_MORE_DATA is returned.
If the PreferredMaximum parameter is 0 and the number of entries remaining in the retrieved list of policies is 0, then ERROR_NO_MORE_ITEMS is returned.
The PreferredMaximum parameter specifies the maximum number of policies that the server can allocate and return to the caller containing the data related to the DHCPv4Policy ADM element objects. If PreferredMaximum parameter is 0xFFFFFFFF or if PreferredMaximum parameter is enough to accommodate all DHCPv4Policy ADM element objects from ResumeHandle parameter to end of the retrieved list of policies, allocate memory for a DHCP_POLICY_ARRAY structure for total number of DHCPv4Policy ADM element objects of type DHCP_POLICY structure from ResumeHandle parameter to the end of the retrieved list of policies. If, however, PreferredMaximum parameter is not enough to accommodate all DHCPv4Policy ADM element objects from ResumeHandle parameter to the end of the list, allocate memory for PreferredMaximum parameter number of policies.
Filter out policies from the list of policies which satisfy any of the following conditions based on the condition element in the Conditions member in the Policy:
- The Operator member is greater than the value of DhcpCompNotBeginWith as defined in the DHCP_POL_COMPARATOR (section 2.2.1.1.22) enumeration.
- The Type member is greater than the value of DhcpAttrSubOption as defined in the DHCP_POL_ATTR_TYPE (section 2.2.1.1.23) enumeration.
- The OptionId member is the relay agent information option (82) and the Operator member is greater than the value of DhcpCompNotEqual as defined in the DHCP_POL_COMPARATOR (section 2.2.1.1.22) enumeration.
This processing is performed to maintain backward compatibility with systems that do not support policies containing new information.<86>
Read the policy information from the retrieved list of policies starting from the ResumeHandle parameter, copy it into the allocated memory until the number of policies copied is equal to PreferredMaximum parameter and return it to the caller.
Fill the number of read DHCPv4Policy ADM element objects in ElementsRead parameter. Fill the number of DHCPv4Policy ADM element objects in the retrieved list of policies that have not yet been enumerated in the ElementsTotal parameter. Update the ResumeHandle parameter to the index of the DHCPv4Policy ADM element objects read plus one (+1). If there are more policies in the retrieved list of policies which are yet to be enumerated, return ERROR_MORE_DATA, else return ERROR_NO_MORE_ITEMS.

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