DhcpV4EnumSubnetClients function (dhcpsapi.h)

Article
10/13/2021

The DhcpV4EnumSubnetClients function enumerates all DHCP client records serviced from the specified IPv4 subnet.

Syntax

DWORD DHCP_API_FUNCTION DhcpV4EnumSubnetClients(
  [in, optional] DHCP_CONST WCHAR            *ServerIpAddress,
  [in]           DHCP_IP_ADDRESS             SubnetAddress,
  [in, out]      DHCP_RESUME_HANDLE          *ResumeHandle,
  [in]           DWORD                       PreferredMaximum,
  [out]          LPDHCP_CLIENT_INFO_PB_ARRAY *ClientInfo,
  [out]          DWORD                       *ClientsRead,
  [out]          DWORD                       *ClientsTotal
);

Parameters

[in, optional] ServerIpAddress

Pointer to a null-terminated Unicode string that represents the IP address or hostname of the DHCP server.

[in] SubnetAddress

DHCP_IP_ADDRESS structure that contains the IPv4 subnet address of the DHCP client records to enumerate. If set to 0, the DHCP client records for all known IPv4 subnets are returned.

[in, out] ResumeHandle

Pointer to a DHCP_RESUME_HANDLE structure that identifies this enumeration for use in subsequent calls to this function. Initially, this value should be zero on input. If successful, the returned value should be used for subsequent enumeration requests. The returned handle value is the last IPv4 address retrieved in the enumeration operation.

[in] PreferredMaximum

The maximum number of bytes of client records to return in ClientInfo. The minimum value is 1024 bytes, and the maximum value is 65536 bytes.

[out] ClientInfo

Pointer to a DHCP_CLIENT_INFO_PB_ARRAY structure that contains the DHCP client lease records set available for the specified subnet.

[out] ClientsRead

Pointer to a DWORD that specifies the number of DHCP client records returned in ClientInfo.

[out] ClientsTotal

Pointer to a DWORD that specifies the number of client records on the DHCP server that have not yet been enumerated.

Return value

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, it returns one of the following or an error code from DHCP Server Management API Error Codes.

Value	Meaning
ERROR_ACCESS_DENIED	This call was performed by a client who is not a member of the DHCP Users or DHCP Administrators security groups.
ERROR_DHCP_JET_ERROR	An error occurred while accessing the DHCP server's database.
ERROR_MORE_DATA	There are still non-enumerated client lease records on the DHCP server for the provided IPv4 subnet. Call this function again with the returned resume handle to obtain more records.
ERROR_NO_MORE_ITEMS	There are no client lease records on the DHCP server.

Remarks

ClientInfo should be free using DhcpRpcFreeMemory.

Requirements

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

Share via