The R_DhcpV6GetFreeIPAddress method retrieves the list of IPv6 addresses available to be leased out to the clients. The caller of this function can free the memory pointed to by the IPAddrList parameter by calling the function midl_user_free (section 3).

 DWORD R_DhcpV6GetFreeIPAddress(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IPV6_ADDRESS ScopeId,
   [in] DHCP_IPV6_ADDRESS startIP,
   [in] DHCP_IPV6_ADDRESS endIP,
   [in] DWORD numFreeAddr,
   [out] LPDHCPV6_IP_ARRAY *IPAddrList
 );

ServerIpAddress: The IP address of the DHCP server. This parameter is unused.

ScopeId: The IPv6 subnet ID that contains the addresses available to be leased out.

startIP: The IPv6 address at the start of the range of IPv6 addresses available to be leased out. A value of 0 indicates that the method uses the starting address of the IPv6 range of the scope specified by the ScopeId parameter.

endIP: The IPv6 address at the end of the range of IPv6 addresses available to be leased out. A value of 0 indicates that the method uses the ending address of the IPv6 range of the scope specified by the ScopeId parameter.

numFreeAddr: The number of IPv6 addresses to obtain from the specified scope. If this parameter is 0, only one IPv6 address is returned.

IpAddrList: A pointer to the location at which the list of IPv6 addresses available to be leased out will be returned.

Return Values: A 32-bit unsigned integer value that indicates return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully. Otherwise, it contains a Win32 error code, as specified in [MS-ERREF]. This error code value can correspond to a DHCP-specific failure, which takes a value between 20000 and 20123, or to any generic failure.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The call completed successfully.
0x00020005 ERROR_DHCP_SUBNET_NOT_PRESENT	The IPv6 subnet does not exist on the DHCPv6 server.
0x00020126 ERROR_DHCP_REACHED_END_OF_SELECTION	The specified DHCP server has reached the end of the selected range while finding the free IP addresses.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call completed successfully.

0x00020005

ERROR_DHCP_SUBNET_NOT_PRESENT

The IPv6 subnet does not exist on the DHCPv6 server.

0x00020126

ERROR_DHCP_REACHED_END_OF_SELECTION

The specified DHCP server has reached the end of the selected range while finding the free IP addresses.

The opnum field value for this method is 121.

When processing this call, the DHCP server MUST do the following:

Return ERROR_INVALID_PARAMETER if any of the following are true:
- The IPAddrList parameter is NULL.
- The ScopeId parameter is 0.
- The NumFreeAddr parameter is greater than DHCP_MAX_FREE_ADDRESSES_REQUESTED.
- The startIP and endIP parameters are nonzero, and startIP is greater than endIP.
- The startIP and endIP parameters are nonzero, and the number of IPv6 addresses in the range defined by those parameters is less than the value of the NumFreeAddr parameter.
Validate that the method is authorized for read access as specified in section 3.5.4. If not, return ERROR_ACCESS_DENIED.
Retrieve the DHCPv6Scope ADM element entry corresponding to the ScopeId parameter from the DHCPv6ScopesList server ADM element.
If the DHCPv6Scope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.
If the IPv6 addresses specified by the startIP and endIP parameters do not belong to the IPv6 subnet specified by the ScopeId parameter, return ERROR_INVALID_PARAMETER.
Allocate memory for the location pointed to by the IPAddrList parameter to accommodate NumFreeAddr number of IPv6 addresses.
Retrieve all the entries in the DHCPv6Scope.DHCPv6ClientsList and DHCPv6Scope.DHCPv6ExclusionRangesList ADM elements.
If the startIP parameter is nonzero, iterate over IPv6 addresses starting from the IPv6 address specified by the startIP parameter. Otherwise, if the startIP parameter is 0, iterate over the IPv6 addresses starting from the first IPv6 address of the subnet specified by DHCPv6Scope.
For each IPv6 address, if there is no DHCPv6Client ADM element object in the DHCPv6ClientsList corresponding to the IPv6 address and there is no DHCPv6ExclusionRange ADM element object in the DHCPv6ExclusionRangesList that contains the IPv6 address, copy the IPv6 address to the output IPAddrList parameter.
If the number of IPv6 addresses retrieved has reached the number of IPv6 addresses requested by the caller, return ERROR_SUCCESS.
If the endIP parameter is nonzero and all the available IPv6 addresses up to the IPv6 address specified by the endIP parameter have been retrieved or if the endIP parameter is 0, and all the available IPv6 addresses up to the last IPv6 address of the subnet specified by DHCPv6Scope have been retrieved, and if the number of IPv6 addresses retrieved is less than the number of IPv6 addresses requested, return ERROR_DHCP_REACHED_END_OF_SELECTION.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol specified in [MS-RPCE].