1.1 Introduction

1.2 NaturalFax

1.3 CT Access Environment

1.3.1 Programming Model

1.3.2 CT Access Components

1.3.3 Managing NaturalFax Parameters in CT Access

1.1 Introduction

The NaturalFax Developer's Reference Manual provides detailed information about developing NaturalFax applications under CT Access and provides a complete reference for the NaturalFax API, demonstration programs, and utilities.

This manual is targeted to developers of fax applications who are using CT Access 4.0 or higher. This document defines telephony terms where applicable, but assumes that the reader is familiar with telephony concepts. It also assumes that the user is familiar with the C programming language.

1.2 NaturalFax

NaturalFax is a C function library component of CT Access that provides fax functionality. It runs on the following Alliance Generation (AG) and QX 2000 boards without any additional hardware:

• AG Quad E/Dual E

• AG Quad T/Dual T

• QX 2000 (Windows NT only)

• AG 2000 (NaturalFax is not supported on AG 2000/100 hardware.)

• AG 4000/400, AG 4000/800, AG 4000/1600, AG 4000/3200, AG 4000/4000

• AG 4000/C

• CompactPCI AG Quad T/Dual E
  Note: NaturalFax 3.4 or earlier does not support the CG 6000C board.

Use NaturalFax to develop an application to transmit and receive Group 3 facsimiles at rates of up to 14,400 bps.

NaturalFax software can be used to produce fax server products for enterprise fax applications, IP telephony gateways, and large scale Fax Service Provider systems. Applications include LAN fax, fax broadcast, fax-on-demand, and store-and-forward and realtime fax over IP data networks.

NaturalFax runs on Natural MicroSystems hardware that consists of various telecommunications interfaces, a high-speed controller (X86), and an array of DSPs. On the AG boards, the fax modems run on powerful TI C5x and C54x DSPs and share them with other telephony algorithms such as voice record and play. The T.30 fax communication protocol runs on the AG board controller and host processor. This efficient sharing of DSP and controller resources is in contrast to traditional "chip-per-port" designs and provides the highest density and lowest cost/port fax boards and systems.

In the QX family of boards, NaturalFax runs on the TI C549 DSP which serves both as a DSP resource and board controller. The simplified architecture of the four port QX design leads to high performance at a low cost.

NaturalFax supports enhanced Group 3 fax features, such as 1D, 2D, and MMR encoding, Error Correcting Mode (ECM), low, high, and superhigh resolutions, and the standard page width formats. NaturalFax also supports the T.37 format, which is specified as 1D encoding, LOW resolution, and A4 page width. NaturalFax can convert documents into different formats, resolutions, or encodings online (on-the-fly) or offline. NaturalFax supports polling remote fax terminals; a calling fax can poll a remote fax terminal and request the remote terminal to transmit a fax.

For more information about the Group 3 fax standard, see Appendix F.

1.3 CT Access Environment

This section provides background information about CT Access and summarizes the main elements of the CT Access environment. You must have CT Access installed on your system to build applications using NaturalFax.

For more detailed information about CT Access, see the CT Access Developer's Reference Manual.

1.3.1 Programming Model

CT Access employs an asynchronous programming model in order to take advantage of concurrent processing. When called, most functions return immediately, which indicates the operation was initiated. The application may then perform other functions while CT Access is processing the command.

There are two types of functions in CT Access, synchronous and asynchronous.

• Synchronous functions are complete when the return value is received. The return value may be either SUCCESS or an error code.

• Asynchronous functions are complete when the DONE event is delivered to the application. The return value indicates if the operation was successfully initiated, but does not report completion.
  If the return value is SUCCESS, the function has been successfully initiated. During the function execution, events are generated indicating the occurrence of certain conditions or state changes. The execution result will arrive asynchronously in an event. If an asynchronous function fails after being initiated, CT Access delivers a DONE event to the application and the event value field contains an error code. If an asynchronous function completes successfully, its value field contains CTA_REASON_FINISHED.
  If the return code is not SUCCESS, the function was never initiated; therefore, no subsequent events associated with the function will be generated.

The following table summarizes the differences between asynchronous and synchronous functions. Chapter 6 lists all NaturalFax functions and indicates if they are synchronous or asynchronous.

Behavior	Asynchronous	Synchronous
Operation complete when function returns	NO	YES
Returns a DONE event when function is complete	YES	NO
Operation can fail after function returns	YES	NO

See Appendix B for a complete list of NaturalFax events, and Appendix A for a complete list of NaturalFax errors.

1.3.2 CT Access Components

A CT Access service is a group of logically related telephony functions. The NaturalFax service provides functions to send and receive Group 3 faxes.

A CTA context organizes services and accompanying resources around a single processing context. A CTA context usually represents an application instance controlling a single telephone call. Some CTA contexts are not associated with a call; an operation performing fax file conversions does not require a telephone line.

Note: Only one asynchronous fax operation per CTA context can be active at one time.

A service can only be opened once on an individual CTA context. For example, in order to send faxes using all eight channels of an AG 2000 board, an application needs to create eight CTA contexts, and open the NaturalFax service on each CTA context.

An event queue is the communication path from a service to an application. A service generates events indicating certain conditions or state changes. An application retrieves the events from the event queue.

1.3.3 Managing NaturalFax Parameters in CT Access

The characteristics for CT Access services can be altered by modifying associated parameters. Each NaturalFax parameter structure has default values that are sufficient for most configurations. NaturalFax applications typically need to set the Subscriber ID (the telephone number) to comply with FCC or other local regulations, but may not need to modify other parameters.

CT Access manages parameters for services on a CTA context basis. The CTA context maintains a copy of the parameters for all services opened on the context. This allows each fax operation to have its own characteristics.

Use the following CT Access functions to retrieve or modify parameter values:

• ctaGetParmByName retrieves a single field for a given parameter name.

• ctaSetParmByName modifies a single field for a given parameter name.

• ctaGetParmInfo retrieves a parameter field definition.

• ctaGetParms returns parameter values for a given parameter structure.

• ctaRefreshParms resets the values of all context parameters on a CTA context to the global defaults.

See Appendix D for detailed descriptions of NaturalFax parameters and their default values.