3.2.4.39 R_DhcpEnumSubnetElementsV5 (Opnum 38)
The R_DhcpEnumSubnetElementsV5 method enumerates the list of a specific type of IPv4 subnet element from the specified IPv4 subnet. The caller of this function can free the memory pointed to by EnumElementInfo and the Elements field of EnumElementInfo by calling the function midl_user_free (section 3).
-
DWORD R_DhcpEnumSubnetElementsV5( [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_V5* 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) that contains 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, a value that indicates the type of IPv4 subnet element to enumerate.
ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (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. For example, if PreferredMaximum 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, specifying the preferred maximum number of bytes to return. If the number of remaining unenumerated subnet elements (in bytes) is less than this value, then all IPv4 subnet elements for the 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_V5 in which 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 EnumElementInfo 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 on the DHCP server.
The opnum field value for this method is 38.
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 DhcpSecondaryHosts , return ERROR_NOT_SUPPORTED.
If EnumElementType parameter is set to DhcpIpUsedClusters, DhcpIpRangesDhcpOnly or DhcpIpRangesBootpOnly, return ERROR_INVALID_PARAMETER.
Retrieve the DHCPv4Scope entry corresponding to SubnetAddress from the server ADM element DHCPv4ScopesList.
If the DHCPv4Scope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.
If EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp, 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 PreferredMaximum.
If EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp and PreferredMaximum is 0, then ERROR_NO_MORE_ITEMS is returned.
If EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4IpRangesList element.
If EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp and 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 entries in the DHCPv4IpRangesList element, then return ERROR_NO_MORE_ITEMS.
If EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp, allocate memory for EnumElementInfo equal to the size of structure DHCP_SUBNET_ELEMENT_INFO_ARRAY_V5.
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. In case the PreferredMaximum is 0xFFFFFFFF, the server must allocate memory for all remaining DHCPv4IpRanges objects. If the EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp and PreferredMaximum is unable to hold all the entries in DHCPv4IpRangesList starting from ResumeHandle, allocate memory for the Elements field of EnumElementInfo equal to PreferredMaximum, else allocate memory for the Elements field of EnumElementInfo equal to the number of entries in DHCPv4IpRangesList starting from ResumeHandle.
If the EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp, copy as many RangeInfo entries from the retrieved DHCPv4IpRange entries in the Elements field of the EnumElementInfo parameter as can fit into the allocated memory in the preceding step. Copy the number of read DHCPv4IpRange entries in the ElementsRead parameter and in the numElements field of EnumElementInfo, and copy the number of DHCPv4IpRange entries in the DHCPv4IpRangesList 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 element entry read.
If the EnumElementType parameter is set to DhcpIpRanges or DhcpIpRangesDhcpBootp, and if PreferredMaximum memory was not able to hold all entries being retrieved from DHCPv4IpRangesList, then return ERROR_MORE_DATA, else return ERROR_SUCCESS.
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 range elements is less than PreferredMaximum.
If EnumElementType parameter is set to DhcpReservedIps, PreferredMaximum is 0 and the number of entries in the DHCPv4ReservationsList retrieved based on EnumElementType parameter is greater than 0, then ERROR_MORE_DATA is returned.
If EnumElementType parameter is set to DhcpReservedIps, PreferredMaximum is 0 and the number of entries in the DHCPv4ReservationsList retrieved based on EnumElementType parameter is 0, then ERROR_NO_MORE_ITEMS is returned.
If EnumElementType parameter is set to DhcpReservedIps and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4ReservationsList.
If 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 is greater or equal to than the number of entries in the DHCPv4ReservationsList, then return ERROR_NO_MORE_ITEMS.
If EnumElementType parameter is set to DhcpReservedIps, allocate memory for EnumElementInfo equal to the size of structure DHCP_SUBNET_ELEMENT_INFO_ARRAY_V5.
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. In case the PreferredMaximum is 0xFFFFFFFF, the server must allocate memory for all remaining DHCPv4ReservedIps objects. If the EnumElementType parameter is set to DhcpReservedIps and PreferredMaximum is unable to hold all the entries in DHCPv4ReservationsList starting from ResumeHandle, allocate memory for the Elements field of EnumElementInfo equal to PreferredMaximum, else allocate memory for the Elements field of EnumElementInfo equal to the number of entries in DHCPv4ReservationsList starting from ResumeHandle.
If the EnumElementType parameter is set to DhcpReservedIps, copy the retrieved DHCPv4Reservation entries in EnumElementInfo and copy as many DHCPv4Reservation entries in the Elements field of the EnumElementInfo parameter as can fit into the allocated memory in the preceding step. Copy the number of read DHCPv4Reservation entries in ElementsRead and in the numElements field of EnumElementInfo, and copy the number of DHCPv4Reservation entries in DHCPv4ReservationsList that are not yet enumerated in ElementsTotal. Update ResumeHandle to the value obtained by adding 1 to the index of the last DHCPv4Reservation entry read.
If the EnumElementType parameter is set to DhcpReservedIps, and if PreferredMaximum memory was not able to hold all entries being retrieved from DHCPv4ReservationsList, then return ERROR_MORE_DATA, else return ERROR_SUCCESS.
If EnumElementType is set to DhcpExcludedIpRanges, retrieve all the entries in DHCPv4Scope.DHCPv4ExclusionRangesList, 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 PreferredMaximum.
If EnumElementType is set to DhcpExcludedIpRanges, PreferredMaximum is 0 and the number of entries in the DHCPv4ExclusionRangesList retrieved based on EnumElementType parameter is greater than 0, then ERROR_MORE_DATA is returned.
If EnumElementType is set to DhcpExcludedIpRanges and PreferredMaximum is 0 and the number of entries in the DHCPv4ExclusionRangesList retrieved based on EnumElementType parameter is 0, then ERROR_NO_MORE_ITEMS is returned.
If EnumElementType is set to DhcpExcludedIpRanges and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4ExclusionRangesList.
If EnumElementType 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 ResumeHandle is greater than or equal to the number of entries in the DHCPv4ExclusionRangesList, then return ERROR_NO_MORE_ITEMS.
If EnumElementType parameter is set to DhcpExcludedIpRanges, allocate memory for EnumElementInfo equal to the size of structure DHCP_SUBNET_ELEMENT_INFO_ARRAY_V5.
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. In case the PreferredMaximum is 0xFFFFFFFF, the server must allocate memory for all remaining DHCPExcludedIpRanges objects. If EnumElementType is set to DhcpExcludedIpRanges and PreferredMaximum is unable to hold all the entries in DhcpExcludedIpRanges starting from ResumeHandle, allocate memory for the Elements field of EnumElementInfo equal to PreferredMaximum, else allocate memory for the Elements field of EnumElementInfo equal to the number of entries in DhcpExcludedIpRanges starting from ResumeHandle.
If EnumElementType is set to DhcpExcludedIpRanges, copy as many DHCPv4ExclusionRange entries in the Elements field of the EnumElementInfo parameter as can fit into the allocated memory in the preceding step. Copy the number of read DHCPv4ExclusionRange entries in ElementsRead and in the numElements field of EnumElementInfo, and copy the number of DHCPv4ExclusionRange entries in DHCPv4ExclusionRangesList that are not yet enumerated in ElementsTotal. Update ResumeHandle to the value obtained by adding 1 to the index of the DHCPv4ExclusionRange entries read.
If the EnumElementType parameter is set to DhcpExcludedIpRanges, and if PreferredMaximum memory was not able to hold all entries being retrieved from DhcpExcludedIpRanges, then return ERROR_MORE_DATA, else return ERROR_SUCCESS.
Exceptions Thrown: No exceptions SHOULD be thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].