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:

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