3.1.4.17 R_DhcpCreateClientInfo (Opnum 16)

  • Article

The R_DhcpCreateClientInfo method creates DHCPv4 client lease records on the DHCPv4 server database.

 DWORD R_DhcpCreateClientInfo(
   [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 set on the DHCPv4 server. The caller MUST pass the ClientIPAddress and ClientHardwareAddress member fields to add the DHCPv4 client lease record to the DHCPv4 server database. The ClientHardwareAddress member represents a DHCPv4 client-identifier (section 2.2.1.2.5.1). Members ClientName, ClientComment, ClientLeaseExpires, and OwnerHost are modified on 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.

The opnum field value for this method is 16.

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 the method is not authorized, 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 if the IPv4 range contains the Ipv4 address specified by the ClientIpAddress member of the ClientInfo parameter. In case of 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, the DHCPv4 client-identifier, which is the ClientHardwareAddress member field specified in the ClientInfo parameter.

  • If there is a DHCPv4Client ADM element entry corresponding to this DHCPv4 client unique ID and/or client ClientIpAddress member of the ClientInfo parameter in the DHCPv4ClientsList ADM element, return ERROR_DHCP_JET_ERROR. Otherwise, create a DHCPv4Client ADM element object and set the ClientIPAddress, ClientName, ClientComment, and ClientLeaseExpires member fields as specified in the ClientInfo input parameter. Set the other fields of DHCPv4Client ADM element as follows:

    • The DHCPv4Client.SubnetMask ADM element is set to the ScopeInfo.SubnetAddress ADM element of the retrieved DHCPv4Scope ADM element.

    • The DHCPv4Client.ClientHardwareAddress ADM element is set to the DHCPv4 client unique ID created in previous steps.

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

    • The DHCPv4Client.bClientType ADM element is set to CLIENT_TYPE_NONE.

    • The DHCPv4Client.AddressState ADM element is set to ADDRESS_STATE_ACTIVE.

    • The DHCPv4Client.QuarantineCapable ADM element is set to FALSE.

    • The DHCPv4Client.Status ADM element is set to NOQUARANTINE.

    • The DHCPv4Client.ProbationEnds ADM element is set to ZERO.

    • 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.

    Insert the object into the Dhcpv4Scope.DHCPv4ClientsList ADM element, and return the ERROR_SUCCESS (0x00000000) return value.

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