4.5. Specifying Fax Data for Transmission in a DF_IOTT Table Entry

• 4.5.1. Declaring a Table of DF_IOTT Entries
• 4.5.2. Connecting DF_IOTT Table Entries
• 4.5.3. Sending Data from Device or Memory
• 4.5.4. Specifying File Storage Format
• 4.5.5. Sending Raw Files
• 4.5.6. Sending TIFF/F Files
• Handling Multi-Page TIFF/F Files
• Troubleshooting
• 4.5.7. Sending ASCII Files
• 4.5.8. Specifying Encoding Scheme for Data Transmission
• 4.5.9. Setting Phase D Continuation Values
• Hints
• Automatic Phase D Messaging - DFC_AUTO
• Merge Page - DFC_MPG
• End of Procedure - DFC_EOP
• End of Message - DFC_EOM
• Multi-Page Signal - DFC_MPS
• 4.5.10. Merging Images from Different Sources or Sub-Page Addressing

The DF_IOTT structure contains fields describing the fax data for one fax document to be transmitted. Each structure describes one source for fax data: raw, TIFF/F or ASCII. A linked list or array of DF_IOTT structures (table) can be created to specify multiple fax documents for transmission using the fax send function, fx_sendfax( ). A pointer argument in the fax send function points to the DF_IOTT table.

The DF_IOTT table may contain entries specifying fax data of different widths, resolutions and encoding schemes. Before the fax data is transmitted, the validity of each DF_IOTT table entry is verified.

For complete reference information on all fields in the DF_IOTT structure, see Section 7.6. DF_IOTT -- Fax Transmit Data Description on page 109.

The following topics on DF_IOTT are discussed:

• 4.5.1. Declaring a Table of DF_IOTT Entries on page 45
• 4.5.2. Connecting DF_IOTT Table Entries on page 46
• 4.5.3. Sending Data from Device or Memory on page 46
• 4.5.4. Specifying File Storage Format on page 47
• 4.5.5. Sending Raw Files on page 47
• 4.5.6. Sending TIFF/F Files on page 49
• 4.5.7. Sending ASCII Files on page 50
• 4.5.8. Specifying Encoding Scheme for Data Transmission on page 52
• 4.5.9. Setting Phase D Continuation Values on page 53
• 4.5.10. Merging Images from Different Sources or Sub-Page Addressing on page 57

4.5.1. Declaring a Table of DF_IOTT Entries

The following usage notes and cautions apply when you declare a table of DF_IOTT entries:

• Declare the DF_IOTT entries which are passed as an argument to fx_sendfax( ) as global or static in your application.
• Do not modify the DF_IOTT entries until after fx_sendfax( ) has completed. The DF_IOTT entries must exist for the duration of the fax transmission.
• In asynchronous mode, the fax library must repeatedly access the DF_IOTT entries during the fax transmission even after fx_sendfax( ) has returned control to the application. Each channel controlled by the single process must have its own separate DF_IOTT table.

The io_type field of the last DF_IOTT table entry must contain an IO_EOT to identify it as the last table entry.

The fx_setiott( ) function can be used to initialize DF_IOTT structure values. For more information, see Chapter 9. Fax Library Function Reference.

4.5.2. Connecting DF_IOTT Table Entries

When sending more than one fax document in a single fx_send( ) operation, you must build a linked list or array of DF_IOTT structures (table).

This DF_IOTT table may represent a combination of data in MH or MMR encoding schemes, or in ASCII format. The valid encoding scheme or format of the stored files specified for transmission depends on the capability of the fax product.

Specify the link between DF_IOTT table entries using the io_type logical OR field as follows:

• If the next entry is linked to the current one, specify IO_LINK and use io_nextp to point to the next DF_IOTT entry.
• If the entry is the last DF_IOTT entry in the chain, specify IO_EOT.
• If the next entry is contiguous, specify IO_CONT and set io_nextp and io_prevp fields to NULL. This is the default setting.

If neither IO_EOT nor IO_LINK is specified, the next entry is contiguous (next element in the array).

The fax library automatically builds the backward links for the DF_IOTT chain when fx_sendfax( ) is issued. The io_prevp field of the first DF_IOTT entry is set to NULL.

