3.1.4.6 R_DhcpEnumSubnetElements (Opnum 5)

  • Article

The R_DhcpEnumSubnetElements method enumerates the list of a specific type of IPv4 subnet elements from a specific DHCPv4 IPv4 subnet. The caller of this function can free the memory pointed to by the EnumElementInfo parameter and its member the Elements array by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumSubnetElements(
     [in, unique, string]  DHCP_SRV_HANDLE  ServerIpAddress,
     [in]   DHCP_IP_ADDRESS      SubnetAddress,
     [in]   DHCP_SUBNET_ELEMENT_TYPE  EnumElementType,
     [in, out]   DHCP_RESUME_HANDLE     *ResumeHandle,
     [in]   DWORD PreferredMaximum,
     [out] LPDHCP_SUBNET_ELEMENT_INFO_ARRAY  *EnumElementInfo,
     [out]   DWORD *ElementsRead,
     [out]   DWORD *ElementsTotal
 );

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

SubnetAddress: This is of type DHCP_IP_ADDRESS (section 2.2.1.2.1), containing the IPv4 subnet ID from which subnet elements are enumerated.

EnumElementType: This is of type DHCP_SUBNET_ELEMENT_TYPE (section 2.2.1.1.7) enumeration, indicating the type of IPv4 subnet element to enumerate.

ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (section 2.2.1.2.6) a DWORD 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. For example, if the PreferredMaximum parameter is set to 1,000 bytes, and 2,000 bytes worth of IPv4 subnet elements are stored on the DHCPv4 server, the resume handle can be used after the first 1,000 bytes are retrieved to obtain the next 1,000 on a subsequent call, and so forth.

PreferredMaximum: This is of type DWORD that specifies the preferred maximum number of bytes to return. If the number of remaining unenumerated subnet elements (in bytes) is less than this value, all IPv4 subnet elements for a specific type are returned. To retrieve all the IPv4 subnet elements of a specific type, 0xFFFFFFFF is specified.

EnumElementInfo: This is a pointer of type LPDHCP_SUBNET_ELEMENT_INFO_ARRAY in which an IPv4 subnet element of type EnumElementType is returned for a specific IPv4 subnet SubnetAddress. If no IPv4 subnet element of a specific type is available for enumeration, this value is null.

ElementsRead: This is a pointer to a DWORD value that specifies the number of IPv4 subnet elements read in the EnumElementInfo parameter for a specific type of IPv4 subnet element. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

ElementsTotal: This is a pointer to a DWORD value that specifies the number of IPv4 subnet elements of a specific type from a specific IPv4 subnet that are not yet enumerated with respect to the resume handle that is returned. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

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.

0x000000EA

ERROR_MORE_DATA

There are more elements available to enumerate.

0x00000103

ERROR_NO_MORE_ITEMS

There are no more elements left to enumerate.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist.

