Edit

DhcpV4EnumSubnetReservations function (dhcpsapi.h)

  • Article

The DhcpV4EnumSubnetReservations function enumerates the reservations for a specific DHCP IPv4 subnet.

Syntax

DWORD DHCP_API_FUNCTION DhcpV4EnumSubnetReservations(
  [in, optional] DHCP_CONST WCHAR              *ServerIpAddress,
  [in]           DHCP_IP_ADDRESS               SubnetAddress,
  [in, out]      DHCP_RESUME_HANDLE            *ResumeHandle,
  [in]           DWORD                         PreferredMaximum,
  [out]          LPDHCP_RESERVATION_INFO_ARRAY *EnumElementInfo,
  [out]          DWORD                         *ElementsRead,
  [out]          DWORD                         *ElementsTotal
);

Parameters

[in, optional] ServerIpAddress

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

[in] SubnetAddress

DHCP_IP_ADDRESS structure that contains the IPv4 subnet address of the reservations to enumerate.

[in, out] ResumeHandle

Pointer to a DHCP_RESUME_HANDLE structure that identifies this enumeration for use in subsequent calls to this function.

Initially, this value should be zero on input. If successful, the returned value should be used for subsequent enumeration requests. For example, if PreferredMaximum is set to 100, and 200 reservation elements are configured on the server, the resume handle can be used after the first 100 policies are retrieved to obtain the next 100 on a subsequent call.

[in] PreferredMaximum

The maximum number of bytes of subnet reservations to return in EnumInfo. If PreferredMaximum is greater than the number of remaining non-enumerated bytes of subnet reservations on the server, the remaining number of non-enumerated bytes is returned. To retrieve all the subnet reservation elements, set this parameter to 0xFFFFFFFF.

[out] EnumElementInfo

Pointer to a DHCP_RESERVATION_INFO_ARRAY structure that contains the reservations elements available for the specified subnet. If no elements are configured, this value is NULL.

[out] ElementsRead

Pointer to a DWORD that specifies the number of reservation elements returned in EnumElementInfo.

[out] ElementsTotal

Pointer to a DWORD that specifies the number of reservations on the DHCP server that have not yet been enumerated.

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_MORE_DATA
 There are more elements available to enumerate.
ERROR_NO_MORE_ITEMS
 There are no more elements left to enumerate.
ERROR_DHCP_SUBNET_NOT_PRESENT
 IPv4 subnet does not exist on the DHCPv4 server.

Remarks

EnumElementInfo should be free using DhcpRpcFreeMemory.

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