4.5.3. Sending Data from Device or Memory

Use the io_type field of the DF_IOTT structure to specify whether you are sending data from a device or from memory.

• For data stored on a disk device, specify IO_DEV.
• For data stored in memory, specify IO_MEM.

IO_MEM is only valid when io_datatype is set for raw data (DF_RAW) or ASCII (DF_ASCII).

4.5.4. Specifying File Storage Format

Use the io_datatype field of the DF_IOTT structure to specify the file storage format for transmission as follows:

• For a raw, compressed unstructured file, specify DF_RAW.
• For a TIFF/F file, specify DF_TIFF.
• For an ASCII text file (converted to a fax image at the time of transmission), specify DF_ASCII.

4.5.5. Sending Raw Files

Fax data stored as a raw file contains no information on the format of the fax data. When the raw data is sent, the width, resolution and encoding scheme for the stored raw fax data must be specified in the DF_IOTT structure.

If the width and resolution of the data in the raw file do not match the capabilities of the receiving station, automatic image scaling is provided.

Raw files negotiated for transfer in MH or MR line encoding scheme are sent with a fill order of Least Significant Bit (LSB) first; End of Line (EOL) sequences are not byte aligned.

Table 11. DF_IOTT Fields for Raw Files lists DF_IOTT fields used to send raw files:

Table 11. DF_IOTT Fields for Raw Files

Field	Value or Description
io_datatype	DF_RAW
io_width	Width of the stored raw fax data.
io_resln	Vertical resolution for the stored raw fax data.
io_coding	Encoding scheme for raw files: DF_MH for Modified Huffman and DF_MMR for Modified Modified Read. See Section 4.5.8. Specifying Encoding Scheme on page 52 for more information.
io_offset	The starting byte location in the file/memory for the data transfer. Setting io_offset to zero starts the transfer from the beginning of the file/memory.
io_length	The number of bytes to transfer. This field is used with the io_type value.
io_type	The entry type: If io_type is set to IO_DEV and io_length is set to -1, data is transferred until the end of the file is reached. If io_type is set to IO_MEM, io_length indicates the exact number of bytes to transfer from the buffer. If io_type is set to IO_MEM, io_bufferp points to the buffer in memory containing the raw image data.

4.5.6. Sending TIFF/F Files

The DF_IOTT structure may be set to send all or part of a single or multi-page TIFF/F file.

The fax library defaults to sending a single TIFF/F page beginning at page zero. To transmit TIFF/F files with a base 1 page numbering scheme, use the FC_TFPGBASE channel parameter in fx_setparm( ).

To send a subset of a TIFF/F file, use the io_pgcount and io_firstpg fields; see Table 12. DF_IOTT Fields for TIFF/F Files.

The io_pgcount value specifies the number of pages to send, and the io_firstpg value specifies the first page number to send. If the value of io_firstpg is zero (default), the number of pages specified by io_pgcount is sent. For example, to send document pages 0, 1 and 2 of a TIFF/F file, set io_firstpg to 0, and io_pgcount to 3.

If the width and resolution of the data in the TIFF/F file do not match the capabilities of the receiving station, automatic image scaling is provided.

Table 12. DF_IOTT Fields for TIFF/F Files lists DF_IOTT fields used to send TIFF/F files.

Table 12. DF_IOTT Fields for TIFF/F Files

Field	Value or Description
io_datatype	DF_TIFF
io_firstpg	The first page number to send. The first page in the file is referenced as page zero.
io_pgcount	The number of pages to send. If io_pgcount is -1 (default), all remaining pages in the file are sent.
io_coding	This field is ignored. The fax library reads the TIFF/F tags embedded in the file to determine the encoding scheme of the stored data.

Handling Multi-Page TIFF/F Files

In a multi-page TIFF/F file transmission, all pages preceding the final page are set to DFC_EOM (FC_SENDCONT parameter in fx_setparm( )). The last selected page of the specified TIFF/F file uses the Phase D continuation value set in io_phdcont (DF_IOTT structure).

