(Page 1 of 1 in this chapter)

Chapter 1

Introduction

1.1 About NaturalFax

1.2 About the CT Access Environment

: 1.2.1 Programming Model
: 1.2.2 CT Access Components
: 1.2.3 Managing NaturalFax Parameters in CT Access

1.1 About NaturalFax

NaturalFax is a C function library component of CT Access that provides fax functionality. It runs on the following Alliance Generation (AG) boards without any additional hardware: · AG-8/80 · AG-8/80 DSP · AG-T1 · AG-E1 · AG-24+ · AG-30 · AG-48 · AG-60 · AG-T1 v2 · AG-E1 v2 · AG Quad E AG Quad T
Use NaturalFax to develop an application to transmit and receive Group 3 facsimiles at rates of 2400, 4800, 7200, or 9600 bps. NaturalFax can also transmit facsimiles at 12,000 and 14,400 bps. NaturalFax supports polling remote fax terminals; a calling fax can poll a remote fax terminal and request the remote terminal to transmit a fax.
NaturalFax supports enhanced Group 3 fax features, such as 1D, 2D, and MMR encodings, Error Correcting Mode (ECM), low, high, and superhigh resolutions, and the standard page width formats. NaturalFax can convert documents into different formats, resolutions, or encodings online (on-the-fly) or offline.
For more information about the Group 3 fax standard, see Appendix G of this manual.
Its software licensing scheme does not require hardware security devices.

1.2 About the 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.2.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 5 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 C for a complete list of NaturalFax events, and Appendix B for a complete list of NaturalFax errors.

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

1.2.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 24 channels of an AG-T1 board, an application needs to create 24 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.2.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 E for detailed descriptions of NaturalFax parameters and their default values.

(Page 1 of 1 in this chapter)

tech_support@nmss.com