4.7. Setting the Bit Mask for a Send Fax Function

• 4.7.1. Mode of Operation
• 4.7.2. Enable Phase B Event Generation
• 4.7.3. Enable Phase D Event Generation
• 4.7.4. Enable Operator Intervention (Voice Request)
• 4.7.5. Select Resolution for Fax Transmission
• 4.7.6. Enable Subaddress Fax Routing
• Sending Fax to a Single Subaddress
• Sending Fax to Multiple Subaddresses

The sndflag parameter of the fx_sendfax( ) function is a logical OR bit mask that can be set to indicate one or more conditions. For more information, see the following:

• 4.7.1. Mode of Operation on page 63
• 4.7.2. Enable Phase B Event Generation on page 64
• 4.7.3. Enable Phase D Event Generation on page 65
• 4.7.4. Enable Operator Intervention (Voice Request) on page 65
• 4.7.5. Select Resolution for Fax Transmission on page 66
• 4.7.6. Enable Subaddress Fax Routing on page 67

4.7.1. Mode of Operation

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

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

In synchronous mode, the function does not return control to the application until fx_sendfax( ) completes (zero returned) or an error has occurred (-1 returned); see Section 8.3. Error Handling on page 128.

In asynchronous mode, the function returns control to the application immediately after invocation. fx_sendfax( ) returns a zero to indicate successful invocation and a -1 to indicate an invocation error. Once control is returned to the application, the application may continue to send fax data on the specified device or issue voice/fax calls on other devices. The completion (or error termination) of fx_sendfax( ) is indicated to the application via events generated by the Dialogic Standard Runtime Library.

The following events are valid for fx_sendfax( ):

Event	Indicates...
TFX_FAXERROR	Error in processing
TFX_FAXSEND	Successful completion of fx_sendfax( )

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

4.7.2. Enable Phase B Event Generation

To enable Phase B event generation, specify DF_PHASEB in sndflag of the fx_sendfax( ) function.

When this bit is set, a TFX_PHASEB event is generated each time Phase B of the T.30 protocol is completed while fx_sendfax( ) is transmitting fax data.

If you issue fx_sendfax( ) in synchronous mode (EV_SYNC), you must install an event handler to handle Phase B events using the sr_enbhdlr( ) function of the Standard Runtime Library. For event handler details, see the Voice Software Reference - Standard Runtime Library.

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

Fax Extended Attribute	Returns...
ATFX_BSTAT( )	Phase B status information
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

4.7.3. Enable Phase D Event Generation

To enable Phase D event generation, specify DF_PHASED in sndflag of the fx_sendfax( ) function.

When this bit is set, a TFX_PHASED event is generated each time Phase D of the T.30 protocol is completed during the send fax operation. A Phase D event is generated for every page except for the last page. After the last page, if your application is running in synchronous mode fx_sendfax( ) completes or in asynchronous mode a TFX_FAXSEND event occurs.

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

If you issue fx_sendfax( ) in synchronous mode (EV_SYNC), you must install an event handler 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.

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

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

4.7.4. Enable Operator Intervention (Voice Request)

You can enable your application to send or receive an operator intervention (voice request) from a remote station.

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

DF_ISSUE_VRQ in the sndflag argument enables the application to send an operator intervention request (DFS_PRI_EOP) to the remote station after the last fax page of the fx_sendfax( ) fax session is transmitted.

If fx_sendfax( ) completes successfully, the function returns a 0 in synchronous mode or a TFX_FAXSEND 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_sendfax( ), call ATFX_TERMMSK( ). This function returns a TM_FXTERM bitmap value indicating normal completion of the function or TM_VOICEREQ indicating completion due to a voice request issued or received.

4.7.5. Select Resolution for Fax Transmission

When the sndflag argument specifies a resolution (DF_TXRESLO or DF_TXRESHI), all fax data associated with the fx_sendfax( ) call is transmitted at this resolution regardless of any resolutions previously specified.

The DF_IOTT entries for the fax may contain an arbitrary combination of raw, TIFF/F and ASCII files at different resolutions, specified in the io_resln field for raw and ASCII files. By setting the DF_TXRESHI or DF_TXRESLO bit in sndflag, the entire chain of DF_IOTT entries is sent at the specified resolution.

For example, if the DF_IOTT array specifies a TIFF/F file at high resolution followed by a raw file at low resolution, after the transmission of the TIFF/F file, Phase B would be entered to negotiate the change in resolution for the raw file. By setting sndflag to DF_TXRESLO, the entire fax session takes place at low resolution. In this case, the high resolution data in the TIFF/F file is internally converted to low resolution at the time of transmission.

