Edit

DhcpScanDatabase function (dhcpsapi.h)

  • Article

The DhcpScanDatabase function enumerates the leased DHCPv4 client IPv4 addresses that are not synchronized between the in-memory cache and the server database.

Syntax

DWORD DHCP_API_FUNCTION DhcpScanDatabase(
  [in]  DHCP_CONST WCHAR *ServerIpAddress,
  [in]  DHCP_IP_ADDRESS  SubnetAddress,
  [in]  DWORD            FixFlag,
  [out] LPDHCP_SCAN_LIST *ScanList
);

Parameters

[in] ServerIpAddress

Unicode string that specifies the IP address or hostname of the DHCP server.

[in] SubnetAddress

DHCP_IP_ADDRESS value that specifies the subnet whose leases will be scanned for desynchronized client lease IP addresses.

[in] FixFlag

Specifies a set of bit flags that indicate whether the in-memory cache or the client lease database should be the definitive source for fixes when synchronizing the two on the DHCPv4 server. These flags are enumerated in DHCP_SCAN_FLAG.

[out] ScanList

DHCP_SCAN_LIST structure that contains the returned list of leased client IP addresses that are not in sync.

Return value

This function returns ERROR_SUCCESS upon a successful call. Otherwise, it returns one of the DHCP Server Management API Error Codes.

Return code Description
ERROR_ACCESS_DENIED
 This call was performed by a client who is not a member of the "DHCP Administrators" security group.
ERROR_DHCP_JET_ERROR
 An error occurred while accessing the DHCPv4 server's database.
ERROR_DHCP_SUBNET_NOT_PRESENT
 The specified subnet is not defined on the DHCPv4 server.

Remarks

Each leased DHCPv4 client IPv4 address defined on a DHCPv4 server has an entry in both an in-memory store, which serves as a cache for speeding up lease retrieval, and in the client lease database proper. DhcpScanDatabase enumerates either the DHCPv4 client IPv4 addresses that are present in the in-memory store and are not present in the database, or those that are present in database but not present in the in-memory store.

This process is necessary as the DHCPv4 server maintains an in-memory cache of frequently-accessed client leases used to improve performance, but it can become desynchronized relative to the server's persistent client lease database. Therefore, it is necessary to reconcile the two stores, and update either the in-memory version of a client lease IP address, or the client lease IP address stored in the database. The DHCP_SCAN_LIST structure returned by this operation contains the "definitive" client leases as specified by the preferred location set in the FixFlag parameter.

Requirements

Requirement Value
Minimum supported client None supported
Minimum supported server Windows Server 2008, Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header dhcpsapi.h
Library Dhcpsapi.lib
DLL Dhcpsapi.dll

See also

DHCP_SCAN_LIST