Edit

DhcpV4EnumSubnetClients function (dhcpsapi.h)

  • Article

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