5.3. Setting the Bit Mask for a Receive Fax Function

• 5.3.1. File Format for Incoming Fax Data
• 5.3.2. Mode of Operation
• 5.3.3. Enable Phase B Event Generation
• 5.3.4. Enable Phase D Event Generation
• 5.3.5. Enable Operator Intervention (Voice Request)
• 5.3.6. Selectable Receive Width
• 5.3.7. Selectable Receive Length
• 5.3.8. Resolution for Storing Incoming Fax Data

The rcvflag parameter of the fx_rcvfax( ) and fx_rcvfax2( ) functions is a logical OR bit mask that can be set to indicate one or more conditions. For more information, see the following:

• 5.3.1. File Format for Incoming Fax Data

Once received, fax data can be stored in one of the following formats:

• raw, unstructured file -- rcvflag bit mask set to DF_RAW
• TIFF/F structured, formatted file -- rcvflag bit mask set to DF_TIFF

For information on delimiters for multi-page fax documents, see Section 5.2.2. Storing Incoming Fax Data on page 75.

5.3.2. Mode of Operation

Two modes of operation are available for the receive fax functions:

• synchronous mode -- rcvflag bit mask set to EV_SYNC
• asynchronous mode -- rcvflag bit mask set to EV_ASYNC

In synchronous mode (EV_SYNC), the function does not return control to the application until fx_rcvfax( ) completes or an error has occurred.

In asynchronous mode (EV_ASYNC), the function returns control to the application immediately after it is invoked. The fx_rcvfax( ) function returns a zero to indicate successful invocation and a -1 to indicate an invocation error. If successfully invoked, the function returns control to the application and the specified device continues to receive fax data. Once control is returned to the application, the application may issue voice/fax calls on other devices. The completion (or error termination) of fx_rcvfax( ) is indicated through events generated by the Standard Runtime Library.

The following events are valid for fx_rcvfax( ):

Event	Description
TFX_FAXERROR	Error in processing
TFX_FAXRECV	Successful completion of fx_rcvfax( )

See the Voice Software Reference - Standard Runtime Library for event handling information.

5.3.3. Enable Phase B Event Generation

To enable Phase B event generation, specify DF_PHASEB in rcvflag of the receive fax function.

When this bit is set, a TFX_PHASEB event is returned each time Phase B is completed during the receive fax operation.

When a TFX_PHASEB event occurs, the application can call these fax extended attributes for the following information:

Fax Extended Attribute	Indicates
ATFX_BSTAT( )	Phase B information available
ATFX_CODING( )	Negotiated line encoding scheme for the data transfer
ATFX_SPEED( )	Baud rate of the data transfer
ATFX_STATE( )	State of the fax channel device

If you issue fx_rcvfax( ) or fx_rcvfax2( ) in synchronous mode (EV_SYNC), you must install an event handler to handle Phase B events using sr_enbhdlr( ) of the Standard Runtime Library. See the Voice Software Reference - Standard Runtime Library for event handler details.

5.3.4. Enable Phase D Event Generation

To enable Phase D event generation, specify DF_PHASED in rcvflag of the receive function.

When this bit is set, a TFX_PHASED event is returned each time Phase D is completed during the receive fax operation, except for the last page. After the last page, fx_rcvfax( ) completes (synchronous mode) or a TFX_FAXRECV event occurs (asynchronous mode).

Phase D events allow the application to monitor the progress of the fax session on a page-by-page basis.

When a TFX_PHASED or TFX_FAXRECV event occurs, the application can call these fax extended attributes for the following information:

Fax Extended Attribute	Returns
ATFX_BADSCANLINES( )	Number of bad scan lines transferred (per page)
ATFX_PHDCMD( )	Phase D command
ATFX_PHDRPY( )	Phase D reply
ATFX_RESLN( )	Resolution of the page
ATFX_SCANLINES( )	Total number of scan lines transferred
ATFX_SPEED( )	Baud rate of the data transfer
ATFX_STATE( )	State of the fax channel device
ATFX_TRCOUNT( )	Number of bytes transferred
ATFX_WIDTH( )	Width of the page

