Edit

DhcpV4GetFreeIPAddress function (dhcpsapi.h)

  • Article

The DhcpV4GetFreeIPAddress function retrieves the list of available IPv4 addresses that can be leased to clients.

Syntax

DWORD DHCP_API_FUNCTION DhcpV4GetFreeIPAddress(
  [in, optional] LPWSTR          ServerIpAddress,
  [in]           DHCP_IP_ADDRESS ScopeId,
  [in]           DHCP_IP_ADDRESS StartIP,
  [in]           DHCP_IP_ADDRESS EndIP,
  [in]           DWORD           NumFreeAddrReq,
  [out]          LPDHCP_IP_ARRAY *IPAddrList
);

Parameters

[in, optional] ServerIpAddress

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

[in] ScopeId

DHCP_IP_ADDRESS structure that specifies the IPv4 subnet ID from which available addresses to lease to clients are retrieved.

[in] StartIP

DHCP_IP_ADDRESS structure that specifies the scope IPv4 range's starting point address from where the available addresses are retrieved. If this parameter is 0, the start address of the IPv4 subnet specified by ScopeId is the default.

[in] EndIP

DHCP_IP_ADDRESS structure that specifies the scope IPv4 range's end point address from where the available addresses are retrieved. If this parameter is 0, the end address of the IPv4 subnet specified by ScopeId parameter is taken as the default.

[in] NumFreeAddrReq

Integer that specifies the number of IPv4 addresses retrieved from the specified scope in IPAddrList. If this parameter is 0, only one IPv4 address is returned.

[out] IPAddrList

Pointer to a DHCP_IP_ARRAY structure that contains the list of available IPv4 addresses that can be leased to clients.

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_INVALID_PARAMETER
 One or more of the parameters were invalid.
ERROR_FILE_NOT_FOUND
 There are no more elements left to enumerate.
ERROR_DHCP_REACHED_END_OF_SELECTION
 The specified DHCP Server has reached the end of the selected range while finding the free IP address.

Remarks

IPAddrList should be free using DhcpRpcFreeMemory.

The maximum number of IPv4 addresses returned is 1024. To retrieve more that 1024 IPv4 addresses, multiple calls to DhcpV4GetFreeIPAddress must be made. After the initial call, each subsequent call to DhcpV4GetFreeIPAddress must set startIP to the last address in the list received in IPAddrList from the previous call to DhcpV4GetFreeIPAddress.

When the number of free IPv4 addresses available on the DHCP server is less than that requested, the list of free IPv4 addresses available are returned to the caller with error code ERROR_DHCP_REACHED_END_OF_SELECTION.

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