• Introduction
• About the evaluation version
• Sample application
• How to send faxes
  • FileImageFaxProducer (faxing PDF or HTML Files).
• How to Receive faxes
• API

Introduction

RFax requires:

• fax modem class 1 (recommended) class 2 or class 2.0. This must be an analog modem (no ISDN).
• .NET framework

About the evaluation version

Sample application

RFax comes with a simple application you can use to send your first fax. In order to start the application you must just unzip rfax and execute the file FaxTest10.exe (for .NET 1.0) or FaxTest11.exe (for .NET 1.1):

now you can send a test fax::

1. enter port name (COM1, COM2...)
2. select dialing mode (tone or pulse)
3. select Flow Control (RTS/CTS recommended)
4. select Flow Control Command ( normally AT&K3 fo RTS/CTS, see your modem's documentation).
5. enter destination of fax
6. press "Send fax"

or receive faxes::

1. enter port name (COM1, COM2...)
2. select Flow Control (RTS/CTS recommended)
3. select Flow Control Command ( normally AT&K3 fo RTS/CTS, see your modem's documentation).
4. press "Receive" to wait for a fax. Incomming faxes will be stored in the current directory as TIFF files.
5. press "Stop" and "Quit" to finish receiving faxes.

How to send faxes in your programs

The steps you must follow to send a fax are:

1. Implement the faxProducer interface

this interface will provide RFax with the pages that must be send. The format of the interface is very simple:

       Bitmap getFaxPage(int page);

Your class must return a image object that contains the image to be faxed. The maximum size the image is 1728 x 2387. If you  use a size smaller than that you can use the scaleFactor feature of the t4Encoder in order to scale your image. The scaled image shall not be larger than the maximum size.

For example, if you image is 800 x 1000 and you set scale to 2, the final image will be 1600 x 2000.

This is a simple implementation of a fax producer:

[c#]

// faxProducer Interface

public Bitmap getFaxPage(int page) {

 // we send only 1 page
if (page>0) return null;

// create an image and write something on it
Bitmap i=new Bitmap(800,1000);

Graphics g=Graphics.FromImage(pageImage);

// clear image
g.Clear(Color.White);

 

// define font and color
SolidBrush textBrush=new SolidBrush(Color.Black);
Font textFont= new Font(new FontFamily("Arial"),12);

PointF textPos=new PointF(50,50);

// paint text on page
g.DrawString("MY FIRST FAX", textFont,textBrush, textPos);
return i;

}

RFax also provides some ready to use faxProducers:

• FaxTextProducer: Uses a String as source for creating the pages to be faxed.

[c#]

// create text fax producer
producer p=new TextFaxProducer();
p.text="Hello, \n\n this is a fax sent with RFax\n\nregards\n\nJ4L";
p.prepare();

// now create the FaxModem object and call the open() method using the producer as parameter

The second step is to create a FaxModem object, set up port and modem configurations and call the sendFax() method.

For example:

 

[c#]

using J4L.RFax;

class MainClass
{

public static void Main(string[] args)
{
MainClass m=new MainClass();
m.sendFax();
}

public void sendFax() {

TextFaxProducer fp=new TextFaxProducer();

fp.textFont= new Font(new FontFamily("Arial"),28);
fp.text="This is my first fax";
fp.prepare();

FaxModem m=new FaxModem();
m.ATFlowControlRTSCTS="AT&K3";
m.flowControl=FaxModem.FLOWCONTROL_RTSCTS;
m.port="COM3";
m.faxClass=1;
m.bitRate=FaxModem.BITRATE_9600;
m.debug=true;

if (m.open(fp)) {
m.sendFax("12345");
}
m.close();

}

}

 

or if you implement your own FaxProducer:

 

[c#]

using J4L.RFax;

class MainClass: IFaxProducer
{

public static void Main(string[] args)
{
MainClass m=new MainClass();
m.sendFax();
}

 

public Bitmap getFaxPage(int page) {

// implement faxProducer Interface here

}

public void sendFax() {

FaxModem m=new FaxModem();
m.ATFlowControlRTSCTS="AT&K3";
m.flowControl=FaxModem.FLOWCONTROL_RTSCTS;
m.port="COM3";
m.faxClass=1;
m.bitRate=FaxModem.BITRATE_9600;
m.debug=true;

if (m.open(this)) {
m.sendFax("12345");
}
m.close();

}

}

 

FileImageFaxProducer (faxing PDF or HTML Files).

RFax includes a fax producer that can read image files (jpeg, png, gif....) and fax them. For example:

 

[c#]

string[] iFiles={"page1.gif","page2.gif"};
FileImageFaxProducer fp=new FileImageFaxProducer();
fp.files=iFiles;

FaxModem m=new FaxModem();
...
if (m.open(fp)) {
m.sendFax("**");
}

 

The FileImageFaxProducer is very simple, it just has a property called "files" which must contain the list of files to be faxes (each file/image in one page).

You can use this fax producer to fax PDF or HTML files, but first of all you must convert your PDF or HTML file an image/s. The product comes with 2 example classes that can do this. Both classes are located in the "source" subdirectory.

• PDF2Image.cs: Use this file to convert PDF files to JPEG images. The class uses a free program called ghostscript for such conversion. The program can be downloaded here:

  http://www.ghostscript.com

  The PDF2Image class can be used in the following manner:

[c#]

PDF2Image p=new PDF2Image();
p.outputDirectory="c:\\images\\"; // directory where jpeg files will be created
p.ghostscriptDir="c:\\Program Files\\gs\\gs8.00\\bin\\"; // bin directory of the ghostscript installation

string[] iFiles=p.toJPEG("c:\\input.pdf"); // convert now

// now you can use the FileImageFaxProducer with the list of generated files.
FileImageFaxProducer fp=new FileImageFaxProducer();
fp.files=iFiles;

• Html2Image.cs: this class uses the Internet Explorer for rendering the html code. Before you compile this class you must:
  1. Use the AxImp utility to create the .Net wrappers for the ShDocVw.dll. This will create 2 assemblies: shdocvw.dll and AxShDocVw.DLL which must be added as reference to your project. For example "AxImp c:\windows\system32\ShDocVw.dll"
  2. reference to Microsoft.mshtml - NET tab, Microsoft mshtml
     

Example of use:

[c#]

// parameters are, input html (as url or file), page length in pixels, output directory and prefix for output png files.
string[] iFiles= Html2Image.toPNG("http://www.java4less.com",800,"c:\\images\\","out");

// now you can use the FileImageFaxProducer with the list of generated files.
FileImageFaxProducer fp=new FileImageFaxProducer();
fp.files=iFiles;

 

How to receive faxes

 

You can use the FaxTest.cs file as a reference if you want to receive faxes in your application. Faxes are always stored as TIFF files.

The steps you must follow are:

1. create a FaxReceiverModem. it is a subclass of the FaxModem class, which is used for reception.
2. set port and flow control configuration.
3. Implement the IFaxReceiver interface so that your application can receive an event when a fax is received.

Example:

m=new FaxReceiverModem();

m.flowControl=FaxModem.FLOWCONTROL_RTSCTS;
m.ATFlowControlRTSCTS="AT&K3";
m.bitRate=FaxModem.BITRATE_9600;

m.port="COM1";

((FaxReceiverModem) m).faxReceiver=this; // your class must implement the IFaxReceiver interface
if (((FaxReceiverModem) m).openReception()) ((FaxReceiverModem) m).waitForFax();

 

The IFaxReceiver only implements one method:

void faxReceived(string callerId, bool success,string file,int pages);

the parameters are selfexplaining:

• callerId: fax number of the caller
• success: whether reception was successfull
• file: name of the TIFF file
• pages: number of pages

 

API

 

FaxModem Properties:

• string port: port name where the modem is located (default is COM1)
• int maxRetries: maximum number of page transmision retries
• int bitRate: bit rate, valid values are:
  • FaxModem.BITRATE_2400,
  • FaxModem.BITRATE_4800,
  • FaxModem.BITRATE_7200,
  • FaxModem.BITRATE_9600,
  • FaxModem.BITRATE_12000,
  • FaxModem.BITRATE_14400
• bool dialTone: dial using tones (if true) or pulses (if false).
• string faxFile: temporary fax file. The extension 1,2,3... will be added for the different pages. The default value is "tmpFax".
• int faxClass: requested modem class, 1 (recommended and default value), 2 or 2.0
• int flowControl: flow control (FLOWCONTROL_NONE , FLOWCONTROL_RTSCTS or FLOWCONTROL_XONXOFF ). Default is FLOWCONTROL_RTSCTS.
• string ATFlowControlXONXOFF: AT command for setting the modem in XON/XOFF mode (default is At&K4).
• string ATFlowControlRTSCTS: AT command for setting the modem in RTS/CTS mode (default is At&K3).
• int hangCode: hangup code sent by remote fax machine if the connection was cancelled.
• string[] initCommands: list of initialization AT commands defined by the user.
• string lastError: description of last error.
• IFaxStatusListener listener: status listener.
• bool log: log mode.
• string logStr: log output.
• int MPSEOPdelay: delay between RTC and MPS/EOP default is 8 (80 ms).
• string noEcho: No echo command (default is ATE0).
• string ownId: own telephone number.
• IFaxProducer producer: fax producer.
• string remoteId: telephone number of the remote fax machine
• string resetCommand: AT reset command (ATZ)
• int resetDelay: delay after ATZ (reset command) in msecs, default is 0
• int resolution: resolution normal or fine (default)
  • RESOLUTION_FINE 196 dpi vertical resolution. The page will have an aproximate size of 1728 * 2378.
  • RESOLUTION_NORMAL 98 dpi vertical resolution. The page will have an aproximate size of 1728 * 1189.
• int timeout: response timeout seconds (30)
• string resetDelay: delay after ATZ (reset command) in msecs, default is 0. Some modem require a delay after the ATZ command.

 

FaxModem Methods:

• close() closes connection to the modem.
• T4Encoder getEncoder() gets t4 encoder.
• string getInitString() gets modem initialization string. Default is ATV1Q0.
• bool open(FaxProducer p) opens connection to modem and create fax pages.
• bool sendFax(string destId) sends fax to the specified fax number. Will return false if it did not succeed.
• setInitString(string s) sets modem initialization string. Default is ATV1Q0.
• setPortName(string p) selects modem/port, for example COM1.

FaxReceiverModem Properties (extends FaxModem)

• inDirectory: directory where tiff files will be stored
• answerAfterRings: answer after this number of rings (default is 1)
• faxReceiver: class that implements the IFaxReceiver interface

 

FaxReceiverModem methods (extends FaxModem)

• public bool openReception(): open port and initialize modem.
• public bool receiveFax(): enter loop and wait for fax.
• public bool close(): exit loop, stop waiting for fax.

 

T4Encoder Properties

• bool centerImage: center image in the fax page.
• int scaleFactor: image scale factor (1 or 2). If 2 the image will be scaled to the double of its size. For example, if your faxProducer provides an image of size 850*1150 and you set scale to 2, the resulting page will be 1700*2300.
• color whiteColor: Fax pages are black and white pages. The T4Encoder will convert color bitmaps to black and white fax pages. You can define the white color with this property (default is Color.White), any other color will be treated as black.

 

IFaxStatusListener

• faxProgress(int status, int page) reports status. Your class must implement this method if you want to receive notifications of the faxing state. Status are:
  • FaxModem.ST_CLOSE RFax is closing connection and port
  • FaxModem.ST_CONNECTING RFax is connecting to remote fax
  • FaxModem.ST_CONVERT_FIlES RFax is creating fax files
  • FaxModem.ST_INIT_MODEM RFax is initilizing modem
  • FaxModem.ST_OPEN_PORT RFax is opening modem
  • FaxModem.ST_REC_CALL Incomming call detected
  • FaxModem.ST_REC_PAGE RFax is receiving page
  • FaxModem.ST_SEND_PAGE RFax is sending page
  • FaxModem.ST_WAIT_CALL waiting for call

IFaxReceiver

• void faxReceived(string callerId, bool success,string file,int pages): This method is executed when a faxed is received
  • callerId: fax number of the caller
  • success: whether reception was successfull
  • file: name of the TIFF file
  • pages: number of pages