ITAddress::Forward method (tapi3if.h)

Article
02/22/2024

The Forward method forwards calls destined for the address according to the forwarding instructions contained in ITForwardInformation. If pForwardInfo is set to NULL, forwarding is canceled.

Syntax

HRESULT Forward(
  [in] ITForwardInformation *pForwardInfo,
  [in] ITBasicCallControl   *pCall
);

Parameters

[in] pForwardInfo

Pointer to ITForwardInformation interface, or set to NULL to cancel forwarding.

[in] pCall

Pointer to ITBasicCallControl interface for the consultation call, if required by the telephony environment. May be NULL if not required.

Return value

This method can return one of these values.

Return code	Description
S_OK	Method succeeded.
E_INVALIDARG	The address does not support forwarding, or pCall does not point to a valid call.
E_OUTOFMEMORY	Insufficient memory exists to perform the operation.
E_POINTER	The pForwardInfo or pCall parameter is not a valid pointer.
TAPI_E_TIMEOUT	The operation failed because the TAPI 3 DLL timed it out. The timeout interval is two minutes.
LINEERR_	See LineForward for error codes returned from this TAPI 2.1 function.

Remarks

The information in pForwardInfo overrides any previous forwarding instructions.

If ITAddress::put_DoNotDisturb is called with fDoNotDisturb set to VARIANT_FALSE, all forwarding is canceled.

An application can determine whether non-NULL consultation call is required by calling ITAddressCapabilities::get_AddressCapability (AC_ADDRESSCAPFLAGS, plCapability) and checking whether the flag LINEADDRCAPFLAGS_FWDCONSULT, a member of LINEADDRCAPFLAGS_ Constants, has been set in plCapability. If it is set, a non-NULL value is required for the pCall parameter of the Forward method.

The Forward method is, in part, a COM wrapper for the TAPI 2.1 LineForward function.

Requirements

Requirement	Value
Target Platform	Windows
Header	tapi3if.h (include Tapi3.h)
Library	Uuid.lib
DLL	Tapi3.dll