3.2.4.91 R_DhcpV4FailoverSetRelationship (Opnum 90)

  • Article

The R_DhcpV4FailoverSetRelationship method is used to modify an existing failover relationship on the DHCPv4 server.

 DWORD R_DhcpV4FailoverSetRelationship(
     [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
     [in] DWORD  Flags,
     [in] LPDHCP_FAILOVER_RELATIONSHIP pRelationship
 );

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

Flags: A DWORD type that contains the bitmask of the members in the pRelationship parameter structure to be updated. The bit mapping for the various values for the flags parameter is listed in the following table.

Value

Meaning

MCLT

0x00000001

Update the mclt member of DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) to the value specified in the mclt member in pRelationship parameter.

SAFEPERIOD

0x00000002

Update the safePeriod member of DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) to the value specified in the safePeriod member in pRelationship parameter.

CHANGESTATE

0x00000004

Update the state member of DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) to the value specified in the state member in pRelationship parameter.

PERCENTAGE

0x00000008

Update the percentage member of DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) to the value specified in the percentage member in pRelationship parameter.

MODE

0x00000010

Update the mode member of DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) to the value specified in the mode member in pRelationship parameter.

PREVSTATE

0x00000020

Update the prevState member of DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) to the value specified in the prevState member in pRelationship parameter.

pRelationship: This is a pointer to a type DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98) that contains information about the failover relationship to be modified on the DHCPv4 server.

Return Values: A 32-bit unsigned integer value that indicates return status. The return value 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 20123, or any generic failure.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00004E92

ERROR_DHCP_FO_RELATIONSHIP_DOES_NOT_EXIST

The failover relationship doesn’t exist.

The opnum field value for this method is 90.

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

  • Return ERROR_INVALID_PARAMETER if any of the following are true:

    • pRelationship parameter is NULL.

    • relationshipName member of pRelationship parameter is NULL.

    • flags parameter is 0.

    • flags parameter is set to any value other than the valid bitmasks as specified in the preceding table .

    • PERCENTAGE constant is set in the flags parameter and percentage member of pRelationship parameter is greater than 100.

    • MODE constant is set in the flags parameter and the mode member of pRelationship parameter is not set to LoadBalance enumeration value and is not set to HotStandby enumeration value.

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

  • Iterate through all the elements in DHCPv4FailoverRelationshipList ADM element and retrieve the DHCPv4FailoverRelationship ADM element corresponding to the relationshipName member in pRelationship parameter. If the corresponding DHCPv4FailoverRelationship ADM element is not found return ERROR_DHCP_FO_RELATIONSHIP_DOES_NOT_EXIST, else update the retrieved DHCPv4FailoverRelationship ADM element based on the passed in flags parameter and corresponding values in pRelationship parameter object as described in the preceding table.

  • Return ERROR_SUCCESS.

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