The R_DhcpV4FailoverEnumRelationship method enumerates all the failover relationships on the DHCPv4 server. 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_DhcpV4FailoverEnumRelationship(
     [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
     [in, out] DHCP_RESUME_HANDLE *ResumeHandle,
     [in] DWORD preferredMaximum,
     [out] LPDHCP_FAILOVER_RELATIONSHIP_ARRAY *pRelationship,
     [out] LPDWORD relationshipRead,
     [out] LPDWORD relationshipTotal
);

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

ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (section 2.2.1.2.6) that identifies the enumeration operation. Initially, this value MUST be set to zero, with a successful call returning the handle value used for subsequent enumeration requests.

preferredMaximum: This is of type DWORD, specifying the preferred maximum number of bytes to be returned. If the number of bytes required in memory for the remaining unenumerated failover relationships is less than the PreferredMaximum parameter value, then all the remaining failover relationships for the DHCP server are returned.

pRelationship: This is a pointer of type LPDHCP_FAILOVER_RELATIONSHIP_ARRAY (section 2.2.1.2.99) in which information about all the failover relationships defined on the DHCP server is retrieved.

relationshipRead: This is a pointer to a DWORD value that specifies the number of failover relationships returned in the pRelationship parameter. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

relationshipTotal: This is a pointer to a DWORD value that specifies the number of failover relationships defined on the DHCP server that have not yet been enumerated. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

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.
0x000000EA ERROR_MORE_DATA	There are more elements available to enumerate.
0x00000103 ERROR_NO_MORE_ITEMS	There are no more elements left to enumerate.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x000000EA

ERROR_MORE_DATA

There are more elements available to enumerate.

0x00000103

ERROR_NO_MORE_ITEMS

There are no more elements left to enumerate.

The opnum field value for this method is 93.

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.
- relationshipRead parameter is NULL.
- relationshipTotal parameter is NULL.
Retrieve the DHCPv4FailoverRelationshipList ADM element.
If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of DHCPv4FailoverRelationshipList ADM element. Otherwise, if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle parameter. If ResumeHandle parameter is greater than or equal to the number of entries in the DHCPv4FailoverRelationshipList ADM element or if the DHCPv4FailoverRelationshipList ADM element is empty, return ERROR_NO_MORE_ITEMS.
The PreferredMaximum parameter specifies the maximum number of bytes that the server can allocate and return to the caller containing the data related to the DHCPv4FailoverRelationship ADM element objects retrieved. If the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server must allocate the PreferredMaximum parameter number of bytes for the pRelationship parameter and store as many DHCPv4FailoverRelationship ADM element entries as will fit into the pRelationship parameter; else, allocate the memory for the DHCP_FAILOVER_RELATIONSHIP_ARRAY structure (section 2.2.1.2.99) for the total number of DHCPv4FailoverRelationship ADM element entries available in the retrieved list, starting from the index specified by the ResumeHandle parameter and continuing to the end of the failover relationship list.
Copy the information in the retrieved DHCPv4FailoverRelationship ADM element entries in the pRelationship parameter, copy the number of read DHCPv4FailoverRelationship ADM element entries in the relationshipRead parameter, and copy the number of the DHCPv4FailoverRelationship ADM element entries not yet enumerated in the relationshipTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the DHCPv4FailoverRelationship ADM element entry read.
If the PreferredMaximum parameter was able to hold all the entries being retrieved, return ERROR_SUCCESS; otherwise return ERROR_MORE_DATA.

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