3.2.4.9 R_DhcpScanMDatabase (Opnum 8)

  • Article

The R_DhcpScanMDatabase method can be used by DHCP servers to enumerate and/or fix inconsistencies between the MADCAP lease records and the bitmask representation in memory (section 3.1.1.4). The caller of this function can free the memory pointed to by ScanList and its member ScanItems by calling the function midl_user_free (section 3).

 DWORD R_DhcpScanMDatabase(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref, string] LPWSTR* MScopeName,
   [in] DWORD FixFlag,
   [out] LPDHCP_SCAN_LIST* ScanList
 );

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

MScopeName: This is a pointer to a Unicode string that contains the name of the multicast subnet in which a scan is done for the MADCAP client IPv4 addresses that are not in sync.

FixFlag: This is of type DWORD, defining the behavior of this method. This method enumerates the MADCAP 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 DHCP_SCAN_LIST (section 2.2.1.2.74) that points to the location that contains the MADCAP 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.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the MADCAP server database.

The opnum field value for this method is 8.

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

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

  • Retrieve the DHCPv4MScope ADM element entry corresponding to MScopeName from the server ADM element DHCPv4MScopesList. If the DHCPv4MScope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

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

  • Retrieve the DHCPv4MClientsList ADM element from the specified DHCPv4MScope.

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

  • Allocate memory to ScanItems for 100 entries at a time. As entries are added to ScanList in the instructions that follow, continue incrementing NumScanItems. If NumScanItems reaches a value of 100, then allocate memory for 200 entries, 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.

  • Iterate through the DHCPv4MClientsList and for each DHCPv4MClient that has the corresponding bit set to 0 in the retrieved DHCPv4IpRange.BitMask, add the IPv4 address in the ScanList and set the ScanFlag as DhcpRegistryFix.

  • For all the DHCPv4 client Ipv4 that have the corresponding bit set to 1 in the retrieved DHCPv4IpRange.BitMask and no corresponding DHCPv4MClient entry in the DHCPv4MClientsList and the IPv4 address does not fall within the range specified by any of the entries of DHCPv4MScope.DHCPv4ExclusionRangesList, add the IPv4 address in the ScanList and set the ScanFlag as DhcpDatabaseFix.

  • If FixFlag is set to FALSE, return ERROR_SUCCESS to the caller.

  • If FixFlag is set to TRUE, traverse the ScanList, and for each entry that contains ScanFlag equal to DhcpDatabaseFix, create a DHCPv4MClient object and insert it into DHCPv4MClientsList. The DHCPv4MClient object is initialized as follows:

    • DHCPv4MClient.ClientIpAddress is set to the ScanList.IpAddress.

    • DHCPv4MClient.MScopeId is set to the DHCPv4MScope.MScopeId.

    • DHCPv4MClient.ClientName is set to NULL.

    • DHCPv4MClient.ClientId is set to the binary encoding of the string representation of ScanList.IpAddress.

    • DHCPv4MClient.ClientLeaseStarts is set to the current system time.

    • DHCPv4MClient.ClientLeaseEnds is set to the default lease duration for specified multicast subnet.

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

    • DHCPv4MClient. AddressState is set to ADDRESS_STATE_ACTIVE.

    • DHCPv4MClient.AddressFlags is set to 0.

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

  • Return ERROR_SUCCESS.

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