Windows Dev Center

Expand Minimize

DhcpV4GetFreeIPAddress function

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

Syntax


DWORD DHCP_API_FUNCTION DhcpV4GetFreeIPAddress(
  _In_opt_ 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

ServerIpAddress [in, optional]

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

ScopeId [in]

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

startIP [in]

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.

endIP [in]

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.

numFreeAddrReq [in]

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.

IPAddrList [out]

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.

ValueMeaning
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

Minimum supported client

None supported

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Dhcpsapi.h

Library

Dhcpsapi.lib

DLL

Dhcpsapi.dll

 

 

Community Additions

ADD
Show:
© 2015 Microsoft