To change the default intermediate page continuation value, set the FC_SENDCONT parameter to a different value or to DFC_AUTO. For more information, see Section 4.5.9. Setting Phase D Continuation Values (page 53) and fx_setparm( ) (page 281).

Troubleshooting

To ensure that TIFF/F files are sent successfully, the TIFF/F file must contain:

• all mandatory TIFF/F tags (or subset)
• valid TIFF/F tag values
• correct TIFF/F file header values
• valid PageNumber tag values

For a table of TIFF/F tags and values, see Appendix A. For information on error codes returned, see Appendix D.

4.5.7. Sending ASCII Files

ASCII files are converted to a fax image at the time of fax transmission and sent at the width, resolution and other values as specified in DF_IOTT.

The fax image is encoded over the phone line in MH or in the encoding scheme specified by the FC_TXCODING parameter of fx_setparm( ).

Converted ASCII files negotiated for transfer in the MH or MR line encoding scheme are sent with a fill order of Least Significant Bit (LSB) first; End of Line (EOL) sequences are byte aligned.

Table 13. DF_IOTT Fields for ASCII Files lists DF_IOTT fields used to send ASCII files.

Table 13. DF_IOTT Fields for ASCII Files

Field	Value or Description
io_datatype	DF_ASCII
io_width	Width of the fax image.
io_resln	Vertical resolution of the fax image.
io_offset	Byte offset in ASCII file/memory to start reading the ASCII data. Setting io_offset to zero starts reading the ASCII data from the beginning of the file/memory.
io_length	Number of bytes of ASCII data to read, convert and send. This field is used with the io_type field.
io_type	Entry type: If io_type is set to IO_DEV and io_length is set to -1, data is transferred until the end of the file is reached. If io_type is set to IO_MEM, io_length indicates the exact number of bytes of ASCII data to read from the buffer. This allows the application to select a portion of an ASCII file for transmission. If io_type is set to IO_MEM, io_bufferp points to the buffer in memory containing the ASCII data.
io_datap	A pointer to an optional DF_ASCIIDATA structure that contains parameters and values for the ASCII data. If this pointer is NULL, the DF_ASCIIDATA structure defaults are used. For information on this structure, see Chapter 7. Fax Data Structures.
io_coding	This field is ignored for ASCII file transfer.

4.5.8. Specifying Encoding Scheme for Data Transmission

The encoding scheme used in transmitting data over the phone line varies by product. For product support, see Section 2.4. Key Product Features on page 8. The negotiated encoding scheme is determined by the receiver's capability.

The io_coding field in the DF_IOTT structure specifies the transmission encoding scheme and is used only in sending raw files. The available values for io_coding are:

• DF_MH -- Modified Huffman
• DF_MMR -- Modified Modified Read

For TIFF/F and ASCII files, the io_coding field is ignored.

Some Dialogic fax products provide the option to specify the preferred line encoding scheme for fax transmission. This option uses the FC_TXCODING parameter in fx_setparm( ). For more information on FC_TXCODING, see Section 4.6.2. Specifying a Preferred Encoding Scheme for Transmission on page 60 and the fx_setparm( ) function reference on page 281.

The transmitting channel uses the FC_TXCODING value during Phase B negotiation with the remote receiver. The fax image data provided via the DF_IOTT structures is automatically converted to the negotiated line encoding scheme at the time of transmission. The final negotiated line encoding scheme for transmission depends on the receiver's capability.

To determine the negotiated line encoding scheme, call ATFX_CODING( ) after the negotiation of Phase B is completed.

4.5.9. Setting Phase D Continuation Values

Each DF_IOTT table entry specifies a continuation value for Phase D (post-message procedure) of the T.30 protocol in the io_phdcont field.

The io_phdcont field defines the way in which a following DF_IOTT entry is connected to the current DF_IOTT entry. Based on the io_phdcont field value, a message is sent from the transmitter to the receiver at the end of the current DF_IOTT entry's fax data. By selecting the appropriate value, you can transmit more data from the next DF_IOTT entry or terminate the fax session.

The io_phdcont field can have one of the values listed in Table 14. Phase D Continuation Values.

Table 14. Phase D Continuation Values

