IFaxDoc::put_CallHandle

The IFaxDoc::put_CallHandle method changes the CallHandle property for a FaxDoc object. The CallHandle property is a call handle for an active inbound TAPI 2.x call that can enable transmission of a fax using an existing line connection.

Note  The CallHandle property is available for use only by C/C++ fax client applications. Visual Basic applications cannot use this property because Visual Basic cannot make calls to TAPI 2.x functions. Visual Basic fax client applications can use the ConnectionObject property instead to transmit a fax using an existing line connection.

Visual Basic Reference

HRESULT put_CallHandle(
  LONG newVal  // new value for TAPI 2.x call handle
);

Parameters

newVal

[in] Specifies the new value to assign to the optional CallHandle property. This parameter must be a call handle returned by the TAPI 2.x LINE_CALLSTATE message. The value of this parameter is an HCALL data type that has been cast to a LONG data type.

If you specify a valid call handle, 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

To transmit a fax using an existing line connection, set the CallHandle property before you call the IFaxDoc::Send method. If you set the CallHandle property, the fax server transmits the fax using the existing line connection instead of initiating a new call. The call handle must be one retrieved by the TAPI 2.x LINE_CALLSTATE message. For more information, see Transmitting a Fax to an Active Inbound Call.

To successfully transmit a document using an existing inbound line connection, the call must be in the LINECALLSTATE_CONNECTED state. The underlying hardware must also support turning a call around. For more information, see LINE_CALLSTATE and LINECALLSTATE_ Constants, both in the TAPI documentation.

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 ConnectionObject property, call the IFaxDoc::putref_ConnectionObject property.

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::get_CallHandle, IFaxDoc::Send, IFaxDoc::put_FaxNumber, IFaxDoc::putref_ConnectionObject