t4.h File Reference

Go to the source code of this file.

Classes

struct  t4_stats_t

Typedefs

typedef int(* t4_row_read_handler_t )(void *user_data, uint8_t buf[], size_t len)
typedef int(* t4_row_write_handler_t )(void *user_data, const uint8_t buf[], size_t len)
typedef struct t4_state_s t4_state_t

Enumerations

enum  t4_image_compression_t { T4_COMPRESSION_ITU_T4_1D = 1, T4_COMPRESSION_ITU_T4_2D = 2, T4_COMPRESSION_ITU_T6 = 3 }
enum  t4_image_x_resolution_t {
  T4_X_RESOLUTION_R4 = 4016, T4_X_RESOLUTION_R8 = 8031, T4_X_RESOLUTION_300 = 11811, T4_X_RESOLUTION_R16 = 16063,
  T4_X_RESOLUTION_600 = 23622, T4_X_RESOLUTION_800 = 31496, T4_X_RESOLUTION_1200 = 47244
}
enum  t4_image_y_resolution_t {
  T4_Y_RESOLUTION_STANDARD = 3850, T4_Y_RESOLUTION_FINE = 7700, T4_Y_RESOLUTION_300 = 11811, T4_Y_RESOLUTION_SUPERFINE = 15400,
  T4_Y_RESOLUTION_600 = 23622, T4_Y_RESOLUTION_800 = 31496, T4_Y_RESOLUTION_1200 = 47244
}
enum  t4_image_width_t {
  T4_WIDTH_R4_A4 = 864, T4_WIDTH_R4_B4 = 1024, T4_WIDTH_R4_A3 = 1216, T4_WIDTH_R8_A4 = 1728,
  T4_WIDTH_R8_B4 = 2048, T4_WIDTH_R8_A3 = 2432, T4_WIDTH_300_A4 = 2592, T4_WIDTH_300_B4 = 3072,
  T4_WIDTH_300_A3 = 3648, T4_WIDTH_R16_A4 = 3456, T4_WIDTH_R16_B4 = 4096, T4_WIDTH_R16_A3 = 4864,
  T4_WIDTH_600_A4 = 5184, T4_WIDTH_600_B4 = 6144, T4_WIDTH_600_A3 = 7296, T4_WIDTH_1200_A4 = 10368,
  T4_WIDTH_1200_B4 = 12288, T4_WIDTH_1200_A3 = 14592
}
enum  t4_image_length_t {
  T4_LENGTH_STANDARD_A4 = 1143, T4_LENGTH_FINE_A4 = 2286, T4_LENGTH_300_A4 = 4665, T4_LENGTH_SUPERFINE_A4 = 4573,
  T4_LENGTH_600_A4 = 6998, T4_LENGTH_800_A4 = 9330, T4_LENGTH_1200_A4 = 13996, T4_LENGTH_STANDARD_B4 = 1401,
  T4_LENGTH_FINE_B4 = 2802, T4_LENGTH_300_B4 = 0, T4_LENGTH_SUPERFINE_B4 = 5605, T4_LENGTH_600_B4 = 0,
  T4_LENGTH_800_B4 = 0, T4_LENGTH_1200_B4 = 0, T4_LENGTH_STANDARD_US_LETTER = 1075, T4_LENGTH_FINE_US_LETTER = 2151,
  T4_LENGTH_300_US_LETTER = 0, T4_LENGTH_SUPERFINE_US_LETTER = 4302, T4_LENGTH_600_US_LETTER = 0, T4_LENGTH_800_US_LETTER = 0,
  T4_LENGTH_1200_US_LETTER = 0, T4_LENGTH_STANDARD_US_LEGAL = 1369, T4_LENGTH_FINE_US_LEGAL = 2738, T4_LENGTH_300_US_LEGAL = 0,
  T4_LENGTH_SUPERFINE_US_LEGAL = 5476, T4_LENGTH_600_US_LEGAL = 0, T4_LENGTH_800_US_LEGAL = 0, T4_LENGTH_1200_US_LEGAL = 0
}

Functions

t4_state_tt4_rx_init (t4_state_t *s, const char *file, int output_encoding)
 Prepare for reception of a document.
int t4_rx_start_page (t4_state_t *s)
 Prepare to receive the next page of the current document.
int t4_rx_put_bit (t4_state_t *s, int bit)
 Put a bit of the current document page.
int t4_rx_put_byte (t4_state_t *s, uint8_t byte)
 Put a byte of the current document page.
