3.1.4.26 R_DhcpServerSetConfig (Opnum 25)

  • Article

The R_DhcpServerSetConfig method sets/modifies the DHCPv4 server settings. There is an extension method R_DhcpServerSetConfigV4 (section 3.1.4.40) that sets some additional settings on the DHCPv4 server.

 DWORD R_DhcpServerSetConfig(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD FieldsToSet,
   [in, ref] LPDHCP_SERVER_CONFIG_INFO 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 structure to set. This method can be called with a value for FieldsToSet.

The bit mapping for the various values for FieldsToSet 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

The DHCP Server 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 (section 2.2.1.2.53) structure that contains 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 25.

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 ConfigInfo to the server Abstract Data Model (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_DatabaseName bit is set in the FieldsToSet parameter 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 FieldsToSet 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 FieldsToSet, then set/modify the DatabaseName member from the ConfigInfo parameter to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_DatabasePath bit is set in FieldsToSet and the DatabasePath member in ConfigInfo is NULL or is a NULL terminated empty string, then return ERROR_INVALID_PARAMETER. Else if the Set_DatabasePath bit is set in FieldsToSet 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 FieldsToSet, then create the directory with the specified path and set/modify the DatabasePath member from ConfigInfo to the DHCPv4ServerConfigInfo ADM element object.

  • If the Set_BackupPath bit is set in the FieldsToSet parameter and the BackupPath member in ConfigInfo is NULL or is a NULL terminated empty string, then return ERROR_INVALID_PARAMETER. Else if the Set_BackupPath bit is set in FieldsToSet 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 FieldsToSet, then create the directory with the specified path and set/modify the BackupPath member from ConfigInfo to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_BackupInterval is set in FieldsToSet and the BackupInterval member is zero, return ERROR_INVALID_PARAMETER. Else if Set_BackupInterval is set in FieldsToSet 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 FieldsToSet, then set/modify the BackupInterval member from ConfigInfo to the DHCPv4ServerConfigInfo ADM element object.

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

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

  • If Set_DatabaseCleanupInterval is set in FieldsToSet and the DatabaseCleanupInterval member is zero, return ERROR_INVALID_PARAMETER. Else if Set_DatabaseCleanupInterval is set in FieldsToSet 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 FieldsToSet, then set/modify the DatabaseCleanupInterval member from ConfigInfo to the DHCPv4ServerConfigInfo ADM element object.

  • If Set_DebugFlag is set in FieldsToSet, set/modify the DebugFlag member from ConfigInfo 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].