ITAddress::Forward method (tapi3if.h)

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(
  ITForwardInformation *pForwardInfo,
  ITBasicCallControl   *pCall
);

Parameters

pForwardInfo

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

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

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

See also

Address Object

Forward overview

ITAddress

ITAddress::CreateForwardInfoObject

ITAddress::get_CurrentForwardInfo

ITForwardInformation

LineForward