int t4_rx_put_chunk (t4_state_t *s, const uint8_t buf[], int len)
 Put a byte of the current document page.
int t4_rx_end_page (t4_state_t *s)
 Complete the reception of a page.
int t4_rx_release (t4_state_t *s)
 End reception of a document. Tidy up and close the file. This should be used to end T.4 reception started with t4_rx_init.
int t4_rx_free (t4_state_t *s)
 End reception of a document. Tidy up, close the file and free the context. This should be used to end T.4 reception started with t4_rx_init.
int t4_rx_set_row_write_handler (t4_state_t *s, t4_row_write_handler_t handler, void *user_data)
 Set the row write handler for a T.4 receive context.
void t4_rx_set_rx_encoding (t4_state_t *s, int encoding)
 Set the encoding for the received data.
void t4_rx_set_image_width (t4_state_t *s, int width)
 Set the expected width of the received image, in pixel columns.
void t4_rx_set_y_resolution (t4_state_t *s, int resolution)
 Set the row-to-row (y) resolution to expect for a received image.
void t4_rx_set_x_resolution (t4_state_t *s, int resolution)
 Set the column-to-column (x) resolution to expect for a received image.
void t4_rx_set_dcs (t4_state_t *s, const char *dcs)
 Set the DCS information of the fax, for inclusion in the file.
void t4_rx_set_sub_address (t4_state_t *s, const char *sub_address)
 Set the sub-address of the fax, for inclusion in the file.
void t4_rx_set_far_ident (t4_state_t *s, const char *ident)
 Set the identity of the remote machine, for inclusion in the file.
void t4_rx_set_vendor (t4_state_t *s, const char *vendor)
 Set the vendor of the remote machine, for inclusion in the file.
void t4_rx_set_model (t4_state_t *s, const char *model)
 Set the model of the remote machine, for inclusion in the file.
t4_state_tt4_tx_init (t4_state_t *s, const char *file, int start_page, int stop_page)
 Prepare for transmission of a document.
int t4_tx_start_page (t4_state_t *s)
 Prepare to send the next page of the current document.
int t4_tx_restart_page (t4_state_t *s)
 Prepare the current page for a resend.
int t4_tx_next_page_has_different_format (t4_state_t *s)
 Check for the existance of the next page, and whether its format is like the current one. This information can be needed before it is determined that the current page is finished with.
int t4_tx_end_page (t4_state_t *s)
 Complete the sending of a page.
int t4_tx_get_bit (t4_state_t *s)
 Get the next bit of the current document page. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added where appropriate.
int t4_tx_get_byte (t4_state_t *s)
 Get the next byte of the current document page. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added where appropriate.
int t4_tx_get_chunk (t4_state_t *s, uint8_t buf[], int max_len)
 Get the next chunk of the current document page. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added where appropriate.
int t4_tx_check_bit (t4_state_t *s)
 Return the next bit of the current document page, without actually moving forward in the buffer. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added.
int t4_tx_release (t4_state_t *s)
 End the transmission of a document. Tidy up and close the file. This should be used to end T.4 transmission started with t4_tx_init.
int t4_tx_free (t4_state_t *s)
 End the transmission of a document. Tidy up, close the file and free the context. This should be used to end T.4 transmission started with t4_tx_init.
void t4_tx_set_tx_encoding (t4_state_t *s, int encoding)
 Set the encoding for the encoded data.
void t4_tx_set_min_row_bits (t4_state_t *s, int bits)
 Set the minimum number of encoded bits per row. This allows the makes the encoding process to be set to comply with the minimum row time specified by a remote receiving machine.
void t4_tx_set_local_ident (t4_state_t *s, const char *ident)
 Set the identity of the local machine, for inclusion in page headers.
void t4_tx_set_header_info (t4_state_t *s, const char *info)
 Set the header info.
int t4_tx_set_row_read_handler (t4_state_t *s, t4_row_read_handler_t handler, void *user_data)
 Set the row read handler for a T.4 transmit context.
int t4_tx_get_y_resolution (t4_state_t *s)
 Get the row-to-row (y) resolution of the current page.
int t4_tx_get_x_resolution (t4_state_t *s)
 Get the column-to-column (x) resolution of the current page.
int t4_tx_get_image_width (t4_state_t *s)
 Get the width of the current page, in pixel columns.
int t4_tx_get_pages_in_file (t4_state_t *s)
 Get the number of pages in the file.
