The fax to send class

class UASClassFaxToSend

This class provides functionality to configure a fax document for sending. To create this class the application will call the FaxToSend function, and this needs to be imported first:

from prosody.uas import Hangup, Error, FaxToSend

A call to the function will create and return an object of this type which is referred to as a “fax document object”.

This class exposes a value pages_to_send which is the total number of pages to send. This value is updated when a function such as set_content or append is called.

In addition, this class will record a number of causes, described below, that can be returned as the result of the functions it provides.

An object of this type is created independently of the call channel. A connected call is not required to create this object or to use the functions it provides.

Usage example:

from prosody.uas import Hangup, Error, FaxToSend

__uas_version__  = "0.0.1"
__uas_identify__ = "application"

def main(channel, application_instance_id, file_man, my_log, application_parameters, outbound_parameters):
    document = outbound_parameters
    my_fax = FaxToSend()
    cause = my_fax.set_content(document)

class FileCause

These are the causes that can be returned by the functions provided by a FaxToSend document object.

The causes are:

NORMAL

The task completed normally.

FILE_ACCESS_ERROR

A file access error occurred.

FILE_BAD_TIFF

The file supplied is not a suitable TIFF.

FILE_NO_PAGES

The file supplied has contains no pages, or a specified page within the file was not found.

FILE_BAD_WIDTH

A page being added for sending has an invalid width or a different width from existing pages. Supported widths are: A4 (1728 pixels, 21.95cm), B4 (2048 pixels, 26.01cm) and A3 (2432 pixels, 30.89cm).

INVALID_PAGE_REQUEST

The page request is invalid.

TIMEOUT

A timeout occurred whilst waiting for the filename to be set.

Usage example:

cause = my_fax.append('my_inbound_fax.tif', from_page=2)
if cause == my_fax.FileCause.FILE_BAD_TIFF:
    print("Could not append the file because it is not a valid TIFF")

UASClassFaxToSend.add_text_to_page(page_number, page_text)

This will add text to the page of the fax document indicated by page_number. Page numbering starts at 1.

This will not affect the physical file that was uploaded to the cloud, it will only affect the page of the fax document that will be transmitted.

Required arguments:

• page_number

  The number of the page to which to add the text.

• page_text

  The PageText object.

Please see the documentation on setting text for information on configuring text to be added to a fax document page.

This function will return a cause of type FileCause. If this function fails the fax document remains unchanged.

usage example:

Usage example:

# create the PageText object
page_text = my_fax.create_page_text()

# set text to be one inch from the top
page_text.Position.unit = page_text.Position.PagePositionUnits.INCHES
page_text.Position.from_page_top = 1

# replace existing text
page_text.mode = page_text.PageTextMode.REPLACE

# put the page number on the left
page_text.left_text = 'This is a fax from Bob'

# add the text to the first page
cause = my_fax.add_text_to_page(1, page_text)
if cause != my_fax.FileCause.NORMAL:
    print("Failed to add text to the page, cause is {0}".format(cause))

UASClassFaxToSend.append(filename, from_page=1, to_page=0, cipher=None)

To append the contents of a new file to an existing fax document, and specifying which pages of the new file to use.

Required argument:

• filename

  The name of the new file.

Optional argument:

• from_page

  The first page of the new file to use. Default is page 1.

• to_page

  The last page of the new file to use. Default is 0 which means to use all the pages starting from from_page.

• cipher

  if the fax to send is encrypted, supply the cipher here.

This function will return a cause of type FileCause.

Note: If this function fails, all existing content will remain unchanged.

Usage example:

cause = my_fax.append('my_inbound_fax.tif', from_page=2)
if cause != my_fax.FileCause.NORMAL:
    print("File error cause {0}".format(cause))

UASClassFaxToSend.create_page_text()

This function will create an object of type PageText which can be used to add text to one or more pages of a fax document object. Note that doing this will not affect the physical TIFF file, only the contents of the fax document to be sent.

PageText usage example:

# create the PageText object
page_text = my_fax.create_page_text()

# set text to be one inch from the top
page_text.Position.unit = page_text.Position.PagePositionUnits.INCHES
page_text.Position.from_page_top = 1

# replace existing text
page_text.mode = page_text.PageTextMode.REPLACE

# put the page number on the left
page_text.left_text = 'This is a fax from Bob'

# add the text to the first page
cause = my_fax.add_text_to_page(1, page_text)
if cause != my_fax.FileCause.NORMAL:
    print("Failed to add text to the page, cause is {0}".format(cause))

UASClassFaxToSend.set_content(filename, from_page=1, to_page=0, cipher=None)

Replace the contents of a fax document with the contents of a new TIFF file, also specifying which pages of the new file to use.

Required argument:

• filename

  The name of the new file.

Optional argument:

• from_page

  The first page of the new file to use. Default is page 1.

• to_page

  The last page of the new file to use. Default is 0 which means to use all the pages starting from from_page.

• cipher

  if the fax to send is encrypted, supply the cipher here.

This function will return a cause of type FileCause.

Note: If this function fails, all existing content will have been lost.

Usage example:

cause = my_fax.set_content('my_inbound_fax.tif', from_page=2)
if cause != my_fax.FileCause.NORMAL:
    print("File error cause {0}".format(cause))

• The fax PageText property