8.2. Function Categories

• 8.2.1. Send Fax
• 8.2.2. Receive Fax
• 8.2.3. Set Initial Fax State
• 8.2.4. Initialize DF_IOTT
• 8.2.5. Configuration
• 8.2.6. Extended Attribute
• 8.2.7. Resource Management
• Hints
• 8.2.8. SCbus Routing
• 8.2.9. Miscellaneous
• 8.2.10. Convenience Functions

The fax main library (libfaxmt.lib) provides functions used to create fax applications. These functions interface with the Dialogic voice driver.

Dialogic also supplies fax convenience functions, which are built on fax main library functions. Convenience functions enable you to easily implement basic functionality of the fax main library functions. The source code for these functions is provided in faxconv.c and in the function reference.

See Chapter 9. Fax Library Function Reference for details on all functions.

The fax library functions can be grouped as shown in Table 21. Categories of Fax Functions:

Table 21. Categories of Fax Functions

Category	Description
Send fax	Send single or multi-page fax data as defined by the DF_IOTT structure.
Receive fax	Receive fax data and write to a file; or send a request to receive fax data (polling).
Set initial fax state	Set the initial fax state of the application to caller (transmit) or called (receive).
Initialize DF_IOTT structure	Set default values for a DF_IOTT structure.
Configuration	Set and retrieve fax parameters such as fax header attributes.
Extended attribute	Return information specific to a fax device.
Resource management	Open, close and stop a fax channel device.
SCbus routing	Connect and disconnect fax channel to an SCbus time slot.
Convenience	A set of functions built on fax main library functions; these functions simplify application development.
Miscellaneous	Fax functions that don't fall into any other category.

8.2.1. Send Fax

The Send Fax function transmits fax data as defined by the DF_IOTT structure.

NOTE:

Convenience functions can also be used to send fax data; see Section 8.2.10. Convenience Functions on page 127.

Function	Description
fx_sendfax( )	Sends fax data as defined by the DF_IOTT structure:   single or multi-page TIFF/F fax file   single page raw image file   ASCII data
	Indicates to the caller application that the called application only has transmit capability.

8.2.2. Receive Fax

The Receive Fax functions receive fax data and write it to a specified file, or send a request to the caller application to receive fax data (poll request).

Functions	Description
fx_rcvfax( )	Receives fax data and writes it to a file:   single or multi-page TIFF/F fax file   single page raw image file
	Requests the caller application to receive a fax document (poll request).
fx_rcvfax2( )	Same description as fx_rcvfax( ), except that this function takes a file descriptor argument instead of a file name. Use this function to enable user-defined I/O functions.

8.2.3. Set Initial Fax State

The caller and called fax applications issue the Set Initial Fax State fax function to establish the initial fax state as caller (transmit state) or called (receive state) before issuing the initial send or receive fax function of the fax call.

NOTE:

Once the fax application sets the initial fax state, the correct fax state is maintained by the fax library throughout the fax session even when polling occurs.

Function	Description
fx_initstat( )	Sets the initial fax state for a specified fax channel device:   caller = transmit state   called = receive state

8.2.4. Initialize DF_IOTT

This function initializes a DF_IOTT structure which specifies the fax data to send.

Function	Description
fx_setiott( )	Initializes a DF_IOTT structure and sets default values.

8.2.5. Configuration

Configuration functions set and read various fax parameters.

Functions	Description
fx_getparm( )	Reads fax parameter.
fx_setparm( )	Sets fax parameter such as fax page header attributes.

8.2.6. Extended Attribute

Fax extended attribute functions have the prefix ATFX_. These functions take one parameter, the device handle for the fax channel, and return status information about the fax session.

Fax extended attributes are included in the fax library file (libfaxmt.lib).

Fax extended attribute function names are case-sensitive and must be written in uppercase letters.

Fax Extended Attribute	Function Description
ATFX_BADIOTT( )	Returns a pointer to an invalid DF_IOTT structure.
ATFX_BADPAGE( )	Returns a bad TIFF/F page number within the DF_IOTT structure.
ATFX_BADSCANLINES( )	Returns the number of bad scan lines in the last page transmitted or received.
ATFX_BSTAT( )	Returns the Phase B status bitmap after a TFX_PHASEB event. Returns bits indicating that the following messages are available: Non-Standard Facilities (NSF) information, Digital Information Signal (DIS) message and Digital Command Signal (DCS) message.
ATFX_ECM( )	Returns information on use of Error Correction Mode (ECM) for fax data transfer.
ATFX_ESTAT( )	Returns Phase E information describing errors during the fax session.
ATFX_CHTYPE( )	Returns the fax channel hardware type.
ATFX_CODING( )	Returns negotiated line encoding scheme.
ATFX_FXVERSION( )	Returns fax library version number string.
ATFX_LASTIOTT( )	Returns a pointer to the last DF_IOTT structure that was processed.
ATFX_PGXFER( )	Returns the number of pages transferred.
ATFX_PHDCMD( )	Returns the Phase D command after a TFX_PHASED event.
ATFX_PHDRPY( )	Returns the Phase D reply after a TFX_PHASED event.
ATFX_RESLN( )	Returns a decimal value indicating the vertical resolution of the transferred page after Phase D is completed.
ATFX_RTNPAGES( )	Returns the number of received pages that returned RTN to the transmitter during reception.
ATFX_SCANLINES( )	Returns the total number of scan lines in the last page transmitted or received.
ATFX_SPEED( )	Returns the final transfer speed (in baud) after Phase B completed; returns the equate DF_14400BAUD to indicate 14.4 Kbps transfer speed.
ATFX_STATE( )	Returns the current fax device channel state.
ATFX_TERMMSK( )	Returns a bitmap of termination reasons.
ATFX_TFBADTAG( )	Returns a bad TIFF/F tag number if EFX_BADTAG error is returned to ATDV_LASTERR( ).
ATFX_TFNOTAG( )	Returns the tag number of missing TIFF/F mandatory tag if EFX_BADTIF error is returned to ATDV_LASTERR( ).
ATFX_TFPGBASE( )	Returns a value indicating the base page numbering scheme for the last transmitted TIFF/F file.
ATFX_TRCOUNT( )	Returns the total number of bytes transferred during the current fax session.
ATFX_WIDTH( )	Returns a decimal value (in pixels per line) of negotiated width after Phase D completed. Returns the width of the fax page as it was transferred.