When you enable Phase D events, the generation of the Phase D event is skipped for the last fax page received of the fx_rcvfax( ) call since a TFX_FAXRECV event is generated indicating the successful completion of the fx_rcvfax( ) function.

NOTE:

If you issue the fx_rcvfax( ) function in synchronous mode (EV_SYNC), an event handler must be installed to handle Phase D events using the sr_enbhdlr( ) function of the Standard Runtime Library (see the Voice Software Reference - Standard Runtime Library for event handler details).

If the RTN message is returned to the TRANSMITTER, the generation of the Phase D event would occur on that page each time Phase D event generation is enabled. In this case, Phase D event would not be skipped for the last page of the fx_sendfax( ) call if the RTN message is returned from the RECEIVER on the last page.

If the RTN message is returned to the TRANSMITTER, either TFX_FAXSEND or TFX_FAXERROR would be generated. If none of pages are sent successfully, TFX_FAXERROR event is generated indicating fax failure. If one of pages is sent successfully, TFX_FAXSEND event is generated indicating the successful completion of the fx_sendfax( ) function.

5.3.5. Enable Operator Intervention (Voice Request)

DF_ACCEPT_VRQ in the rcvflag argument enables the application to accept an operator intervention request from the remote station.

DF_ISSUE_VRQ in the rcvflag argument enables the application to send an operator intervention request (PIN/PIP) to the remote station after the last fax page of the receive fax operation is received.

To indicate successful completion, fx_rcvfax( ) returns a 0 in synchronous mode or a TFX_FAXRECV event occurs in asynchronous mode. The fax session is completed, but the connection between the two stations is still active for voice communication.

To determine the reason for termination of fx_rcvfax( ), call the ATFX_TERMMSK( ). This function returns a TM_FXTERM bit value to indicate normal completion or TM_VOICEREQ to indicate termination due to a voice request issued or received.

5.3.6. Selectable Receive Width

Set the rcvflag bit mask to restrict the maximum width (in number of pixels) at which the application receives fax data. Possible values are:

DF_1728MAX

DF_2048MAX

DF_2432MAX (default)

The DF_2432MAX value (default) allows reception of fax data at a width of 1728, 2048 or 2432 pixels. The transmitter is notified of the maximum width of the transmitted page during negotiation of Phase B. It is up to the transmitting fax machine to scale large pages to the maximum receive width specified.

T.30 protocol specifies that a receiver in a fax session be able to receive fax data at the following width combinations:

1728 pixels only

1728 and 2048 pixels

1728, 2048 and 2432 pixels (default)

5.3.7. Selectable Receive Length

Set the rcvflag bit mask to indicate the preferred page length for receiving fax data.

DF_A4MAXLEN (approximately 11 inches)

DF_B4MAXLEN (approximately 14 inches)

DF_NOMAXLEN (unlimited) (default)

You can override the default setting via parameter initialization during installation.

The transmitter is notified of the receiver's preferred page length during negotiation of Phase B. The receiving fax channel does not actually paginate the incoming image to the specified page length; the transmitter must send the image so that the maximum specified length is not exceeded.

5.3.8. Resolution for Storing Incoming Fax Data

Two grades of vertical resolution can be specified using the rcvflag argument:

• high or fine resolution -- DF_RXRESHI
• low or coarse resolution -- DF_RXRESLO

When the rcvflag argument specifies a resolution (high or low), all fax data associated with fx_rcvfax( ) or fx_rcvfax2( ) is stored at this resolution regardless of the resolution specified by the transmitter. These bit flags can be used to reduce storage requirements or to support third-party utility programs that can only handle certain resolutions.

Click here to contact Dialogic Customer Engineering