The opnum field value for this method is 5.

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

  • Validate if this method is authorized for read access per section 3.5.4. If not, return the error ERROR_ACCESS_DENIED.

  • If the EnumElementType parameter is set to the DhcpSecondaryHosts enumeration value, return the error ERROR_NOT_SUPPORTED.

  • If the EnumElementType parameter is set to DhcpIpUsedClusters, DhcpIpRangesDhcpOnly, DhcpIpRangesDhcpBootp, or DhcpIpRangesBootpOnly, return the error ERROR_INVALID_PARAMETER.

  • Retrieve the server Abstract Data Model (ADM) element DHCPv4Scope entry corresponding to the SubnetAddress parameter from the server ADM element DHCPv4ScopesList.

  • If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If the EnumElementType parameter is set to DhcpIpRanges, retrieve all the entries in the DHCPv4Scope.DHCPv4IpRangesList ADM element, starting with the element at the index specified by the value in the ResumeHandle parameter and continuing while the total byte size of all retrieved IPv4 range elements is less than or equal to the PreferredMaximum parameter.

  • If the EnumElementType parameter is set to DhcpIpRanges and PreferredMaximum is 0, then return ERROR_NO_MORE_ITEMS.

  • If the EnumElementType parameter is set to DhcpIpRanges and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4IpRangesList ADM element.

  • If the EnumElementType parameter is set to DhcpIpRanges and the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle parameter is greater than or equal to the number of entries in the DHCPv4IpRangesList ADM element, then return ERROR_NO_MORE_ITEMS.

  • The PreferredMaximum parameter specifies the maximum number of bytes that the server can allocate and return to the caller containing the data related to the IPv4 ranges. If the EnumElementType parameter is set to DhcpIpRanges and PreferredMaximum is unable to hold all the entries being retrieved, then the server MUST store as many entries as will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA.

  • If the EnumElementType parameter is set to DhcpIpRanges, copy the RangeInfo ADM element field from the retrieved DHCPv4IpRange ADM element entries in the EnumElementInfo parameter, copy the number of read DHCPv4IpRange ADM element entries in the ElementsRead parameter, and copy the number of DHCPv4IpRange ADM element entries in the DHCPv4IpRangesList ADM element that are not yet enumerated in the ElementsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4IpRange ADM element entry read.

  • If the EnumElementType parameter is set to DhcpReservedIps, retrieve all the entries in the DHCPv4Scope.DHCPv4ReservationsList ADM element, starting with the element at the index specified by the value in the ResumeHandle parameter and continuing while the total byte size of all retrieved IPv4 reservation elements is less than or equal to the PreferredMaximum parameter.

  • If the EnumElementType parameter is set to DhcpReservedIps and the PreferredMaximum parameter is 0, and the number of entries in the DHCPv4ReservationsList ADM element retrieved based on the EnumElementType parameter is greater than 0, then return ERROR_MORE_DATA.

  • If the EnumElementType parameter is set to DhcpReservedIps, PreferredMaximum parameter is 0, and the number of entries in the DHCPv4ReservationsList ADM element retrieved based on the EnumElementType parameter is 0, then return ERROR_NO_MORE_ITEMS.

  • If the EnumElementType parameter is set to DhcpReservedIps and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4ReservationsList ADM element.

  • If the EnumElementType parameter is set to DhcpReservedIps and the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle parameter is greater than or equal to the number of entries in the DHCPv4ReservationsList ADM element, then return ERROR_NO_MORE_ITEMS.

  • The EnumElementType parameter is set to DhcpReservedIps and the PreferredMaximum parameter specifies the maximum number of bytes that the server can allocate and return to the caller containing the data related to the IPv4 reservations. If the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server MUST store as many entries as will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA. If PreferredMaximum is 0xFFFFFFFF, the server MUST allocate the memory and store all the available subnet element entries to be retrieved.

  • If the EnumElementType parameter is set to DhcpReservedIps, copy the retrieved DHCPv4Reservation ADM element entries in the EnumElementInfo parameter, copy the number of read DHCPv4Reservation ADM element entries in the ElementsRead parameter, and copy the number of DHCPv4Reservation ADM element entries in the DHCPv4ReservationsList ADM element that are not yet enumerated in the ElementsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4Reservation ADM element entry read.

  • If the EnumElementType parameter is set to DhcpExcludedIpRanges, retrieve all the entries in the DHCPv4Scope.DHCPv4ExclusionRangesList ADM element, starting with the element at the index specified by the value in the ResumeHandle parameter and continuing while the total byte size of all retrieved IPv4 exclusion range elements is less than or equal to the PreferredMaximum parameter.

  • If the EnumElementType parameter is set to DhcpExcludedIpRanges, the PreferredMaximum parameter is 0, and the number of entries in the DHCPv4ExclusionRangesList ADM element retrieved based on the EnumElementType parameter is greater than 0, then return ERROR_MORE_DATA.

  • If the EnumElementType parameter is set to DhcpExcludedIpRanges, the PreferredMaximum parameter is 0, and the number of entries in the DHCPv4ExclusionRangesList ADM element retrieved based on the EnumElementType parameter is 0, then return ERROR_NO_MORE_ITEMS.

  • If the EnumElementType parameter is set to DhcpExcludedIpRanges and the ResumeHandle parameter points to 0x00000000, then the enumeration MUST start from the first entry of the DHCPv4ExclusionRangesList ADM element.

  • If the EnumElementType parameter is set to DhcpExcludedIpRanges and the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle parameter is greater than or equal to the number of entries in the DHCPv4ExclusionRangesList ADM element, then return ERROR_NO_MORE_ITEMS.

  • The PreferredMaximum parameter specifies the maximum number of bytes that the server can allocate and return to the caller containing the data related to the IPv4 exclusions. If the EnumElementType parameter is set to DhcpExcludedIpRanges and the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server MUST store as many entries as will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA.

  • If the EnumElementType parameter is set to DhcpExcludedIpRanges, copy the retrieved DHCPv4ExclusionRange ADM element entries in the EnumElementInfo parameter, copy the number of read DHCPv4ExclusionRange ADM element entries in the ElementsRead parameter, and copy the number of DHCPv4ExclusionRange ADM element entries in the DHCPv4ExclusionRangesList ADM element that are not yet enumerated in the ElementsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4ExclusionRange ADM element entry read.

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