By default, the resolution in the TIFF/F file or in the DF_IOTT entry is used in the fax transmission. The sndflag argument overrides this resolution.

4.7.6. Enable Subaddress Fax Routing

As described in Section 3.10. Subaddress Fax Routing on page 40, a subaddress is a T.30 message protocol that allows a fax to be routed to one or more telephone numbers (or extensions) after it is received by the fax machine or server.

The T.30 subaddress message is a 20-character string containing a combination of one or more phone numbers and/or extensions sent during Phase B negotiation.

To enable subaddress fax routing during fax transmission:

• Set the FC_ENDDOC parameter in fx_setparm( ) to DFS_REMOTESUBADDR.
• Set the FC_SENDCONT parameter in fx_setparm( ) to DFC_AUTO.
• Set the DF_TXSUBADDR bit in the sndflag parameter of fx_sendfax( ).

When subaddress fax routing is enabled, the fax library issues an MPS (DFC_MPS) message between each page of a multiple page TIFF/F file. The width and resolution of the fax transmission is set by the first TIFF/F page and remains the same for the entire fax transmission regardless of changes in width or resolution.

To return Phase B status after a TFX_PHASEB event, use the ATFX_BSTAT( ) extended attribute function. To return the setting of the fax channel for subaddress fax routing, use the FC_REMOTESUBADDR parameter in fx_getparm( ).

Sending Fax to a Single Subaddress

To send subaddress fax routing information with a fax transmission to a single subaddress, use the following procedure:

1. Initialize a table of DF_IOTT entries for fax data to be sent to the subaddress.

For the last entry in a table of DF_IOTT entries, set io_phdcont to DFC_EOP (End of Procedure) and io_type to IO_EOT.

2. Set the following fax parameters using fx_setparm( ):
   • Set the FC_TXSUBADDR parameter to the desired subaddress: phone number and/or extension.
   • If a multi-page fax is to be sent to the subaddress, set the FC_SENDCONT parameter value to DFC_AUTO.

DFC_AUTO automatically sets the FC_SENDCONT parameter value to DFC_MPS, allowing all pages of the multi-page fax to be transmitted to the specified subaddress in the least amount of time.

3. Set the initial state of the fax channel to transmitter using fx_initstat( ).
1. Dial the number of the receiving fax machine/server. See the Voice Software Reference-Programmer's Guide for functions to use for dialing.
2. Call fx_sendfax( ) with the DF_TXSUBADDR bit set in the sndflag parameter.

Sending Fax to Multiple Subaddresses

To send subaddress fax routing information with a fax transmission to multiple subaddresses, use the following procedure:

1. Initialize a table of DF_IOTT entries for fax data to be sent to the subaddress.

 
The specified fax data is sent to the first subaddress. For the last entry in a table of DF_IOTT entries, set io_phdcont to DFC_EOM (End of Message) and io_type to IO_EOT (last DF_IOTT entry). The DFC_EOM causes renegotiation of Phase B and indicates to the receiver that more fax data will be transferred.

2. Set the following fax parameters using fx_setparm( ):
   • Set the FC_TXSUBADDR parameter to the desired subaddress: phone number(s) and/or extension(s).
   • If a multi-page fax is to be sent to the subaddress, set the FC_SENDCONT parameter value to DFC_AUTO.
     
     DFC_AUTO automatically sets the FC_SENDCONT parameter value to DFC_MPS, allowing all pages of the multi-page fax to be transmitted to the specified subaddress in the least amount of time.
3. Set the initial state of the fax channel to transmitter using fx_initstat( ).
1. Dial the number of the receiving fax machine/server. See the Voice Software Reference - Programmer's Guide for information on dialing.
2. Call fx_sendfax( ) with the DF_TXSUBADDR bit set in the sndflag parameter. After fx_sendfax( ) completes, the fax session is still active.
3. Call fx_setparm( ) to update the FC_TXSUBADDR parameter with the new subaddress.
4. Initialize a DF_IOTT table for fax data for the new subaddress.

To route more than two DF_IOTT tables of fax data to different subaddresses, set io_phdcont for each entry in the table to DFC_EOM (End of Message) as in Step 1 above except for the final entry in the last DF_IOTT table. Set io_phdcont for the final entry to DFC_EOP and io_type to IO_EOT to end the fax session.

1. Call fx_sendfax( ) with the DF_TXSUBADDR bit set in the sndflag parameter.
2. Repeat steps 2 through 8 until all fax data has been sent to all specified subaddresses during the same fax session.

Click here to contact Dialogic Customer Engineering