DhcpV6GetFreeIPAddress function (dhcpsapi.h)

The DhcpV6GetFreeIPAddress function retrieves the list of available IPv6 addresses that can be leased to clients.

Syntax

DWORD DHCP_API_FUNCTION DhcpV6GetFreeIPAddress(
  [in, optional] LPWSTR            ServerIpAddress,
  [in]           DHCP_IPV6_ADDRESS ScopeId,
  [in]           DHCP_IPV6_ADDRESS StartIP,
  [in]           DHCP_IPV6_ADDRESS EndIP,
  [in]           DWORD             NumFreeAddrReq,
  [out]          LPDHCPV6_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_IPV6_ADDRESS structure that specifies the IPv6 subnet ID from which available addresses to lease to clients are retrieved.

[in] StartIP

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

[in] EndIP

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

[in] NumFreeAddrReq

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

[out] IPAddrList

Pointer to a DHCPV6_IP_ARRAY structure that contains the list of available IPv6 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.

Remarks

IPAddrList should be free using DhcpRpcFreeMemory.

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

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

Requirements