3.2.4.61 R_DhcpEnumSubnetElementsV6 (Opnum 60)
The R_DhcpEnumSubnetElementsV6 method returns an enumerated list of a specific type of IPv6 prefix element for a specific DHCPv6 IPv6 prefix. The caller of this function can free the memory pointed to by EnumElementInfo and other Elements by calling the function midl_user_free (section 3).
-
DWORD R_DhcpEnumSubnetElementsV6( [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress, [in] DHCP_IPV6_ADDRESS SubnetAddress, [in] DHCP_SUBNET_ELEMENT_TYPE_V6 EnumElementType, [in, out] DHCP_RESUME_HANDLE* ResumeHandle, [in] DWORD PreferredMaximum, [out] LPDHCP_SUBNET_ELEMENT_INFO_ARRAY_V6* 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_IPV6_ADDRESS (section 2.2.1.2.28), containing the IPv6 address of the subnet from which subnet elements are enumerated.
EnumElementType: This is of type DHCP_SUBNET_ELEMENT_TYPE_V6 (section 2.2.1.1.8) value, indicating the type of IPv6 prefix 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 IPv6 prefix elements are stored on the DHCPv6 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 element (in bytes) is less than this value, all IPv6 prefix elements for specific type are returned. To retrieve all the IPv6 prefix elements of a specific type, 0xFFFFFFFF is specified.
EnumElementInfo: This is a pointer of type LPDHCP_SUBNET_ELEMENT_INFO_ARRAY_V6 in which an IPv4 subnet element of type EnumElementType is returned for a specific IPv6 prefix SubnetAddress. If no IPv6 prefix elements are available for enumeration, this value is null.
ElementsRead: This is a pointer to a DWORD value that specifies the number of IPv6 prefix elements read in EnumElementInfo for a specific type of IPv6 prefix 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 IPv6 prefix elements of a specific type for a specific IPv6 prefix 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.
The opnum field value for this method is 60.
When processing this call, the DHCP server MUST do the following:
Validate that this method is authorized for read access per section 3.5.4. If not, return the error ERROR_ACCESS_DENIED.
Retrieve the DHCPv6Scope object corresponding to SubnetAddress from DHCPv6ScopeList. If the DHCPv6Scope object corresponding to SubnetAddress does not exist, return ERROR_FILE_NOT_FOUND.
If EnumElementType is set to Dhcpv6ReservedIps, retrieve the DHCPv6Reservation objects in EnumElementInfo (section 2.2.1.2.34) from DHCPv6Scope.DHCPv6ReservationList, 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 IPv6 reservation elements is less than PreferredMaximum.
If EnumElementType is set to Dhcpv6ReservedIps, PreferredMaximum is 0, and the number of DHCPv6Reservation objects retrieved based on EnumElementType is greater than 0, ERROR_MORE_DATA is returned.
If EnumElementType is set to Dhcpv6ReservedIps, PreferredMaximum is 0, and the number of DHCPv6Reservation objects retrieved based on EnumElementType is 0, ERROR_NO_MORE_ITEMS is returned.
If EnumElementType is set to Dhcpv6ReservedIps and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the beginning of the DHCPv6Scope.DHCPv6ReservationList object.
If EnumElementType is set to Dhcpv6ReservedIps 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 DHCPv6Reservation objects in DHCPv6Scope.DHCPv6ReservationList, 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 DHCPv6Reservation objects retrieved. In case PreferredMaximum is 0xffffffff, the server MUST allocate memory for all remaining DHCPv6Reservation objects. If EnumElementType is set to Dhcpv6ReservedIps and PreferredMaximum is unable to hold all the entries being retrieved, the server MUST store as many entries as will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA.
If EnumElementType is set to Dhcpv6ReservedIps, copy the retrieved DHCPv6Reservation objects in EnumElementInfo, copy the number of objects read in ElementsRead, and copy the number of DHCPv6Reservation objects in DHCPv6Scope.DHCPv6ReservationList that are not yet enumerated in ElementsTotal. Update ResumeHandle to the index of the last DHCPv6Reservation object read plus one.
If EnumElementType is set to Dhcpv6ExcludedIpRanges, retrieve the DHCPv6ExclusionRange objects from DHCPv6Scope.DHCPv6ExclusionRangeList, starting with the element at the index specified by the value in the ResumeHandle parameter in EnumElementInfo (section 2.2.1.2.34) and continuing while the total byte size of all retrieved IPv6 exclusion range elements is less than PreferredMaximum.
If EnumElementType is set to Dhcpv6ExcludedIpRanges, PreferredMaximum is 0, and the number of DHCPv6ExclusionRange objects retrieved based on EnumElementType is greater than 0, ERROR_MORE_DATA is returned.
If EnumElementType is set to Dhcpv6ExcludedIpRanges, PreferredMaximum is 0, and the number of DHCPv6ExclusionRange objects retrieved based on EnumElementType is 0, ERROR_NO_MORE_ITEMS is returned.
If EnumElementType is set to Dhcpv6ExcludedIpRanges and the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the beginning of DHCPv6Scope.DHCPv6ExclusionRangeList.
If EnumElementType is set to Dhcpv6ExcludedIpRanges 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 DHCPv6Scope.DHCPv6ExclusionRangeList.DHCPv6ExclusionRange objects, 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 DHCPv6Scope.DHCPv6ExclusionRangeList.DHCPv6ExclusionRange objects. In case PreferredMaximum is 0xffffffff, the server MUST allocate memory for all remaining DHCPv6 Scope.DHCPv6ExclusionRangeList.DHCPv6ExclusionRange objects. If EnumElementType is set to Dhcpv6ExcludedIpRanges and PreferredMaximum is unable to hold all the entries being retrieved, the server MUST store as many entries as will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA.
If EnumElementType is set to Dhcpv6ExcludedIpRanges, copy the retrieved DHCPv6Scope.DHCPv6ExclusionRangeList.DHCPv6ExclusionRange objects in EnumElementInfo, copy the number of the objects read in ElementsRead, and copy the number of the objects in DHCPv6Scope.DHCPv6ExclusionRangeList that are not yet enumerated in ElementsTotal. Update ResumeHandle to the index of the last DHCPv6ExclusionRange object read plus one.
If the EnumElementType field is set to Dhcpv6IpRanges, retrieve no information and return ERROR_INVALID_PARAMETER.
Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].