EPOC   SDK Home Glossary Indexes Previous Next Up

Fax client API


Contents


Overview

The fax client implements the fax transport protocols defined in the ITU-T T.30 specification. While these are well established protocols, which have been providing reliable fax transfers on all types of phone lines for decades, they are technically very demanding. They combine half-duplex session negotiations which rely for their integrity on very tight command/response synchronisation with real-time unidirectional data streaming which lacks proper flow control.

Applications that wish to become fax-enabled should use the API provided by the client, which frees them from having to worry about any complex timing constraints. They need only create a CFaxTransfer object. This provides a number of utility functions which need to be called before a fax session is begun, such as setting a destination number for faxes that need to be transmitted or a destination file name for faxes that are to be received.

Once the session is set up, an asynchronous call to a Start() function launches the session — which is equivalent to pressing the start button on a fax machine. This spawns a separate high-priority fax thread, which is where all the real-time constraints of the fax session are met. Although a Cancel() function is provided, this thread normally runs to completion with no user intervention, after which a complementary Stop() function is used to remove the now-dormant fax thread.

Because the Start() function is inherently asynchronous, an understanding of the way that EPOC handles such services is required for the fax API to be used effectively — see Asynchronous programming.

The following sections describe the role of ETel in faxing, the supported fax classes, the error handling and progress reporting functionality, the phase model, and the location of persistent fax settings.


ETel and its fax client

The fax client is part of ETel. ETel is used to abstract control over the many different types of telephone device which can be connected to or integrated with an EPOC computer, such as conventional analog modems, digital ISDN adapters, cable modems, and mobile phone handsets. All the commands used to control such devices are encapsulated within the ETel server, which is able to service all the various applications which need to access the phone, and arbitrate between their sometime competing demands. Clients are offered a simplified API to perform all commonly required phone functions irrespective of the actual device in use.

Faxing does not fit into the ETel model in exactly the same way as other forms of data communication. This is because even when the actual command sets used by fax modems are abstracted away, there remains a very tight real-time coupling between a fax server and its clients. The level of command/response synchronisation — of the order of 75 ms — together with the real-time unidirectional fax data streaming, which lacks proper flow control, makes sending and receiving faxes quite demanding.

So while ETel does includes server-side RFax objects, the associated APIs are not intended for use by any modules apart from ETel’s own fax client. There isn’t any need to open a session with ETel directly in order to use a phone’s fax facilities, since all fax functionality is accessible through the API of the client DLL. All that an application has to do is create a CFaxTransfer object.


Fax modems

The fax client does its work by controlling fax modems, which come in one of three distinct varieties.

All these modems implement different AT+F commands for controlling a fax session. However, users of the fax client don’t need to know anything at all about how this is done. The fax client creates a CFaxModemDriver object which is an abstraction of the behaviour of all fax modems and encapsulates all modem behaviour. This is the base class from which the drivers for controlling each of the fax modem classes derive. It is in principle possible to derive new fax modem drivers from CFaxModemDriver to drive different fax devices, including ones that don’t support any AT commands at all. However, in practise the behaviour of all currently available fax modem devices is standard enough to make this unnecessary, and it is therefore not supported in the developer SDK. Note also that it isn’t strictly necessary to know what command set a fax modem supports in advance, since automatic detection of a suitable class is supported.

Each of the fax modem drivers create a CFaxModem object (defined in faxmodem.h) which loans the port from ETel and issues commands to the modem.


Progress reporting

The fax client provide a mechanism for fax progress reporting during a session. As well as information about the transfer itself, such as the number of the page being transferred, this includes other information resulting from the fax negotiations — such as the remote ID, the session speed, and the internal format of the fax.

The client-server structure of ETel means that the client-side API doesn’t have access to the memory used by the server-side fax modem driver. Copying the entire structure from the server to the client on demand, using standard client-server message passing mechanisms, is undesirable since the associated real-time overheads, though small, are significant. Consequently, the RFax::TProgress structure is implemented client-side, and is made accessible to server-side modules as a global memory chunk — see global memory chunks. The Progress() function signals ETel to update the fax client’s TProgress by copying across the fax server’s version, and should therefore be called as a preliminary each time the progress structure is to be read.


Error handling

If the session fails for any reason, there is a rich range of error codes to help in diagnosing the cause of a failure; see Fax error codes. It is necessary to know a little about the structure of a fax session — discussed in “Fax phases” below — to understand both the progress reporting and the error handling provided by the fax client.

The action to be taken in the event of receiving an error is dependent both on the error, and on the fax phase when the error was received. If an error occurs in the early phases of transmission then the appropriate action is usually to re-send the fax. If an error occurs when a partial fax has been transferred, it may be possible to re-send only part of the fax. If an error is returned in the final phase, then the fax may have been completely sent — so the error can possibly be ignored.

In addition to the error handling provided by the error codes, a fax log is always kept of the most recent fax session, showing all the modem dialogues and timings. This is done primarily for technical support and as a development aid. Unlike other communications logging in EPOC, the fax log is always created and cannot be switched off. It can always be found as faxlog.txt in the c:\logs\fax directory (if one exists) or else in c:\system. The reason why the fax log cannot be disabled is to ensure consistent behaviour for the fax client. The timing constraints of the T.30 fax protocol require fairly precise timings of ±75 ms, and turning logging on or off would affect timings of this order.


Fax phases

The T.30 protocol defines five distinct phases in sending or receiving a fax.

The T.30 fax phases

The current phase of a session is part of the information which is available for inspection in an RFax::TProgress structure. The CFaxTransfer::Progress() function causes ETel to update the structure, enabling the state of a fax session to be displayed to the user at any time. This is quite important as fax sessions can run for some time.

EPOC       SDK Home Glossary Indexes Previous Next Up