Value	Description
DFC_AUTO	Automatic Phase D Messaging. The fax driver automatically determines the T.30 protocol Phase D continuation value based on the width, resolution and position of the DF_IOTT entries. Possible values automatically assigned are DFC_EOM, DFC_EOP and DFC_MPS. This setting forces negotiation of Phase B when a page of a different width and/or resolution is found. If the following page has the same format as the current page, this setting bypasses Phase B negotiation for each page and saves transmit time.
DFC_MPG	Merge-Page. The data specified for the DF_IOTT entry directly following the current DF_IOTT entry is concatenated to the same page.
DFC_EOP	End of Procedure (T.30). Terminate current fax session; progress to Phase E; and disconnect fax call.
DFC_EOM	End of Message (T.30). End of current fax document page; more fax data to follow at different resolution or width; return to Phase B and negotiate parameters for next fax document page. This setting forces the negotiation of Phase B after each page.
DFC_MPS	Multi-Page Signal (T.30). End of current fax document page; next fax document page is in the same format as the current page; proceed directly to Phase C. This setting bypasses Phase B negotiation for each page and saves transmit time.

Hints

• DFC_AUTO and DFC_MPG are Dialogic fax library terms, not T.30 protocol terminology.
• DFC_EOP, DFC_EOM and DFC_MPS are provided for backward compatibility and for applications where specific T.30 Phase D continuation values are required.
• If a DF_IOTT entry specifies DFC_EOP as a Phase D continuation value, but it is not the last entry in the table, ATDV_LASTERR( ) returns an EFX_BADIOTT error.

More detail on each Phase D continuation value is provided next.

Automatic Phase D Messaging - DFC_AUTO

To enable automatic Phase D messaging, set the io_phdcont field in the DF_IOTT entry to DFC_AUTO.

By specifying DFC_AUTO for each DF_IOTT entry, Phase D messaging is simplified. The application does not have to determine the correct Phase D continuation value for each DF_IOTT entry; the Dialogic fax library does this automatically. The fax library uses DFC_EOM, DFC_MPS or DFC_EOP as the continuation value based on the width, resolution, and position of the DF_IOTT entry in the chain as well as the remote receiver's capability.

For example, if you specify DFC_AUTO for the last DF_IOTT entry in the chain, the fax library automatically issues an EOP after transmitting all files specified in the last DF_IOTT entry.

For fax data containing more than one image file per page (also known as sub-page addressing), you must use DFC_MPG. For more information, see Section 4.5.10. Merging Images from Different Sources or Sub-Page Addressing on page 57.

Merge Page - DFC_MPG

To concatenate data for the DF_IOTT entry directly following the current DF_IOTT entry to the same page, specify DFC_MPG as the Phase D continuation value. This concatenation is also known as sub-page addressing.

When you use DFC_MPG, the DFC_MPG entries in a chain are followed by a DF_IOTT entry that specifies DFC_AUTO or a Phase D continuation value (DFC_EOP, DFC_EOM or DFC_MPS) for the last entry of the multi-source fax page.

For more information on sub-page addressing, see Section 4.5.10. Merging Images from Different Sources or Sub-Page Addressing on page 57.

End of Procedure - DFC_EOP

To disconnect the fax call after Phase E is completed, specify DFC_EOP as the Phase D continuation value in the io_phdcont field for a DF_IOTT entry.

After Phase E, the line is still open and the application sets the channel on-hook, if necessary.

End of Message - DFC_EOM

To transmit more data in a different format, specify DFC_EOM as the Phase D continuation value in the io_phdcont field. This value allows you to:

• Change the type of data you are sending for the next DF_IOTT entry in a multiple page or multiple source fax transmission.
• Request turnaround polling fax transmission. After the current DF_IOTT entry's fax data is sent, you can send a message to the receiver requesting that the transmitter and receiver switch roles.

When initiating a turnaround polling fax transmission, set the io_phdcont field to DFC_EOM for the last DF_IOTT entry. This allows the fax session to return to Phase B after the initial fax data transmission is completed. The caller application (transmitter) can then continue with the turnaround polling fax transmission by issuing the fx_rcvfax( ) or fx_rcvfax2( ) function to indicate a poll request; see Section 3.4.3. Turnaround Polling Fax Transmission on page 34.

