3.2.4.99 R_DhcpV4FailoverGetClientInfo (Opnum 98)

  • Article

The R_DhcpV4FailoverGetClientInfo method retrieves DHCPv4 client lease record information from the DHCPv4 server database. The caller of this function can free the memory pointed to by the ClientInfo parameter, by calling the function midl_user_free (section 3).

 DWORD R_DhcpV4FailoverGetClientInfo(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref] LPDHCP_SEARCH_INFO SearchInfo,
   [out] LPDHCPV4_FAILOVER_CLIENT_INFO* ClientInfo
 );

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

SearchInfo: This is a pointer to a type DHCP_SEARCH_INFO structure (section 2.2.1.2.18) that defines the key to be used to search the DHCPv4 client lease record on the DHCPv4 server. In case the SearchType member is DhcpClientName enumeration value and there are multiple lease records with the same ClientName member, the server will return client information for the client having the lowest numerical IP address.

ClientInfo: This is a pointer of type LPDHCPV4_FAILOVER_CLIENT_INFO (section 2.2.1.2.101) that points to the location in which specific DHCPv4 client lease record information is retrieved. The caller SHOULD free up this buffer after using this. The ClientHardwareAddress member represents a DHCPv4 client unique ID (section 2.2.1.2.5.2).

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

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the DHCP server database or the client entry is not present in the database.

The opnum field value for this method is 98.

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

  • Return ERROR_INVALID_PARAMETER if the SearchInfo parameter is NULL or if the ClientInfo parameter is NULL.

  • If the SearchType member of the SearchInfo parameter is set to DhcpClientName enumeration value and the ClientName member of the SearchInfo parameter is NULL, return ERROR_INVALID_PARAMETER.

  • Validate whether this method is authorized for read access as specified in section 3.5.4. If not, return ERROR_ACCESS_DENIED.

  • Iterate through the DHCPv4ClientsList ADM element of all the DHCPv4Scope ADM element entries in the server ADM element DHCPv4ScopesList, and retrieve the DHCPv4Client ADM element entry corresponding to the members ClientIpAddress, ClientHardwareAddress, or ClientName member as specified by the SearchType member in the SearchInfo parameter (section 2.2.1.2.18). If the DHCPv4Client ADM element entry is not found, return ERROR_DHCP_JET_ERROR.

  • Copy the information in the DHCPv4Client ADM element entry, in the ClientInfo out parameter (section 2.2.1.2.19). The HostName member in the DHCP_HOST_INFO structure (section 2.2.1.2.7) is unused.

  • Return ERROR_SUCCESS.

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