IFaxDoc::get_CallHandle

The IFaxDoc::get_CallHandle method retrieves the CallHandle property for a FaxDoc object. The CallHandle property is a call handle for an active inbound TAPI 2.x call. Setting this property enables 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 get_CallHandle(
  LONG  *pVal  // receives TAPI 2.x call handle
);

Parameters

pVal

[out] Specifies an optional 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.

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.

For more information, see Transmitting a Fax to an Active Inbound Call.

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::put_CallHandle, IFaxDoc::Send