Class CFaxTransfer

CFaxTransfer

Support

Supported from 5.0

Description

Send or receive a fax

Contains the public Fax Client API.

The API includes a number of functions for setting up a fax, and then for sending it. Functions to set up a fax allow the client to launch a fax client session, set the fax mode, set the fax destination number, define the fax pages to be sent, and declare a file in which received faxes are to be stored. After setting up, the client can send, cancel and monitor the progress of the fax.

This class is not intended for user derivation.

Derivation

Defined in CFaxTransfer:
AddSourceL(), Cancel(), NewL(), NewLC(), Progress(), RemoveAllSources(), SetMode(), SetPhoneNumber(), SetPhoneNumberL(), SetReceiveFileName(), Start(), Stop(), iProgress, ~CFaxTransfer()

Inherited from CBase:
operator new()

static CFaxTransfer* NewL(const TFaxSettings& aFaxSettings);

Description

Constructs a CFaxTransfer object, which offers the publicly exported Symbian OS Fax Client API.

Parameters

Return value

Leave codes

static CFaxTransfer* NewLC(const TFaxSettings& aFaxSettings);

Description

Constructs a CFaxTransfer object, which offers the publicly exported Symbian OS Fax Client API. As is usual in Symbian OS, the only difference between this function and NewL() is that this variant pushes the object to the cleanup stack.

Parameters

Return value

Leave codes

~CFaxTransfer();

Description

Destructor

Frees all resources owned by the object, prior to its destruction.

Description

Sets up the fax system to send or receive. The functions must be called before the sending and receiving functions.

void SetMode(TFaxMode aMode);

Description

Sets the mode of operation during the fax session.

There are three possible transmission modes:

• A standard fax machine style dial and transmit.

• An immediate transmit mode which is used if the phone is already off-hook on a voice call.

• A polling mode, in which the fax is set up as an answering machine. It sends the fax on request when dialled by a remote modem.

There are four possible reception modes:

• A standard fax machine style wait for a ring and receive.

• An immediate receive which is used if the phone is already off-hook on a voice call.

• A dial and receive mode in which the modem dials up in voice mode and then switches to immediate receive. It is intended for use with faxback services which require users to dial manually and then press the start button on their fax machine. The number of seconds between the voice mode dial and the switch to fax receive mode is determined by TFaxSettings::iFaxOnDemandDelay.

• An automatic polling mode, in which the fax dials a remote answering machine, and requests it to send a fax.

Parameters

Notes:

• Some GSM networks do not allow switching between voice and fax or data modes, and hence cannot support the immediate transmit and immediate receive modes. This includes all networks in the UK.

void SetPhoneNumberL(TDesC8& aNumber);

Description

Resolves a local telephone number into an international number by taking account of the current location and country.

The resolved number is then set as the actual phone number to dial.

Parameters

Notes:

• The alternative SetPhoneNumber() should be used if the phone number must be used in its raw state. One of these functions must be called before CFaxTransfer::Start() when a fax is to be sent.
• This function may leave with KErrNoMemory if there is insufficient memory to perform the operation. The leave code is one of the system error codes: see system-wide error codes.
• The current location and country information is obtained from the location table in the communications database.

void SetPhoneNumber(TDesC8& aNumber);

Description

Sets the telephone number to be dialled when sending a fax.

This function does not check the validity of the number, which is simply sent to the modem as part of an ATD dial command in its raw state.

Parameters

Notes:

• The alternative function SetPhoneNumberL() should be used to resolve the phone number according to the current location and country. One of these functions must be called before CFaxTransfer::Start() when a fax is to be sent.

void AddSourceL(const TFileName& aFaxPageStore);
void AddSourceL(const TFileName& aFaxPageStore, TInt aStartPage);
void AddSourceL(const TFileName& aFaxPageStore, TInt aStartPage, TInt aEndPage);

Description

Specifies which pages of a fax store file should be sent.

It can be called more than once to add multiple pages from different files. Typically, this function is called twice for each transmission: once to queue the cover sheet, and a second time to queue the remainder of the fax.

The overloaded variants are supplied primarily to help error recovery in cases when a fax transmission is either incomplete or when specific pages need to be resent. When transmitting a fax, at least one variant of this function must be called before CFaxTransfer::Start().

Parameters

Notes:

• This function may leave with KErrNoMemory if there is insufficient memory to perform the operation. The leave code is one of the system error codes: see system-wide error codes.

void RemoveAllSources();

Description

Clears the complete list of pages previously selected for faxing using one of the variants of AddSourceL().

Removal of individual items from the list of pages to be fax is not possible.

This function must be used between successive fax transmissions if previously sent pages aren't to be sent again.

void SetReceiveFileName(const TFileName& aName);

Description

Specifies the name of the fax store file in which to save incoming pages.

If the file already exists the previous contents are lost.

Parameters

TInt Start(TRequestStatus& aThreadStat);

Description

Starts the fax session by detaching a high priority fax thread which runs independently of the user thread.

This function can only be called asynchronously. The same function is used for both sending and receiving, with the precise operation having been determined by a prior call to SetMode().

Start() calls RThread::Create() to launch a thread and returns with either KErrNone if successful or KFaxThreadError if the thread could not be launched. The possible reasons for session termination are trapped in the TRequestStatus which the caller should be waiting on in an asynchronous loop or active object. This can return a wide variety of error codes as well as any of the usual system error codes.

The function must always be paired with a call to CFaxTransfer::Stop() to kill the thread after the fax session terminates.

Parameters

Return value

TInt Progress();

Description

Causes ETel to update the fax progress information in RFax::TProgress.

It should be called prior to displaying the fax progress information.

Return value

void Cancel();

Description

Tells the fax engine to cancel the fax session at the first convenient opportunity.

The caller should wait for cancellation to complete, which will usually be signalled by the fax thread's TRequestStatus completing with a KFaxCancelRequested error code. After the fax thread completes, Stop() should be called in the normal way.

The function can be called at any time after the call to Start().

void Stop();

Description

Kills the fax thread once it has completed.

Fax threads do not kill themselves, so every successful call to CFaxTransfer::Start() must be paired with a call to CFaxTransfer::Stop().

Description

There are a number of data members with public access, however only the progress information variable is part of the public API.

RFax::TProgress iProgress

Description

The fax progress.