The R_DhcpV4FailoverGetRelationship method retrieves the failover relationship information configured 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_DhcpV4FailoverGetRelationship( [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress, [in, string, unique] LPWSTR pRelationshipName, [out] LPDHCP_FAILOVER_RELATIONSHIP* pRelationship );
ServerIpAddress: The IP address/host name of the DHCP server. This parameter is unused.
pRelationshipName: A pointer to a null-terminated Unicode string that contains the name of the failover relationship for which the information is retrieved. There is no limit on the length of this Unicode string.
pRelationship: This is a pointer of type LPDHCP_FAILOVER_RELATIONSHIP (section 2.2.1.2.98) in which the information about the failover relationship is retrieved based on the pRelationshipName 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. |
|
0x00004E92 ERROR_DHCP_FO_RELATIONSHIP_DOES_NOT_EXIST |
The failover relationship does not exist. |
The opnum field value for this method is 92.
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.
pRelationshipName parameter is NULL.
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 corresponding to pRelationshipName parameter. If the corresponding ADM element DHCPv4FailoverRelationship is not found, return ERROR_DHCP_FO_RELATIONSHIP_DOES_NOT_EXIST, otherwise, allocate memory for the pRelationship parameter, and copy the failover relationship information from the retrieved DHCPv4FailoverRelationship ADM entry in the allocated memory.
Return ERROR_SUCCESS.
Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].