Share via

3.1.4.40 R_DhcpServerSetConfigV4 (Opnum 39)

  • Article

The R_DhcpServerSetConfigV4 method sets/modifies the DHCPv4 server settings. 

 DWORD R_DhcpServerSetConfigV4(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD FieldsToSet,
   [in, ref] LPDHCP_SERVER_CONFIG_INFO_V4 ConfigInfo
 );

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

FieldsToSet: A DWORD that contains the bitmask of the fields in the ConfigInfo parameter to set. This method can be called with a value for the FieldsToSet parameter.

The bit mapping for the various values for the FieldsToSet parameter is listed in the following table.

FieldsToSet

Bit

Set_APIProtocolSupport

0x00000001

Set_DatabaseName

0x00000002

Set_DatabasePath

0x00000004

Set_BackupPath

0x00000008

Set_BackupInterval

0x00000010

Set_DatabaseLoggingFlag

0x00000020

Set_RestoreFlag

0x00000040

Set_DatabaseCleanupInterval

0x00000080

Set_DebugFlag

0x00000100

Set_PingRetries

0x00000200

Set_BootFileTable

0x00000400

Set_AuditLogState

0x00000800

The DHCP server behavior ignores the bits not specified in the table.

Most of the settings are effective immediately. The DHCPv4 server needs to be restarted for the following settings to become effective:

  • Set_APIProtocolSupport

  • Set_DatabaseName

  • Set_DatabasePath

  • Set_DatabaseLoggingFlag

  • Set_RestoreFlag

ConfigInfo: A pointer of type DHCP_SERVER_CONFIG_INFO_V4 (section 2.2.1.2.54) structure, containing the settings for the DHCPv4 server. The value that is passed here depends on the FieldsToSet parameter. Details of the dependencies follow the return value description.

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. Otherwise, the return value 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.

The opnum field value for this method is 39.

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.

  • Validate the FieldsToSet parameter for nonzero. If it is zero, return ERROR_SUCCESS.

  • If the Set_APIProtocolSupport  bit is set in the FieldsToSet parameter and the APIProtocolSupport member in the ConfigInfo parameter is set to zero, then return ERROR_INVALID_PARAMETER. Else if the Set_APIProtocolSupport bit is set in the FieldsToSet parameter, then set/modify the APIProtocolSupport member from the ConfigInfo parameter to the server ADM element DHCPv4ServerConfigInfo. If the APIProtocolSupport member is set to values other than 1, 2, 4, or 7, the DHCP Server behavior is undefined.

  • If the Set_PingRetries bit is set in the FieldsToSet parameter and the dwPingRetries member in the ConfigInfo parameter is greater than 0x05, return ERROR_INVALID_PARAMETER. Else if the Set_PingRetries bit is set in the FieldsToSet parameter, then set/modify the dwPingRetries member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_AuditLogState bit is set in the FieldsToSet parameter, then set/modify the fAuditLog member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_BootFileTable bit is set in the FieldsToSet parameter and the cbBootTableString member in the ConfigInfo parameter is greater than 0x100000, then return ERROR_INVALID_PARAMETER. Else if the Set_BootFileTable bit is set in the FieldsToSet parameter, then set/modify the wszBootTableString member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_DatabaseName bit is set in the FieldsToSet member and the DatabaseName member in the ConfigInfo parameter is NULL or is a NULL terminated empty string, then return ERROR_INVALID_PARAMETER. Else if the Set_DatabaseName bit is set in the FieldsToSet parameter and the DatabaseName member cannot be converted into an OEM or ANSI character string, then return ERROR_INVALID_NAME. Else if the Set_DatabaseName bit is set in the FieldsToSet parameter, then set/modify the DatabaseName member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_DatabasePath bit is set in the FieldsToSet parameter and the DatabasePath member in the ConfigInfo parameter is NULL or is a NULL terminated empty string, then return ERROR_INVALID_PARAMETER. Else if the Set_DatabasePath bit is set in the FieldsToSet parameter and the DatabasePath member cannot be converted into OEM or ANSI character string, then return ERROR_INVALID_NAME. Else if the Set_DatabasePath bit is set in the FieldsToSet member, then create the directory with the specified path and set/modify the DatabasePath member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_BackupPath bit is set in the FieldsToSet parameter and the BackupPath member in the ConfigInfo parameter is NULL or is a NULL terminated empty string, then return ERROR_INVALID_PARAMETER. Else if the Set_BackupPath bit is set in the FieldsToSet parameter and the BackupPath member cannot be converted into an OEM or ANSI character string, then return ERROR_INVALID_NAME. Else if the Set_BackupPath bit is set in the FieldsToSet parameter, then create the directory with the specified path and set/modify the BackupPath member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_BackupInterval is set in the FieldsToSet parameter and the BackupInterval member is zero, return ERROR_INVALID_PARAMETER. Else if Set_BackupInterval is set in the FieldsToSet parameter and the BackupInterval member (in minutes) after converting to milliseconds is greater than 0xFFFFFFFF, return ERROR_ARITHMETIC_OVERFLOW. Else if Set_BackupInterval is set in the FieldsToSet parameter, then set/modify the BackupInterval member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_DatabaseLoggingFlag is set in the FieldsToSet parameter, set/modify the DatabaseLoggingFlag member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_RestoreFlag is set in the FieldsToSet parameter, set/modify the RestoreFlag member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_DatabaseCleanupInterval is set in the FieldsToSet parameter and the DatabaseCleanupInterval member is zero, return ERROR_INVALID_PARAMETER. Else if Set_DatabaseCleanupInterval is set in the FieldsToSet parameter and the DatabaseCleanupInterval member (in minutes) after converting to milliseconds is greater than 0xFFFFFFFF, return ERROR_ARITHMETIC_OVERFLOW. Else if Set_DatabaseCleanupInterval is set in the FieldsToSet parameter, then set/modify the DatabaseCleanupInterval member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_DebugFlag is set in the FieldsToSet parameter, set/modify the DebugFlag member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • Return ERROR_SUCCESS to the caller.

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