EPOC   SDK Home Glossary Indexes Previous Next Up

CFaxTransfer class


Contents


CFaxTransfer class — Send or receive a fax

Section Contents


Overview

Derivation

CBase

Abstract: CBase behaviour

CFaxTransfer

The fax client.

Defined in

cfax32.h

Link against

faxcli.lib

Description

This class contains the public client API for the EPOC fax client.

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.

Writing derived classes

This class is not intended for user derivation


Construction and destruction


NewL() — Create new fax client object

static CFaxTransfer* NewL(const TFaxSettings& aFaxSettings);

Description

Use this function to construct a CFaxTransfer object, which offers the publicly exported EPOC fax API.

Arguments

const TFaxSettings& aFaxSettings

A reference to a TFaxSettings object, which contains persistent information applicable to all fax sessions.

Return value

CFaxTransfer*

A pointer to the newly created object.

Leave considerations

The 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 error codes.


NewLC() — Create new fax client object

static CFaxTransfer* NewLC(const TFaxSettings& aFaxSettings);

Description

Use this function to construct a CFaxTransfer object, which offers the publicly exported EPOC fax API. As is usual in EPOC, the only difference between this function and NewL() is that this variant pushes the object to the cleanup stack.

Arguments

const TFaxSettings& aFaxSettings

A reference to a TFaxSettings object which contains persistent information applicable to all fax sessions.

Return value

CFaxTransfer*

Pointer to the newly created object.

Leave considerations

The 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 error codes.


~CFaxTransfer() — Destructor

~CFaxTransfer();

Description

The destructor frees all resources owned by the object, prior to its destruction.


Preparing to send and receive faxes

These functions are used to set up the fax system to send or receive. The functions must be called before the functions in the section Sending and receiving faxes.


SetMode() — Set type of fax session

void SetMode(TFaxMode aMode);

Description

This function must be called before CFaxTransfer::Start() and determines the mode of operation during the fax session.

There are three possible transmission modes:

There are four possible reception modes:

Arguments

TFaxMode aMode

Type of fax operation for the current session.

Note

SetPhoneNumberL() — Resolve then set fax destination phone number

void SetPhoneNumberL(TDesC8& aNumber);

Description

This function 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.

Arguments

TDesC8& aNumber

Descriptor containing the phone number to be resolved.

Note

SetPhoneNumber() — Set fax destination phone number

void SetPhoneNumber(TDesC8& aNumber);

Description

This function 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.

Arguments

TDesC8& aNumber

Descriptor containing the phone number to be dialled.

Note

AddSourceL() — Specify fax pages to be transmitted

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

Description

This function 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().

Arguments

const TFileName& aFaxPageStore

Name of the fax store file from which to take pages.

TInt aStartPage

Page in file to start from. If omitted, the file is sent from the start.

TInt aEndPage

Page in file to stop sending. If omitted, transmission continues to the end.

Note

RemoveAllSources() — Clear list of pages to be transmitted

void RemoveAllSources();

Description

This function 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.


SetReceiveFileName() — Sets file name for received fax

void SetReceiveFileName(const TFileName& aName);

Description

This function must be called before CFaxTransfer::Start() when a fax is to be received. It specifies the name of the fax store file in which to save incoming pages. If the file already exists the previous contents are lost.

Arguments

const TFileName& aName

The name of a file in which to save received faxes.


Sending and receiving faxes


Start() — Launches fax session thread

TInt Start(TRequestStatus& aThreadStat);

Description

This function 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 Fax 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.

Arguments

TRequestStatus& aThreadStat

A request status indicating the reason for the termination of the fax thread. A value of KErrNone indicates a successful session, with fax specific errors listed in Fax error codes. See Asynchronous programming for a detailed discussion of how to use TRequestStatus.

Return value

TInt

An error code: see System error codes.


Progress() — Update fax progress structure

TInt Progress();

Description

This function causes ETel to update the fax progress information in RFax::TProgress. It should be called prior to displaying the fax progress information.

Return value

TInt

An error code: see System error codes.


Cancel() — Cancels fax session

void Cancel();

Description

This function 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().


Stop() — Kills fax session thread

void Stop();

Description

This function 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().


Data members

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

The fax progress.

EPOC       SDK Home Glossary Indexes Previous Next Up