DhcpEnumSubnetElementsV5 function (dhcpsapi.h)

Article
10/13/2021

The DhcpEnumSubnetElementsV5 function returns an enumerated list of elements for a specific DHCP subnet.

Syntax

DWORD DHCP_API_FUNCTION DhcpEnumSubnetElementsV5(
  [in]      DHCP_CONST WCHAR                    *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
);

Parameters

[in] ServerIpAddress

Unicode string that specifies the IP address or hostname of the DHCP server.

[in] SubnetAddress

DHCP_IP_ADDRESS value that specifies the address of the IP subnet whose elements will be enumerated.

[in] EnumElementType

DHCP_SUBNET_ELEMENT_TYPE enumeration value that indicates the type of subnet element to enumerate.

[in, out] ResumeHandle

Pointer to a DHCP_RESUME_HANDLE value that identifies the enumeration operation. Initially, this value should be zero, with a successful call returning the handle value used for subsequent enumeration requests. For example, if PreferredMaximum is set to 1000 bytes, and 2000 bytes worth of subnet elements are stored on the server, the resume handle can be used after the first 1000 bytes are retrieved to obtain the next 1000 on a subsequent call, and so forth.

The presence of additional enumerable data is indicated when this function returns ERROR_MORE_DATA. If no additional enumerable data is available on the DHCPv4 server, ERROR_NO_MORE_ITEMS is returned.

[in] PreferredMaximum

Specifies the preferred maximum number of bytes of subnet elements to return. If the number of remaining unenumerated options (in bytes) is less than this value, then that amount will be returned.

To retrieve all the subnet client elements for the default user and vendor class at the specified level, set this parameter to 0xFFFFFFFF.

[out] EnumElementInfo

Pointer to a DHCP_SUBNET_ELEMENT_INFO_ARRAY_V5 structure containing an enumerated list of all elements available for the specified subnet. If no elements are available for enumeration, this value will be null.

[out] ElementsRead

Pointer to a DWORD value that specifies the number of subnet elements returned in EnumElementInfo.

[out] ElementsTotal

Pointer to a DWORD value that specifies the total number of elements for the specified subnet.

Return value

This function returns ERROR_SUCCESS upon a successful call. Otherwise, it returns one of the DHCP Server Management API Error Codes. Common errors include the following:

Return code	Description
ERROR_INVALID_PARAMETER	This error can be returned when this function is called with EnumElementType set to DhcpIpRangesDhcpOnly or DhcpIpRangesDhcpBootp.
ERROR_MORE_DATA	There are more elements available to enumerate.
ERROR_NO_MORE_ITEMS	There are no more elements left to enumerate.

Remarks

When no longer needed, the resources consumed for the enumerated data, and all pointers contained within, should be released with DhcpRpcFreeMemory.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	dhcpsapi.h
Library	Dhcpsapi.lib
DLL	Dhcpsapi.dll