EPOC   SDK Home Glossary Indexes Previous   Up

Fax header line API


Contents


Overview

In common with all fixed stand-alone fax machines, and because it is a legal requirement in many countries, all faxes sent by the ETel fax client have a header line inserted at the top of each page. This line includes the page number, the time and the date of transmission, and the identity and phone number of the sender.

Since the time and the date are not known until the receiving fax has actually answered, the header has to be generated by the fax engine in real time. It cannot be fully encoded prior to sending in the same way as the rest of the image. To overcome this problem a fax header line template is partially prepared in advance — with empty spaces for the information which must be supplied at send-time. When this information is known, the appropriate characters are selected from a pre-prepared font bitmap, and inserted into the empty positions. This makes generation of a fax header in real-time both reliable and simple.

The header line template, font bitmap, and the information needed to create the header line file from them, are stored in a header line data file. The API discussed in this document includes the classes used to create and read the fax header line data file, and the class used to perform scan line encoding and decoding.

If the EPOC device has a licence which includes the Email application, the fax MTM is used to generate this header line data file. The fax server then takes the data file, creates the header line, and appends it to each fax page. If Email is not present then this API can be used to localise the header line file, or to generate a header line for EPOC devices that do not include the EPOC Email application.


The fax header data file

Section Contents

The header line template, font bitmap, and the additional information required to generate the header line, are stored in the header line data file — c:\system\faxhead.dat. The header line data file defines the layout and formatting of the header line. It must be regenerated each time the user identity or phone number changes.

Consequently, the fax engine needs to have no knowledge of any locale-specific information — all of this detail is handled whatever code produces the header line data file. The only two assumptions made are that the date, time, and page information can be accurately conveyed by inserting decimal characters at the appropriate places, and that the collating sequence for the digits 0123456789 remains constant across all character sets.

The information stored in the header line data file is described in detail below.

The fax header template bitmap

The fax header template contains the header line information known prior to sending the fax.

The template must be exactly 1728 pixels wide, including a margin of approximately 74 pixels at the start and end of each line. There is no restriction on the height. Also, the text in the bitmap must be generated using a fixed width font.

The font bitmap

The font bitmap is a line containing the 10 digits “0123456789”. When the send-time information is known, the fax server inserts the appropriate characters from this file into the gaps in the fax header template.

The font bitmap must have no margins, and should be in the same fixed width font as was used to create the header line template. Knowledge of the font dimensions — number of bytes wide and height in rows — allows individual characters to be extracted from the font bitmap.

The font dimensions and header line offsets

To generate a header line using the above bitmaps requires that the font dimensions, and the offsets to the gaps in the template where send time information is to be inserted, are known. This information is stored in the header line data file along with the header template and font bitmap.


Creating/writing the fax header line data file

The fax header line data file is not read from or written to directly by either the fax engine or the fax MTM. The only access to this file is through the CFaxHeaderLines class, which contains functions to read and write the fax header information and, once that has been done, to read and write raw header lines and font line data.

To use CFaxHeaderLines, first call WriteFaxHeaderInfoL() to create and open the new header line data file. The function also adds the font dimension and send-time field offset information, contained in a TFaxHeaderInfo object, to the file. WriteRawFontLineL() and WriteRawHeaderLineL() should then be called to add the header line template and the font bitmap.

The header line template bitmap and the font line bitmap can be generated by means of a fax print-to-file in the normal way. The width of the non-proportional font used to generate the header must be a multiple of 8 bytes. This means that the task of inserting the correct digits in the header line is made substantially easier and quicker. Unfortunately, there are limits on the possible width of the font used. Based on the recommended minimum margin specified in T4, and the text which has to be placed on the line, the maximum width font which should be used is 24 bits. While this gives room for just 65 characters on the header line, crowding should not be a problem in practice, since it is unlikely that all the 20 characters permitted in the fax and user ids would be used.

Only one header is generated irrespective of resolution — scan lines are sent once in normal resolution and twice in fine resolution. Note that currently the header is inserted at the top of each fax page — making the fax as sent marginally longer than the original image.


Reading the fax header line data file

The fax header data file is read by the fax server, and used to create a new fax header line every time a page is sent.

The ReadFaxHeaderInfoL() is invoked first to open the file and read the font dimension and send-time field offset information. ReadRawFontLineL() and ReadRawHeaderLineL() should then be called to get the header line template and the font bitmap.

If the fax header file cannot be read, the session terminates prematurely with KErrNotFound.

EPOC       SDK Home Glossary Indexes Previous   Up