The R_DhcpV4GetFreeIPAddress method retrieves the list of IPv4 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_DhcpV4GetFreeIPAddress(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS ScopeId,
   [in] DHCP_IP_ADDRESS startIP,
   [in] DHCP_IP_ADDRESS endIP,
   [in] DWORD numFreeAddr,
   [out] LPDHCP_IP_ARRAY *IPAddrList
 );

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

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

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

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

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

IpAddrList: A pointer to the location at which the list of IPv4 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 any generic failure.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The call completed successfully.
0x00000103 ERROR_FILE_NOT_FOUND	No more elements are left to enumerate.
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.

0x00000103

ERROR_FILE_NOT_FOUND

No more elements are left to enumerate.

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 120.

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

Return ERROR_INVALID_PARAMETER if any of the following conditions 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 IPv4 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 DHCPv4Scope ADM element entry corresponding to the ScopeId parameter from the DHCPv4ScopesList server ADM element.
If the DHCPv4Scope entry is not found, return ERROR_INVALID_PARAMETER.
Retrieve all the entries in the DHCPv4Scope.DHCPv4IpRangesList ADM element. If there are no DHCPv4IpRange ADM element entries in the retrieved list, return ERROR_FILE_NOT_FOUND.
If the IPv4 addresses specified by the startIP and endIP parameters do not belong to the IPv4 subnet specified by the ScopeId parameter, return ERROR_INVALID_PARAMETER.
If the IPv4 addresses specified by the startIP and endIP parameters are nonzero and fall outside all the DHCPv4IpRange objects retrieved in the preceding step, return ERROR_INVALID_PARAMETER.
Allocate memory for the location pointed to by the IPAddrList parameter to accommodate NumFreeAddr number of IPv4 addresses.
Retrieve all the entries in the DHCPv4Scope.DHCPv4ClientsList and DHCPv4Scope.DHCPv4ExclusionRangesList ADM elements.
If the startIP parameter is nonzero, iterate over IPv4 addresses starting from the IPv4 address specified by the startIP parameter. Otherwise, if the startIP parameter is 0, iterate over the IPv4 addresses starting from the StartAddress of the first DHCPv4IpRange ADM element object in the DHCPv4IpRangesList ADM element.
For each IPv4 address, if there is no DHCPv4Client ADM element object in the DHCPv4ClientsList corresponding to the IPv4 address and there is no DHCPv4ExclusionRange ADM element object in the DHCPv4ExclusionRangesList that contains the IPv4 address, copy the IPv4 address to the output IPAddrList parameter.
If the number of IPv4 addresses retrieved has reached the number of IPv4 addresses requested by the caller, return ERROR_SUCCESS.
If the endIP parameter is nonzero and all the available IPv4 addresses up to the IPv4 address specified by the endIP parameter have been retrieved or if the endIP parameter is 0, and all the available IPv4 addresses up to the EndAddress of the last DHCPv4IpRange ADM element object in the DHCPv4IpRangesList have been retrieved (that is, all free IPv4 addresses available in the specified range have been enumerated), enumerate any IPv4 addresses in the DOOMED state by iterating over all the entries in the DHCPv4Scope.DHCPv4ClientsList ADM element object.
Copy the DHCPv4Client.ClientIpAddress from the DHCPv4Client ADM element entry in the DHCPv4ClientsList ADM element entries that have their AddressState field set to ADDRESS_STATE_DOOM, and then proceed to the next record.
If the number of IPv4 addresses retrieved is less than the number of IPv4 addresses requested, return ERROR_DHCP_REACHED_END_OF_SELECTION.

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