int t4_tx_get_current_page_in_file (t4_state_t *s)
 Get the currnet page number in the file.
void t4_get_transfer_statistics (t4_state_t *s, t4_stats_t *t)
 Get the current transfer statistics.
const char * t4_encoding_to_str (int encoding)
 Get the short text name of an encoding format.


Detailed Description


Typedef Documentation

typedef struct t4_state_s t4_state_t

T.4 FAX compression/decompression descriptor. This defines the working state for a single instance of a T.4 FAX compression or decompression channel.


Enumeration Type Documentation

Supported compression modes.

Length of the various supported paper sizes, in pixels at the various Y resolutions. Paper sizes are A4 (215mm x 297mm) B4 (255mm x 364mm) A3 (303mm x 418.56mm) North American Letter (215.9mm x 279.4mm) North American Legal (215.9mm x 355.6mm) Unlimited

T.4 does not accurately define the maximum number of scan lines in a page. A wide variety of maximum row counts are used in the real world. It is important not to set our sending limit too high, or a receiving machine might split pages. It is important not to set it too low, or we might clip pages.

Values seen for standard resolution A4 pages include 1037, 1045, 1109, 1126 and 1143. 1109 seems the most-popular. At fine res 2150, 2196, 2200, 2237, 2252-2262, 2264, 2286, and 2394 are used. 2255 seems the most popular. We try to use balanced choices here.

Exact widths in PELs for the difference resolutions, and page widths. Note: The A4 widths also apply to North American letter and legal. The R4 resolution widths are not supported in recent versions of T.30 Only images of exactly these widths are acceptable for FAX transmisson.

R4 864 pels/215mm for ISO A4, North American Letter and Legal R4 1024 pels/255mm for ISO B4 R4 1216 pels/303mm for ISO A3 R8 1728 pels/215mm for ISO A4, North American Letter and Legal R8 2048 pels/255mm for ISO B4 R8 2432 pels/303mm for ISO A3 R16 3456 pels/215mm for ISO A4, North American Letter and Legal R16 4096 pels/255mm for ISO B4 R16 4864 pels/303mm for ISO A3

Supported X resolutions, in pixels per metre.

Supported Y resolutions, in pixels per metre.


Function Documentation

const char* t4_encoding_to_str ( int  encoding  ) 

Get the short text name of an encoding format.

Get the short text name of an encoding format.

Parameters:
encoding The encoding type.
Returns:
A pointer to the string.

void t4_get_transfer_statistics ( t4_state_t s,
t4_stats_t t 
)

Get the current transfer statistics.

Get the current image transfer statistics.

Parameters:
s The T.4 context.
t A pointer to a statistics structure.

Referenced by t30_get_transfer_statistics().

int t4_rx_end_page ( t4_state_t s  ) 

Complete the reception of a page.

Parameters:
s The T.4 receive context.
Returns:
0 for success, otherwise -1.

References EOLS_TO_END_ANY_RX_PAGE, span_log(), and t4_rx_put_bit().

int t4_rx_free ( t4_state_t s  ) 

End reception of a document. Tidy up, close the file and free the context. This should be used to end T.4 reception started with t4_rx_init.

Parameters:
s The T.4 receive context.
Returns:
0 for success, otherwise -1.

References t4_rx_release().

t4_state_t* t4_rx_init ( t4_state_t s,
const char *  file,
int  output_encoding 
)

Prepare for reception of a document.

Parameters:
s The T.4 context.
file The name of the file to be received.
output_encoding The output encoding.
Returns:
A pointer to the context, or NULL if there was a problem.

References span_log().

int t4_rx_put_bit ( t4_state_t s,
int  bit 
)

Put a bit of the current document page.

Parameters:
s The T.4 context.
bit The data bit.
Returns:
TRUE when the bit ends the document page, otherwise FALSE.

Referenced by t4_rx_end_page().

int t4_rx_put_byte ( t4_state_t s,
uint8_t  byte 
)

Put a byte of the current document page.

Parameters:
s The T.4 context.
byte The data byte.
Returns:
TRUE when the byte ends the document page, otherwise FALSE.

Referenced by t30_non_ecm_put_byte().

int t4_rx_put_chunk ( t4_state_t s,
const uint8_t  buf[],
int  len 
)

Put a byte of the current document page.

Parameters:
s The T.4 context.
buf The buffer containing the chunk.
len The length of the chunk.
Returns:
TRUE when the byte ends the document page, otherwise FALSE.

