IFaxDoc::putref_ConnectionObject

The IFaxDoc::putref_ConnectionObject method stores a reference to a TAPI 3.0 call object in a FaxDoc object. The ConnectionObject property enables transmission of a fax using an existing line connection.

Note  The ConnectionObject property is available for use by both Visual Basic and C/C++ fax client applications. This property provides complete COM-based functionality when transmitting a fax using an existing line connection. Visual Basic applications cannot use the CallHandle property because Visual Basic cannot make the required calls to TAPI 2.x functions.

Visual Basic Reference

HRESULT putref_ConnectionObject(
  IDispatch *newVal // specifies IDispatch pointer to TAPI 3.0 object
);

Parameters

newVal

[in] Pointer to a VARIANT structure that contains an IDispatch interface pointer to a TAPI 3.0 call object. If you specify a valid TAPI 3.0 call object, you can transmit a fax document to an active call in a cost-effective manner. This is known as a "faxback service." For more information, see the following Remarks section.

Return Values

Returns an HRESULT value indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns a COM-defined error code.

You should not check directly for success or failure. Use the COM SUCCEEDED and FAILED macros instead.

Remarks

Before you store a reference to a TAPI call object in the FaxDoc object, you must ensure that the connection was established using a TAPI 3.0 call object. For more information about TAPI 3.0 objects, see Using Basic Call and Media Controls.

To transmit a fax using an existing line connection, set the ConnectionObject property before you call the IFaxDoc::Send method. If you set the ConnectionObject property, the fax server transmits the fax using the existing line connection instead of initiating a new call.

To successfully transmit a document using an existing inbound line connection, the call must be in the CS_CONNECTED CALL_STATE. The underlying hardware must also support turning a call around. For more information, see Transmitting a Fax to an Active Inbound Call.

If you do not set the CallHandle property or the ConnectionObject property, you must set the FaxNumber property to successfully transmit a fax document. If you set more than one of these three properties, the fax server uses the FaxNumber property to send the call.

To set the FaxNumber property, call the IFaxDoc::put_FaxNumber method. To set the CallHandle property, call the IFaxDoc::put_CallHandle method.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxcom.h.
  Import Library: Included as a resource in faxcom.dll.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Interfaces, IFaxDoc, IFaxDoc::Send, IFaxDoc::put_FaxNumber, IFaxDoc::put_CallHandle