The R_DhcpV4FailoverCreateRelationship method is used to create a new failover relationship on the DHCPv4 server.

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

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

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

Return Values: A 32-bit unsigned integer value that indicates the return status. A return value of 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 to any generic failure.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The call was successful.
0x00004E25 ERROR_DHCP_SUBNET_NOT_PRESENT	IPv4 scope does not exist on the DHCPv4 server.
0x00004E90 ERROR_DHCP_FO_SCOPE_ALREADY_IN_RELATIONSHIP	IPv4 is already part of another failover relationship.
0x00004E91 ERROR_DHCP_FO_RELATIONSHIP_EXISTS	A failover relationship already exists on the DHCPv4 server.
0x00004E9D ERROR_DHCP_FO_RELATIONSHIP_NAME_TOO_LONG	The failover relationship name in the DHCP_FAILOVER_RELATIONSHIP (section 2.2.1.2.98) structure is too long.
0x00004EA0 ERROR_DHCP_FO_MAX_RELATIONSHIPS	The maximum number of allowed failover relationships configured on the DHCP server has been exceeded.

The opnum field value for this method is 89.

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

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

• Return ERROR_INVALID_PARAMETER if any of the following are true:

  • The pRelationship parameter is NULL.

  • The relationshipName member of the pRelationship parameter is NULL.

  • The primaryServer member of the pRelationship parameter is 0.

  • The secondaryServer member of the pRelationship parameter is 0.

  • The pScopes member of the pRelationship parameter is NULL.

  • The NumElements member of the pScopes member of the pRelationship parameter is 0.

  • The Elements member of the pScopes member of the pRelationship parameter is NULL.

  • The percentage member of the pRelationship parameter is greater than 100.

  • The mode member of the pRelationship parameter is not equal to the LoadBalance enumeration value and not equal to the HotStandby enumeration value (section 2.2.1.1.18).

  • The serverType member of the pRelationship parameter is not equal to the PrimaryServer enumeration value and not equal to the SecondaryServer enumeration value (section 2.2.1.1.19).

• Iterate through the DHCPv4ScopesList ADM element on the DHCPv4 server, and if any of the IPv4 subnet addresses in the pScopes member of the pRelationship parameter does not match a corresponding DHCPv4ScopesList.DHCPv4Scope ADM element on the DHCPv4 server, return ERROR_DHCP_SUBNET_NOT_PRESENT.

• For any of the IPv4 subnet addresses passed in the pScopes member of the pRelationship parameter, if the corresponding DHCPv4Scope.DHCPv4IpRange ADM element is of type DhcpIpRangesBootpOnly enumeration value (section 2.2.1.2.38), return ERROR_INVALID_PARAMETER.

• If the length of the string in the pRelationship parameter containing the name of the relationship is greater than 126 Unicode characters, return ERROR_DHCP_FO_RELATIONSHIP_NAME_TOO_LONG. The length of the relationship name does not include the terminating null character.

• If the number of DHCPv4FailoverRelationship ADM element entries in the DHCPv4FailoverRelationshipList ADM element is equal to 31, return ERROR_DHCP_FO_MAX_RELATIONSHIPS.

• Iterate through the DHCPv4FailoverRelationshipList ADM elements, and check if any input IPv4 subnet passed in the pScopes member of the pRelationship parameter is already part of the IPv4 subnets configured on the DHCPv4FailoverRelationshipList.DHCPv4FailoverRelationship ADM element; then return ERROR_DHCP_FO_SCOPE_ALREADY_IN_RELATIONSHIP.

• Iterate through the DHCPv4FailoverRelationshipList ADM elements, and if there already exists an ADM element DHCPv4FailoverRelationshipList.DHCPv4FailoverRelationship corresponding to the relationshipName member in the pRelationship parameter, return ERROR_DHCP_FO_RELATIONSHIP_EXISTS.

• Create a DHCPv4FailoverRelationship ADM element from the input pRelationship parameter (a DHCP_FAILOVER_RELATIONSHIP structure; see section 2.2.1.2.98).

  • Set DHCPv4FailoverRelationship.state to the STARTUP enumeration value and DHCPv4FailoverRelationship.prevState to the INIT enumeration value.

• If the safePeriod member is given as 0, set the DHCPv4FailoverRelationship.safePeriod ADM element to 0xFFFFFFFF. For each of the input IPv4 subnet addresses passed in the pScopes member in the pRelationship parameter, iterate through the DHCPv4ScopesList ADM element and retrieve the corresponding DHCPv4Scope ADM element, and set the DHCPv4Scope.IsFailover ADM element to TRUE.

• Return ERROR_SUCCESS.

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