Referenced by t30_non_ecm_put_chunk().

int t4_rx_release ( t4_state_t s  ) 

End reception of a document. Tidy up and close the file. This should be used to end T.4 reception started with t4_rx_init.

Parameters:
s The T.4 receive context.
Returns:
0 for success, otherwise -1.

Referenced by t30_release(), and t4_rx_free().

void t4_rx_set_dcs ( t4_state_t s,
const char *  dcs 
)

Set the DCS information of the fax, for inclusion in the file.

Parameters:
s The T.4 context.
dcs The DCS information, formatted as an ASCII string.

void t4_rx_set_far_ident ( t4_state_t s,
const char *  ident 
)

Set the identity of the remote machine, for inclusion in the file.

Parameters:
s The T.4 context.
ident The identity string.

void t4_rx_set_image_width ( t4_state_t s,
int  width 
)

Set the expected width of the received image, in pixel columns.

Parameters:
s The T.4 context.
width The number of pixels across the image.

void t4_rx_set_model ( t4_state_t s,
const char *  model 
)

Set the model of the remote machine, for inclusion in the file.

Parameters:
s The T.4 context.
model The model string, or NULL.

int t4_rx_set_row_write_handler ( t4_state_t s,
t4_row_write_handler_t  handler,
void *  user_data 
)

Set the row write handler for a T.4 receive context.

Parameters:
s The T.4 receive context.
handler A pointer to the handler routine.
user_data An opaque pointer passed to the handler routine.
Returns:
0 for success, otherwise -1.

void t4_rx_set_rx_encoding ( t4_state_t s,
int  encoding 
)

Set the encoding for the received data.

Parameters:
s The T.4 context.
encoding The encoding.

void t4_rx_set_sub_address ( t4_state_t s,
const char *  sub_address 
)

Set the sub-address of the fax, for inclusion in the file.

Parameters:
s The T.4 context.
sub_address The sub-address string.

void t4_rx_set_vendor ( t4_state_t s,
const char *  vendor 
)

Set the vendor of the remote machine, for inclusion in the file.

Parameters:
s The T.4 context.
vendor The vendor string, or NULL.

void t4_rx_set_x_resolution ( t4_state_t s,
int  resolution 
)

Set the column-to-column (x) resolution to expect for a received image.

Parameters:
s The T.4 context.
resolution The resolution, in pixels per metre.

void t4_rx_set_y_resolution ( t4_state_t s,
int  resolution 
)

Set the row-to-row (y) resolution to expect for a received image.

Parameters:
s The T.4 context.
resolution The resolution, in pixels per metre.

int t4_rx_start_page ( t4_state_t s  ) 

Prepare to receive the next page of the current document.

Parameters:
s The T.4 context.
Returns:
zero for success, -1 for failure.

References span_log().

int t4_tx_check_bit ( t4_state_t s  ) 

Return the next bit of the current document page, without actually moving forward in the buffer. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added.

Parameters:
s The T.4 context.
Returns:
The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is set (i.e. the returned value is 2 or 3).

References SIG_STATUS_END_OF_DATA.

int t4_tx_end_page ( t4_state_t s  ) 

Complete the sending of a page.

Parameters:
s The T.4 context.
Returns:
zero for success, -1 for failure.

int t4_tx_free ( t4_state_t s  ) 

End the transmission of a document. Tidy up, close the file and free the context. This should be used to end T.4 transmission started with t4_tx_init.

Parameters:
s The T.4 context.
Returns:
0 for success, otherwise -1.

References t4_tx_release().

int t4_tx_get_bit ( t4_state_t s  ) 

Get the next bit of the current document page. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added where appropriate.

Parameters:
s The T.4 context.
Returns:
The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is set (i.e. the returned value is 2 or 3).

References SIG_STATUS_END_OF_DATA.

int t4_tx_get_byte ( t4_state_t s  ) 

Get the next byte of the current document page. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added where appropriate.

Parameters:
s The T.4 context.
Returns:
The next byte. For the last byte of data, bit 8 is set. In this case, one or more bits of the byte may be padded with zeros, to complete the byte.

Referenced by t30_non_ecm_get_byte().

int t4_tx_get_chunk ( t4_state_t s,
uint8_t  buf[],
int  max_len 
)

Get the next chunk of the current document page. The document will be padded for the current minimum scan line time. If the file does not contain an RTC (return to control) code at the end of the page, one will be added where appropriate.

