3.1.4.18 R_DhcpSetClientInfo (Opnum 17)

  • Article

The R_DhcpSetClientInfo method modifies existing DHCPv4 client lease records on the DHCPv4 server database. 

 DWORD R_DhcpSetClientInfo(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref] LPDHCP_CLIENT_INFO ClientInfo
 );

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

ClientInfo: A pointer of type DHCP_CLIENT_INFO (section 2.2.1.2.12) structure that contains the DHCPv4 client lease record information that needs to be modified within the DHCPv4 server database. The caller MUST pass the ClientIPAddress and ClientHardwareAddress member fields for modification of a DHCPv4 client lease record stored in the DHCPv4 server database. The ClientHardwareAddress member field represents a DHCPv4 client-identifier (section 2.2.1.2.5.1). The members ClientName, ClientComment, ClientLeaseExpires, and OwnerHost are modified in the DHCPv4 client lease record identified by the ClientIPAddress member.

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.

0x00004E2D

ERROR_DHCP_JET_ERROR

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

The opnum field value for this method is 17.

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

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

  • Validate whether the DHCPv4 client's hardware address data and its length are non-NULL. If they are NULL, return the error ERROR_INVALID_PARAMETER.

  • Iterate through the server Abstract Data Model (ADM) element DHCPv4ScopesList, and retrieve the DHCPv4Scope ADM element entry when the DHCPv4ClientsList ADM element contains the DHCPv4Client ADM element entry corresponding to the ClientIpAddress member of the ClientInfo parameter. If the DHCPv4Client ADM element entry is not found, return ERROR_DHCP_JET_ERROR. In case of any other error, return ERROR_INVALID_PARAMETER.

  • Create the DHCPv4 client unique ID (section 2.2.1.2.5.2) for the DHCPv4 client from the ScopeInfo.SubnetAddress ADM element of the specified DHCPv4Scope ADM element and from the DHCPv4 client-identifier, which is the ClientHardwareAddress member specified in the ClientInfo input parameter.

  • Retrieve the DHCPv4Client ADM element entry corresponding to the ClientIpAddress member of the ClientInfo parameter from the DHCPv4Scope.DHCPv4ClientsList ADM element. Set the DHCPv4Client.ClientHardWareAddress ADM element with the client unique ID created in the previous step. Set the DHCPv4Client ADM element entry with the IPAddress member inside the Ownerhost member of the ClientInfo parameter. Other members of OwnerHost, namely NetBIOSName and HostName members, are ignored.

  • If there is any DHCPv4Reservation ADM element entry in the DHCPv4Scope.DHCPv4ReservationsList ADM element corresponding to the ClientIPAddress member of the ClientInfo input parameter, then the DHCPv4Client.ClientLeaseExpires ADM element is not modified; otherwise, if there is no such entry, update the DHCPv4Client.ClientLeaseExpires ADM element with the lease expiry time specified in the ClientLeaseExpires member.

  • The SubnetMask member of the ClientInfo input parameter is ignored. The DHCPv4Client.SubnetMask ADM element remains unchanged and is equal to ScopeInfo.SubnetAddress ADM element of the retrieved DHCPv4Scope ADM element. If the ClientName and ClientComment string member fields of the ClientInfo input parameter are equal to NULL, then the ClientName and ClientComment member fields of retrieved DHCPv4Client ADM element entry are not modified; otherwise, if they contain string values, then these parameters update the DHCPv4Client.ClientName ADM element and DHCPv4Client.ClientComment ADM element.

  • Set the DHCPv4Client.AddressState ADM element to ADDRESS_STATE_ACTIVE.

  • Return ERROR_SUCCESS.

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