3.1.4.28 R_DhcpScanDatabase (Opnum 27)

  • Article

The R_DhcpScanDatabase method is used by DHCP servers that enumerate and/or fix inconsistencies between the ADM elements DHCPv4 client lease records specified in DHCPv4Scope.DHCPv4ClientsList and the bitmask representation in memory specified in DHCPv4IpRange.BitMask. The caller of this function can free the memory pointed to by the ScanList parameter and its member the ScanItems array by calling the function midl_user_free (section 3).

 DWORD R_DhcpScanDatabase(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS SubnetAddress,
   [in] DWORD FixFlag,
   [out] LPDHCP_SCAN_LIST* ScanList
 );

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

SubnetAddress: This is of type DHCP_IP_ADDRESS (section 2.2.1.2.1), containing the IPv4 subnet ID of the subnet in which the scan is done for the IPv4 addresses that are not in sync.

FixFlag: This is of type DWORD, defining the behavior of this method. This method enumerates the DHCPv4 client IPv4 addresses that are not in sync in both the stores, and if the FixFlag parameter is set to TRUE, it fixes those unmatched IPv4 addresses also.

ScanList: This is a pointer of type LPDHCP_SCAN_LIST that points to the location containing the DHCPv4 client IPv4 addresses that are not in sync in both the stores.

Return Values: A 32-bit unsigned integer value that indicates return status. A return value ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully, else 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 20099, or any generic failure.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist on the DHCP server.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the DHCP server database.

The opnum field value for this method is 27.

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

  • Validate if this method is authorized for read/write access per section 3.5.5. If not, return the error ERROR_ACCESS_DENIED.

  • Retrieve the DHCPv4Scope ADM element entry corresponding to the SubnetAddress parameter from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • Retrieve the DHCPv4IpRange.BitMask ADM element from memory for each element in the DHCPv4Scope.DHCPv4IpRangesList ADM element.

  • Retrieve the DHCPv4ClientsList ADM element from the specified DHCPv4Scope ADM element.

  • Retrieve the DHCPv4ReservationsList ADM element from the specified DHCPv4Scope ADM element.

  • Allocate memory to the ScanList parameter, which is equal to the size of type DHCP_SCAN_LIST, and set its members NumScanItems to zero and ScanItems to NULL.

  • Allocate memory to the ScanItems member for 100 entries at a time. As entries are added to ScanList in the instructions that follow, continue incrementing the NumScanItems member. If NumScanItems reaches a value of 100, then allocate memory for 200 entries and copy the first 100 entries to the new memory and then free the old memory. Continue similarly until all elements are added to the ScanList parameter.

  • Iterate through the DHCPv4ClientsList ADM element; for each DHCPv4Client ADM element that has the corresponding bit set to 0 in the retrieved DHCPv4IpRange.Bitmask ADM element and there exists no DHCPv4Reservation ADM element corresponding to that IPv4 address, add the IPv4 address in the ScanList parameter, and set the ScanFlag member as DhcpRegistryFix. Increment the NumScanItems member.

  • For all the DHCPv4 client Ipv4 addresses that have the corresponding bit set to 1 in the retrieved DHCPv4IpRange.BitMask ADM element, if there is no corresponding DHCPv4Client ADM element entry in the DHCPv4ClientsList ADM element, and if the IPv4 address does not fall within the range specified by any of the entries of DHCPv4Scope.DHCPv4ExclusionRangesList ADM element, add the IPv4 address in the ScanList parameter and set the ScanFlag member as DhcpDatabaseFix. Increment the NumScanItems member.

  • If the NumScanItems member is zero, return ERROR_SUCCESS.

  • For all the DHCPv4 reservations in DHCPv4Scope.DHCPv4ReservationsList ADM element, if there exists no corresponding entry in DHCPv4Scope.DHCPv4ClientsList  ADM element, add the IPv4 address in the ScanList parameter and set the ScanFlag member as DhcpDatabaseFix. This is done in order to locate addresses that are reserved but do not have corresponding DHCPv4 client lease records.

  • If the NumScanItems member is greater than zero and the FixFlag parameter is set to FALSE, return ERROR_SUCCESS to the caller.

  • If the NumScanItems member is greater than zero and the FixFlag parameter is set to TRUE, traverse ScanList, and for each entry that contains a ScanFlag member equal to DhcpDatabaseFix, create a DHCPv4Client ADM element object and insert it into the DHCPv4ClientsList ADM element. The DHCPv4Client ADM element object is initialized as follows:

    • DHCPv4Client.ClientIpAddress ADM element is set to the ScanList.IpAddress member.

    • DHCPv4Client.SubnetMask ADM element is set to the DHCPv4Scope.SubnetMask ADM element.

    • DHCPv4Client.ClientName ADM element is set to a string representation of the ScanList.IpAddress member.

    • DHCPv4Client.OwnerHost.NetBiosName ADM element is set to the NetBIOS name of the DHCPv4 Server. OwnerHost.IpAddress ADM element is set to the ServerIpAddress parameter in case an IP address is passed.

    • DHCPv4Client.bClientType ADM element is set to CLIENT_TYPE_BOTH.

    • DHCPv4Client.AddressState ADM element is set to ADDRESS_STATE_ACTIVE.

    • DHCPv4Client.QuarantineCapable ADM element is set to FALSE.

    • DHCPv4Client.Status ADM element is set to NOQUARANTINE.

    • DHCPv4Client.ProbationEnds ADM element is set to 0.

    • The DHCPv4Client.SentPotExpTime ADM element is set to 0.

    • The DHCPv4Client.AckPotExpTime ADM element is set to 0.

    • The DHCPv4Client.RecvPotExpTime ADM element is set to 0.

    • The DHCPv4Client.StartTime ADM element is set to 0.

    • The DHCPv4Client.CltLastTransTime ADM element is set to 0.

    • The DHCPv4Client.LastBndUpdTime ADM element is set to 0.

    • The DHCPv4Client.flags ADM element is set to 0.

    • The DHCPv4Client.bndMsgStatus ADM element is set to 0.

    • The DHCPv4Client.PolicyName ADM element is set to NULL.

    • If there is a DHCPv4Reservation ADM element entry corresponding to the ScanList.IpAddress member in the DHCPv4ReservationsList ADM element, then the specific fields are initialized as follows:

      • DHCPv4Client.ClientHardwareAddress ADM element is set to the DHCPv4Reservation.ReservedForClient ADM element.

      • DHCPv4Client.ClientLeaseExpires ADM element is set to 0.

    • Otherwise, the specific fields are initialized as follows:

      • DHCPv4Client.ClientHardwareAddress ADM element is set to the binary encoding of the string representation of the ScanList.IpAddress member.

      • DHCPv4Client.ClientLeaseExpires ADM element is set to the default lease duration for the specified subnet.

  • For each entry that contains a ScanFlag member equal to DhcpRegistryFix, set the bit corresponding to that IP address in the DHCPv4IpRange.BitMask ADM element to 1.

  • Return ERROR_SUCCESS.

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