Parameters:
s The T.4 context.
buf The buffer into which the chunk is to written.
max_len The maximum length of the chunk.
Returns:
The actual length of the chunk. If this is less than max_len it indicates that the end of the document has been reached.

Referenced by t30_non_ecm_get_chunk().

int t4_tx_get_current_page_in_file ( t4_state_t s  ) 

Get the currnet page number in the file.

Parameters:
s The T.4 context.
Returns:
The page number, or -1 if there is an error.

int t4_tx_get_image_width ( t4_state_t s  ) 

Get the width of the current page, in pixel columns.

Parameters:
s The T.4 context.
Returns:
The number of columns.

int t4_tx_get_pages_in_file ( t4_state_t s  ) 

Get the number of pages in the file.

Parameters:
s The T.4 context.
Returns:
The number of pages, or -1 if there is an error.

int t4_tx_get_x_resolution ( t4_state_t s  ) 

Get the column-to-column (x) resolution of the current page.

Parameters:
s The T.4 context.
Returns:
The resolution, in pixels per metre.

int t4_tx_get_y_resolution ( t4_state_t s  ) 

Get the row-to-row (y) resolution of the current page.

Parameters:
s The T.4 context.
Returns:
The resolution, in pixels per metre.

t4_state_t* t4_tx_init ( t4_state_t s,
const char *  file,
int  start_page,
int  stop_page 
)

Prepare for transmission of a document.

Parameters:
s The T.4 context.
file The name of the file to be sent.
start_page The first page to send. -1 for no restriction.
stop_page The last page to send. -1 for no restriction.
Returns:
A pointer to the context, or NULL if there was a problem.

References span_log().

int t4_tx_next_page_has_different_format ( t4_state_t s  ) 

Check for the existance of the next page, and whether its format is like the current one. This information can be needed before it is determined that the current page is finished with.

Parameters:
s The T.4 context.
Returns:
0 for next page found with the same format as the current page. 1 for next page found with different format from the current page. -1 for no page found, or file failure.

References span_log().

int t4_tx_release ( t4_state_t s  ) 

End the transmission of a document. Tidy up and close the file. This should be used to end T.4 transmission started with t4_tx_init.

Parameters:
s The T.4 context.
Returns:
0 for success, otherwise -1.

Referenced by t30_release(), and t4_tx_free().

int t4_tx_restart_page ( t4_state_t s  ) 

Prepare the current page for a resend.

Parameters:
s The T.4 context.
Returns:
zero for success, -1 for failure.

void t4_tx_set_header_info ( t4_state_t s,
const char *  info 
)

Set the header info.

Set the info field, included in the header line included in each page of an encoded FAX. This is a string of up to 50 characters. Other information (date, local ident, etc.) are automatically included in the header. If the header info is set to NULL or a zero length string, no header lines will be added to the encoded FAX.

Parameters:
s The T.4 context.
info A string, of up to 50 bytes, which will form the info field.

Referenced by t30_set_tx_page_header_info().

void t4_tx_set_local_ident ( t4_state_t s,
const char *  ident 
)

Set the identity of the local machine, for inclusion in page headers.

Parameters:
s The T.4 context.
ident The identity string.

Referenced by t30_set_tx_ident().

void t4_tx_set_min_row_bits ( t4_state_t s,
int  bits 
)

Set the minimum number of encoded bits per row. This allows the makes the encoding process to be set to comply with the minimum row time specified by a remote receiving machine.

Parameters:
s The T.4 context.
bits The minimum number of bits per row.

int t4_tx_set_row_read_handler ( t4_state_t s,
t4_row_read_handler_t  handler,
void *  user_data 
)

Set the row read handler for a T.4 transmit context.

Parameters:
s The T.4 transmit context.
handler A pointer to the handler routine.
user_data An opaque pointer passed to the handler routine.
Returns:
0 for success, otherwise -1.

void t4_tx_set_tx_encoding ( t4_state_t s,
int  encoding 
)

Set the encoding for the encoded data.

Parameters:
s The T.4 context.
encoding The encoding.

int t4_tx_start_page ( t4_state_t s  ) 

Prepare to send the next page of the current document.

Parameters:
s The T.4 context.
Returns:
zero for success, -1 for failure.

References EOLS_TO_END_T4_TX_PAGE, EOLS_TO_END_T6_TX_PAGE, and span_log().


Generated on Tue Aug 4 03:36:24 2009 for spandsp by  doxygen 1.5.9