spandsp: t4_tx.h File Reference

spandsp 0.0.6

t4_tx.h File Reference

Go to the source code of this file.

## Typedefs
typedef int(* | t4_row_read_handler_t) (void *user_data, uint8_t buf[], size_t len)
typedef struct t4_state_s | t4_tx_state_t

## Functions
int | t4_tx_start_page (t4_tx_state_t *s)
| Prepare to send the next page of the current document.
int | t4_tx_restart_page (t4_tx_state_t *s)
| Prepare the current page for a resend.
int | t4_tx_next_page_has_different_format (t4_tx_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_tx_state_t *s)
| Complete the sending of a page.
int | t4_tx_check_bit (t4_tx_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.
int | t4_tx_get_bit (t4_tx_state_t *s)
| Get the next bit of the current document page. The document will be padded for the current minimum scan line time.
int | t4_tx_get_byte (t4_tx_state_t *s)
| Get the next byte of the current document page. The document will be padded for the current minimum scan line time.
int | t4_tx_get_chunk (t4_tx_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.
void | t4_tx_set_tx_encoding (t4_tx_state_t *s, int encoding)
| Set the encoding for the encoded data.
void | t4_tx_set_min_bits_per_row (t4_tx_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_tx_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_tx_state_t *s, const char *info)
| Set the header info.
void | t4_tx_set_header_tz (t4_tx_state_t *s, tz_t *tz)
| Set the header timezone.
int | t4_tx_set_row_read_handler (t4_tx_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_tx_state_t *s)
| Get the row-to-row (y) resolution of the current page.
int | t4_tx_get_x_resolution (t4_tx_state_t *s)
| Get the column-to-column (x) resolution of the current page.
int | t4_tx_get_image_width (t4_tx_state_t *s)
| Get the width of the current page, in pixel columns.
int | t4_tx_get_pages_in_file (t4_tx_state_t *s)
| Get the number of pages in the file.
int | t4_tx_get_current_page_in_file (t4_tx_state_t *s)
| Get the currnet page number in the file.
void | t4_tx_get_transfer_statistics (t4_tx_state_t *s, t4_stats_t *t)
| Get the current transfer statistics.
t4_tx_state_t * | t4_tx_init (t4_tx_state_t *s, const char *file, int start_page, int stop_page)
| Prepare for transmission of a document.
int | t4_tx_release (t4_tx_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_tx_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.

## Typedef Documentation

## ◆ t4_row_read_handler_t

typedef int(* t4_row_read_handler_t) (void *user_data, uint8_t buf[], size_t len)

This function is a callback from the image decoders, to read the unencoded bi-level image, row by row. It is called for each row, with len set to the number of bytes per row expected.

Returns
  len for OK, or zero to indicate the end of the image data.

## Function Documentation

## ◆ t4_tx_check_bit()

int t4_tx_check_bit | ( | t4_tx_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.

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 t4_t6_encode_state_s::bit_pos, t4_t6_encode_state_s::bit_ptr, t4_state_s::image_buffer, t4_state_s::image_size, and SIG_STATUS_END_OF_DATA.

## ◆ t4_tx_end_page()

int t4_tx_end_page | ( | t4_tx_state_t * | s | ) |

Complete the sending of a page.

Parameters

  s | The T.4 context.

Returns
  zero for success, -1 for failure.

References t4_state_s::current_page.

## ◆ t4_tx_free()

int t4_tx_free | ( | t4_tx_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().

## ◆ t4_tx_get_bit()

int t4_tx_get_bit | ( | t4_tx_state_t * | s | ) |

Get the next bit of the current document page. The document will be padded for the current minimum scan line time.

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 t4_t6_encode_state_s::bit_pos, t4_t6_encode_state_s::bit_ptr, t4_state_s::image_buffer, t4_state_s::image_size, and SIG_STATUS_END_OF_DATA.

## ◆ t4_tx_get_byte()

int t4_tx_get_byte | ( | t4_tx_state_t * | s | ) |

Get the next byte of the current document page. The document will be padded for the current minimum scan line time.

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.

References t4_t6_encode_state_s::bit_ptr, t4_state_s::image_buffer, and t4_state_s::image_size.

Referenced by t30_non_ecm_get_byte().

## ◆ t4_tx_get_chunk()

int t4_tx_get_chunk | ( | t4_tx_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.

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.

References t4_t6_encode_state_s::bit_ptr, t4_state_s::image_buffer, and t4_state_s::image_size.

Referenced by t30_non_ecm_get_chunk().

## ◆ t4_tx_get_current_page_in_file()

int t4_tx_get_current_page_in_file | ( | t4_tx_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.

References t4_state_s::current_page.

## ◆ t4_tx_get_image_width()

int t4_tx_get_image_width | ( | t4_tx_state_t * | s | ) |

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

Parameters

  s | The T.4 context.

Returns
  The number of columns.

References t4_state_s::image_width.

## ◆ t4_tx_get_pages_in_file()

int t4_tx_get_pages_in_file | ( | t4_tx_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.

References t4_tiff_state_t::pages_in_file, t4_t6_encode_state_s::row_read_handler, and t4_state_s::tiff.

## ◆ t4_tx_get_transfer_statistics()

void t4_tx_get_transfer_statistics | ( | t4_tx_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.

References t4_stats_t::bad_rows, t4_t6_decode_state_s::bad_rows, t4_state_s::current_page, t4_stats_t::encoding, t4_state_s::image_length, t4_state_s::image_width, t4_stats_t::length, t4_state_s::line_encoding, t4_state_s::line_image_size, t4_stats_t::line_image_size, t4_stats_t::longest_bad_row_run, t4_t6_decode_state_s::longest_bad_row_run, t4_stats_t::pages_in_file, t4_tiff_state_t::pages_in_file, t4_stats_t::pages_transferred, t4_tiff_state_t::start_page, t4_state_s::tiff, t4_stats_t::width, t4_state_s::x_resolution, t4_stats_t::x_resolution, t4_state_s::y_resolution, and t4_stats_t::y_resolution.

Referenced by t30_get_transfer_statistics().

## ◆ t4_tx_get_x_resolution()

int t4_tx_get_x_resolution | ( | t4_tx_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.

References t4_state_s::x_resolution.

## ◆ t4_tx_get_y_resolution()

int t4_tx_get_y_resolution | ( | t4_tx_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.

References t4_state_s::y_resolution.

## ◆ t4_tx_init()

t4_tx_state_t * t4_tx_init | ( | t4_tx_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 t4_state_s::bytes_per_row, t4_state_s::cur_runs, t4_state_s::current_page, t4_tiff_state_t::file, t4_state_s::image_buffer_size, t4_state_s::image_width, t4_state_s::logging, t4_t6_encode_state_s::max_rows_to_next_1d_row, t4_tiff_state_t::pages_in_file, t4_state_s::ref_runs, t4_t6_encode_state_s::ref_steps, t4_state_s::row_buf, t4_t6_encode_state_s::rows_to_next_1d_row, t4_state_s::rx, span_log(), t4_tiff_state_t::start_page, t4_tiff_state_t::stop_page, t4_state_s::tiff, and t4_tiff_state_t::tiff_file.

## ◆ t4_tx_next_page_has_different_format()

int t4_tx_next_page_has_different_format | ( | t4_tx_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 t4_state_s::current_page, t4_state_s::logging, t4_t6_encode_state_s::row_read_handler, span_log(), t4_tiff_state_t::stop_page, t4_state_s::tiff, and t4_tiff_state_t::tiff_file.

## ◆ t4_tx_release()

int t4_tx_release | ( | t4_tx_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.

References t4_state_s::rx, t4_state_s::tiff, and t4_tiff_state_t::tiff_file.

Referenced by t4_tx_free().

## ◆ t4_tx_restart_page()

int t4_tx_restart_page | ( | t4_tx_state_t * | s | ) |

Prepare the current page for a resend.

Parameters

  s | The T.4 context.

Returns
  zero for success, -1 for failure.

References t4_t6_encode_state_s::bit_pos, and t4_t6_encode_state_s::bit_ptr.

## ◆ t4_tx_set_header_info()

void t4_tx_set_header_info | ( | t4_tx_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.

References t4_state_s::header_info.

Referenced by t30_set_tx_page_header_info().

## ◆ t4_tx_set_header_tz()

void t4_tx_set_header_tz | ( | t4_tx_state_t * | s,
|  | tz_t * | tz )

Set the header timezone.

Set the time zone for the time stamp in page header lines. If this function is not used the current time zone of the program's environment is used.

Parameters

  s | The T.4 context.
  tz | A time zone descriptor.

References t4_state_s::tz.

Referenced by t30_set_tx_page_header_tz().

## ◆ t4_tx_set_local_ident()

void t4_tx_set_local_ident | ( | t4_tx_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.

References t4_rx_metadata_t::local_ident, and t4_state_s::tiff.

Referenced by t30_set_tx_ident().

## ◆ t4_tx_set_min_bits_per_row()

void t4_tx_set_min_bits_per_row | ( | t4_tx_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.

References t4_t6_encode_state_s::min_bits_per_row.

## ◆ t4_tx_set_row_read_handler()

int t4_tx_set_row_read_handler | ( | t4_tx_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.

References t4_t6_encode_state_s::row_read_handler, and t4_t6_encode_state_s::row_read_user_data.

## ◆ t4_tx_set_tx_encoding()

void t4_tx_set_tx_encoding | ( | t4_tx_state_t * | s,
|  | int | encoding )

Set the encoding for the encoded data.

Parameters

  s | The T.4 context.
  encoding | The encoding.

References t4_state_s::line_encoding, t4_t6_encode_state_s::max_rows_to_next_1d_row, t4_state_s::row_is_2d, and t4_t6_encode_state_s::rows_to_next_1d_row.

## ◆ t4_tx_start_page()

int t4_tx_start_page | ( | t4_tx_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 t4_t6_encode_state_s::bit_pos, t4_t6_encode_state_s::bit_ptr, t4_state_s::bytes_per_row, t4_state_s::cur_runs, t4_state_s::current_page, EOLS_TO_END_T4_TX_PAGE, EOLS_TO_END_T6_TX_PAGE, t4_tiff_state_t::file, t4_state_s::header_info, t4_state_s::image_length, t4_state_s::image_size, t4_state_s::image_width, t4_state_s::line_encoding, t4_state_s::line_image_size, t4_state_s::logging, t4_state_s::max_row_bits, t4_t6_encode_state_s::max_rows_to_next_1d_row, t4_state_s::min_row_bits, t4_state_s::ref_runs, t4_t6_encode_state_s::ref_steps, t4_state_s::row_bits, t4_state_s::row_buf, t4_state_s::row_is_2d, t4_t6_encode_state_s::row_read_handler, t4_t6_encode_state_s::row_read_user_data, t4_t6_encode_state_s::rows_to_next_1d_row, span_log(), t4_tiff_state_t::stop_page, T4_COMPRESSION_ITU_T6, t4_state_s::tiff, t4_tiff_state_t::tiff_file, t4_state_s::tx_bits, and t4_state_s::tx_bitstream.