The current width and resolution values for the fax session remain in effect until a Phase D continuation value of DFC_EOM is reached in a DF_IOTT entry.

If the width and/or resolution of the data described in the next DF_IOTT entry is different from the current entry, specify DFC_EOM in the current entry to renegotiate Phase B.

Multi-Page Signal - DFC_MPS

To transmit more data in the same format as the current page, use DFC_MPS as the Phase D continuation value in the io_phdcont field.

All fields of the next DF_IOTT entry should be set to transmit data of the same format (image width, resolution, and so on) as the current DF_IOTT entry's data.

When transmitting a multi-page TIFF/F file from a single DF_IOTT structure, the value specified in the io_phdcont field of the DF_IOTT structure is the Phase D continuation value after all the pages specified in that DF_IOTT structure are sent. The Phase D continuation value used between each page of the multi-page TIFF/F file is specified by the FC_SENDCONT parameter (see fx_setparm( )).

4.5.10. Merging Images from Different Sources or Sub-Page Addressing

A single page of fax data can be formed from images stored in different sources. Each stored image is considered a sub-page.

To concatenate fax data described in the next DF_IOTT entry to the current DF_IOTT entry on the same page, specify DFC_MPG in the io_phdcont field.

For example, to create a page of fax data from three different files (TIFF/F, raw and ASCII), three DF_IOTT entries are required. For each of the first two DF_IOTT entries, set the io_phdcont field to DFC_MPG to concatenate the data to the following DF_IOTT entry's data. For the third DF_IOTT entry, specify DFC_AUTO or a Phase D continuation value (DFC_EOP, DFC_EOM or DFC_MPS) in the io_phdcont field for the last entry of the page.

NOTE:

DFC_MPG and DFC_AUTO are Dialogic fax library terms, not T.30 protocol terminology.

The following rules and restrictions apply to sub-page addressing and the use of the DFC_MPG value.

DFC_MPG Usage

• DFC_MPG cannot be specified for the last DF_IOTT entry in a chain or array. The last entry in the chain or array should specify DFC_AUTO or a T.30 protocol Phase D continuation value (DFC_EOP, DFC_EOM or DFC_MPS).
• A DF_IOTT entry for a TIFF/F file specifying DFC_MPG is limited to sending a single page of data for the entry: a one-page TIFF/F file or one page of a multi-page TIFF/F file.

 
When selecting a page from a multi-page TIFF/F file, set the io_firstpg field to the desired page number and the io_pgcount field to 1.

Resolution

The resolution for the fax data page is determined by the resolution specified for the first sub-page entry or by the resolution specified in the fx_sendfax( ) sndflag argument.

Width

• If the width of consecutive sub-pages is different, the sub-pages are scaled to match the negotiated width.

Encoding schemes

• Stored encoded data to be specified as a sub-page may be in one of the supported encoding schemes: MMR, MH. Support for this feature varies by product. For a listing of key features by product, see Section 2.4. Key Product Features on page 8.

ASCII sub-pages

• If you concatenate multiple ASCII sub-pages on the same page, the top margin, bottom margin, page length and page padding values specified in the first DF_ASCIIDATA structure apply to the entire page.
• The left and right margins, font and line spacing can be set differently for each DF_ASCIIDATA structure sub-page. The margins specified for ASCII sub-pages only apply to the ASCII data and do not affect the image sub-pages.
• Multiple ASCII/image sub-pages concatenated to a single fax page may result in an image that exceeds the length of a single page. This may occur due to the choice of graphical attributes for the ASCII data, the size of the ASCII sub-pages or a large image sub-page. Your application must specify the correct choice of graphical attributes for the ASCII data and know how much space will be taken by an image sub-page.
  • If an image is present at the bottom of the page that exceeds the page length, the page is extended.
  • If the page length specified in the first ASCII sub-page is exceeded while an ASCII sub-page is being processed, the remaining ASCII text is placed on the next fax page.
• Formfeed characters in ASCII sub-pages are ignored.

If the DFC_MPG continuation value is not used properly, ATDV_LASTERR( ) returns an EFX_BADIOTT error code.

Click here to contact Dialogic Customer Engineering