8.2.7. Resource Management

Resource Management functions start and stop fax resources, and stop a fax transfer.

Functions	Description
fx_open( )	Opens a fax channel or board device.
fx_close( )	Closes a fax channel device.
fx_stopch( )	Stops a fax channel device I/O.

Before a fax transfer can occur, the fax channel device must be opened. The fx_open( ) function specifies a unique Dialogic device handle. This handle is the only way a device can be identified once it is open. The fx_close( ) function closes a device via its handle.

The fx_open( ) and fx_close( ) functions do not cause a device to be busy. The functions work on a device whether the device is busy or idle.

See Section 4.3. Opening and Closing a Fax Channel (page 43) for more information on opening and using devices.

Hints

• Issuing an fx_open( ) or fx_close( ) while the fax device is in use by another process does not affect the current operation of the fax device.

The device handle which is returned is Dialogic defined. The device handle is not a standard Windows file descriptor. Any attempts to use operating system commands such as read( ), write( ), or ioctl( ) will produce unexpected results.

• In an application that creates a child process from a parent process, a device handle is not inheritable by the child process. Devices must be opened in the child process.

The fx_stopch( ) function stops a fax send or receive in progress on a channel device.

8.2.8. SCbus Routing

Used in SCbus configurations only: Use the fax-specific SCbus routing functions in combination with SCbus routing functions of other resources to set up SCbus routing to send or receive a fax.

Functions	Description
fx_listen( )	Connects fax listen channel to SCbus time slot.
fx_unlisten( )	Disconnects fax listen channel from SCbus.
fx_getxmitslot( )	Returns fax device channel's SCbus transmit time slot.

The fax SCbus routing functions are included as part of the fax library and are described in the SCbus Routing Software Reference.

8.2.9. Miscellaneous

The following functions don't fall into any other fax category. They are used to get T.30 messaging data, load fonts for ASCII data, set up user-defined I/O functions and for other miscellaneous purposes.

Functions	Description
fx_getDCS( )	Gets T.30 Digital Command Signal data.
fx_getDIS( )	Gets T.30 Digital Information Signal data.
fx_getNSF( )	Gets T.30 Non-Standard Facilities data.
fx_GetDllVersion( )	Returns the fax DLL version number.
fx_libinit( )	Initializes the fax library DLL.
fx_loadfont( )	Loads ASCII font to the VFX/40ESCplus board.
fx_setuio( )	Installs user-defined I/O functions.

The fx_getDCS( ) function allows an application to retrieve the most recent T.30 Digital Command Signal message, if available, for a specified channel. The DCS message contains information about the Phase B negotiated settings between the transmitter and receiver.

The fx_getDIS( ) function allows an application to retrieve the most recent T.30 Digital Information Signal message, if available, for a specified channel. The DIS message contains information about the receiver's capabilities. The DIS message is sent by the receiver to the transmitter as part of the Phase B negotiation.

The fx_getNSF( ) function allows an application to retrieve the T.30 Non-Standard Facilities message, if available, for a specified channel. The NSF message is a variable length message that can contain manufacturer-specific information. Manufacturers can use this message to support proprietary features for their products. The NSF message is sent as part of the Phase B negotiation.

The fx_GetDllVersion( ) function returns the fax DLL version number, while the fx_libinit( ) function initializes the fax library DLL.

The fx_loadfont( ) function allows an application to change the fonts used by the VFX/40ESCplus for ASCII to fax conversion and for the fax page header.

The fx_setuio( ) function allows an application to install user-defined read( ), write( ) and lseek( ) I/O functions. The DF_UIO data structure provides pointers to user-defined I/O functions.

8.2.10. Convenience Functions

Fax convenience functions are built on fax main library functions. They allow you to easily implement some of the basic functionality of the fax main library functions.

Functions	Description
fx_sendascii( )	Sends a single ASCII file.
fx_sendraw( )	Sends a single page of raw, unformatted, compressed fax data.
fx_sendtiff( )	Sends a single TIFF/F file.

The fax convenience functions are based on the fx_sendfax( ) function and use the DF_IOTT data structure. The source code for these functions is provided in the function reference as well as in the file faxconv.c.

The faxconv.c file is installed by default in the samples\fax subdirectory.

You have the option of building your own convenience functions or using the functions provided in faxconv.c. If you use the convenience functions in faxconv.c, you must compile faxconv.c and link it with the object code when building your application.

These convenience functions are written to operate in synchronous mode (EV_SYNC). To use the asynchronous mode of operation, you can modify the source code for the call to fx_sendfax( ) in the faxconv.c file. See the fx_sendfax( ), fx_sendascii, fx_sendraw( ) and fx_sendtiff( ) function references and sample code in Chapter 9. Fax Library Function Reference.

Click here to contact Dialogic Customer Engineering