3.2.4.97 R_DhcpV4FailoverGetScopeRelationship (Opnum 96)

  • Article

The R_DhcpV4FailoverGetScopeRelationship method retrieves the failover relationship information which is configured for a specific IPv4 subnet address. The caller of this function can free the memory pointed to by the pRelationship parameter by calling the function midl_user_free (section 3).

 DWORD R_DhcpV4FailoverGetScopeRelationship(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DHCP_IP_ADDRESS scopeId,
   [out] LPDHCP_FAILOVER_RELATIONSHIP* pRelationship
 );

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

scopeId: This is of type DHCP_IP_ADDRESS data type (section 2.2.1.2.1) that contains the IPv4 subnet address which is configured as part of a failover relationship.

pRelationship: This is a pointer of type LPDHCP_FAILOVER_RELATIONSHIP (section 2.2.1.2.98) that contains the failover relationship which has the scopeId parameter configured as part of the pScopes member in the pRelationship parameter.

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 any generic failure.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00004E93

ERROR_DHCP_FO_SCOPE_NOT_IN_RELATIONSHIP

IPv4 subnet is not part of the failover relationship.

The opnum field value for this method is 96.

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.

    • scopeId parameter is 0.

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

  • Iterate through the server ADM element DHCPv4FailoverRelationshipList, and retrieve the DHCPv4FailoverRelationship ADM element which has the scopeId parameter configured as part of the pScopes member of the DHCP_FAILOVER_RELATIONSHIP structure (section 2.2.1.2.98). If the corresponding ADM element DHCPv4FailoverRelationship is not found, return ERROR_DHCP_FO_SCOPE_NOT_IN_RELATIONSHIP, else allocate the memory for the pRelationship parameter, and copy the failover relationship information from the retrieved DHCPv4FailoverRelationship ADM element entry in the allocated memory.

  • Return ERROR_SUCCESS.

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