The R_DhcpV4FailoverAddScopeToRelationship method adds scopes to an existing failover relationship.

 DWORD R_DhcpV4FailoverAddScopeToRelationship(
   [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 structure (section 2.2.1.2.98) that contains information about the failover relationship to which scopes as specified in the pScopes member of the pRelationship parameter are to be added.

Return Values: A 32-bit unsigned integer value that indicates 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.
0x00004E91 ERROR_DHCP_FO_SCOPE_ALREADY_IN_RELATIONSHIP	IPv4 scope is already part of another failover relationship.
0x00004E92 ERROR_DHCP_FO_RELATIONSHIP_DOES_NOT_EXIST	Failover relationship does not exist.
0x00004EA5 ERROR_DHCP_FO_SCOPE_SYNC_IN_PROGRESS	Failover relationship is being re-integrated with the failover partner server.
0x00004E98 ERROR_DHCP_FO_STATE_NOT_NORMAL	Failover relationship is not in the NORMAL state.

The opnum field value for this method is 94.

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

• 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 pScopes member of the pRelationship parameter is NULL.

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

• 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 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 have 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 there are no elements in the DHCPv4FailoverRelationshipList ADM element, return ERROR_FILE_NOT_FOUND; otherwise, iterate through the DHCPv4FailoverRelationshipList ADM elements, and 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, return ERROR_DHCP_FO_SCOPE_ALREADY_IN_RELATIONSHIP.

• Iterate through the server ADM element DHCPv4FailoverRelationshipList, and retrieve the DHCPv4FailoverRelationship ADM element corresponding to the relationshipName member of the pRelationship parameter. If the corresponding DHCPv4FailoverRelationship ADM element is not found, return ERROR_DHCP_FO_RELATIONSHIP_DOES_NOT_EXIST.

• If the retrieved DHCPv4FailoverRelationship ADM element's state member is not a NORMAL enumeration value, return ERROR_DHCP_FO_STATE_NOT_NORMAL, or, if the relationship is re-integrating with the partner server, return ERROR_DHCP_FO_SCOPE_SYNC_IN_PROGRESS. Otherwise, add the IPv4 subnets passed in the pScopes member of the pRelationship parameter to the retrieved DHCPv4FailoverRelationship ADM element's pScope member.

• For each of the input IPv4 subnet addresses passed in the pScopes member of 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 [MS-RPCE].