ML::Fax::archiveFaxInfoGet() - return FAX info for specified FAX file, as returned by ML::Fax::archiveFaxList(), ML::Fax::archiveFaxNewest() or ML::Fax::archiveFaxOldest()
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
fax_file_name
name of the FAX file in the archive area
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
0 or more of name=value, ... :
- DataFormat=1-D MH
- Device=ttyS0 - The modem that the FAX was received on
- EMAILed='NO' if never EMAILed else 'sfo@cargocult.ca by Stephen Oberski @ Wed Feb 22 11:00:47 2006'
- ErrCorrect=No
- Page=North American Letter
- Pages=2
- Printed='NO' if never printed else 'hylafax-ttyS0 by Ted Wooding @ Wed Feb 22 13:01:49 2006'
- Quality=Fine
- Received=2005/12/21 18:08:00
- Sender=905 795 8385
- SignalRate=14400 bit/s
- Status=OK
- TimeToRecv=1:53
ML::Fax::archiveFaxInfoSet() - set FAX info for specified FAX file, as returned by ML::Fax::archiveFaxList(), ML::Fax::archiveFaxNewest() or ML::Fax::archiveFaxOldest()
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
fax_file_name
name of the FAX file in the archive area
0 or more of name=value, ... :
- DataFormat=1-D MH
- Device=ttyS0 - The modem that the FAX was received on
- EMAILed='NO' if never EMAILed else 'sfo@cargocult.ca by Stephen Oberski @ Wed Feb 22 11:00:47 2006'
- ErrCorrect=No
- Page=North American Letter
- Pages=2
- Printed='NO' if never printed else 'hylafax-ttyS0 by Ted Wooding @ Wed Feb 22 13:01:49 2006'
- Quality=Fine
- Received=2005/12/21 18:08:00
- Sender=905 795 8385
- SignalRate=14400 bit/s
- Status=OK
- TimeToRecv=1:53
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
ML::Fax::archiveFaxList() - return list of archive FAX file names, ordered by increasing date/time, for the specified date/time range inclusive
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
start_date_time
"YYYY/MM/DD[ HH:MM:SS]" or "" for today at 00:00:00, default HH:MM:SS is "00:00:00"
end_date_time
"YYYY/MM/DD[ HH:MM:SS]" or "" for current date/time, default HH:MM:SS is "23:59:59"
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
0 or more of FAX file, YYYY/MM/DD HH:MM:SS
ML::Fax::archiveFaxNewest() - return name and date/time of newest file in the FAX archive
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
newestInfo
FAX file name,YYYY/MM/DD HH:MM:SS
ML::Fax::archiveFaxOldest() - return name and date/time of oldest file in the FAX archive
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
oldestInfo
FAX file name,YYYY/MM/DD HH:MM:SS
ML::Fax::authenticate() - validate authentication token
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
ML::Fax::del() - delete FAX file in spool area
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
fax_file_name
name of the FAX file in the spool area, must be simple file name, no path characters (i.e. '/', '\', ':' etc.) or a file name returned by ML::Fax::archiveFaxList(), ML::Fax::archiveFaxNewest() or ML::Fax::archiveFaxOldest()
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
ML::Fax::get() - get received FAX file
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
job_id/file_name
The ID of previously received fax or file in the spool area, must be simple file name, no path characters (i.e. '/', '\', ':' etc.) or a file name returned by ML::Fax::archiveFaxList(), ML::Fax::archiveFaxNewest() or ML::Fax::archiveFaxOldest()
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
contents
base64 encoded TIFF format received FAX file
ML::Fax::groupInfo() - return group information
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
group
The name of the group
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
description
Description of group, for display purposes only
modem_list
comma separated list of modems for this group
printer_list
comma separated list of printers for this group
ML::Fax::login() - return authentication token for name/password
DESCRIPTION
Must be called before any other ML::Fax() function to authenticate
and authorise. All other ML:Fax() functions take as input the authorization
token returned by this function. Since the authorization token can expire at any time,
the application must be prepared to handle the failure of an ML:Fax() function due to expiry of the authentication token (return == "AUTH") by re-invoking this function.
INPUT
user_name
ML::Fax user name
password
ML::Fax password in plain text
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
authentication
authentication token to be passed into all other ML::Fax functions
ML::Fax::logout() - invalidate authentication token
DESCRIPTION
Logout from the ML::Fax() service.
The authentication token is no longer valid and if used in subsequent calls
to ML::Fax() functions will result in an "AUTH" return.
Use the ML::Fax::login() function to re-authenticate.
INPUT
authentication
Authentication token to be passed into all other ML::Fax functions
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
ML::Fax::jobInfo() - return state of previously submitted (via ML::Fax::sendFax()) or received job_id
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
job_id
The ID of previously submitted FAX job (via ML::Fax::sendFax()) or received fax
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
state
The current state of the FAX job:
"ACTIVE" - actively being processed, i.e. transmitted or received
"BLOCKED" - blocked by concurrent activity, i.e. there is a job currently being transmitted on the modem
"DONE" - processing completed with success
"FAILED" - processing completed with failure
"PENDING" - waiting for time to send
"READY" - ready to be sent, waiting for resources (i.e. a free modem)
"SLEEPING" - waiting for scheduled timeout
"SUSPENDED" - not being scheduled
"UNDEFINED" - deleted from send/receive queue before transmission/reception complete
ML::Fax::printerInit() - return initiailization data for specified printer
For example, this allows a specific input tray to be selected.
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
printer_name
The name of the printer, should match a printer specified in the 'ml_fax_group.txt' configuration file.
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
init_data
base64 encoded printer initialization data
ML::Fax::privInfo() - return user privlede information
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
description
Description of user, for display purposes only
group_list
comma separated list of groups of which this user is a member
priv_list
comma separated list of privledes for this user
ML::Fax::put() - put FAX contents in spool area as name
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
contents
base64 encoded PS or TIFF format FAX file to subsequently transmit via ML::Fax::sendFax()
fax_file_name
name of the FAX file in the spool area, must be simple file name, no path characters (i.e. '/', '\', ':' etc.)
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
ML::Fax::received() - list contents of received FAX queue
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
0 or more of:
- elapsed_receive_time
Time spent receiving document (HH:MM:SS)
- file_size_bytes
File size (number of bytes)
- number_pages
Number of pages in document
- resolution
Resolution of received data
- TSI
Sender identity (TSI)
- page_width_mm
Page width in mm
- is_in_progress
1 (one) if receive in progress; otherwise 0 (zero)
ML::Fax::sendFax() - submit FAX for transmission
INPUT
authentication
authentication token returned by ML::Fax::login() to be passed into all ML::Fax functions
phonenumber
Destination string (number) to dial. [REQUIRED]
faxfile
Name of the FAX file as previously sent via ML::Fax::put(). Fax file must be in one of the native formats described below, i.e. PostScript or TIFF Class F. [REQUIRED]
notifyaddr
E-mail address of the person to be notified about the status of the job. Defaults to "". [OPTIONAL]
sendtime
Time when the FAX should be sent. Possible values: "now" or date in format "YYYYMMDDHHMM". This value must be in GMT time zone. Defaults to "now". [OPTIONAL]
lasttime
Kill the job if not successfully sent after this much time. Format "DDHHSS". Defaults to "000259" (3 hours). [OPTIONAL]
maxdials
The maximum number of times to dial the phone. Defaults to "12". [OPTIONAL]
maxtries
The maximum number of times to retry sending a job once connection is established. Defaults to "3". [OPTIONAL]
pagewidth
Set the transmitted page width in millimeters. Defaults to "216" (Letter size). [OPTIONAL]
pagelength
Set the transmitted page length in millimeters. Defaults to "279" (Letter size). [OPTIONAL]
vres
Set the vertical resolution in lines/inch to use when transmitting facsimile. High resolution equals to "196", low resolution equals to "98". Defaults to "196". [OPTIONAL]
schedpri
The scheduling priority to assign to the job. Defaults to "127" (Normal). [OPTIONAL]
OUTPUT
return
"OK", "ERROR", "AUTH" or "PRIV" - see below
message
Log information related to the success or failure of this function.
job_id
The ID of the submitted FAX job, valid only if return (above) = "OK". The job_id is unique, that is it will never be reused, so it can be used as the unique key for the submitted FAX.
Interface to the Micro-line FAX (ML::Fax) service.
Allows a client application to send, receive and monitor FAX transmission and reception.
The following interfaces are provided:
- ML::Fax::archiveFaxInfoGet() - return FAX info for specified FAX file, as returned by ML::Fax::archiveFaxList(), ML::Fax::archiveFaxNewest() or ML::Fax::archiveFaxOldest()
- ML::Fax::archiveFaxInfoSet() - set FAX info for specified FAX file, as returned by ML::Fax::archiveFaxList(), ML::Fax::archiveFaxNewest() or ML::Fax::archiveFaxOldest()
- ML::Fax::archiveFaxList() - return list of archive FAX file names, ordered by increasing date/time, for the specified date/time range inclusive
- ML::Fax::archiveFaxNewest() - return name and date/time of newest file in the FAX archive
- ML::Fax::archiveFaxOldest() - return name and date/time of oldest file in the FAX archive
- ML::Fax::authenticate() - validate authentication token returned by ML::Fax::login()
- ML::Fax::del() - delete FAX file from ML::Fax server
- ML::Fax::get() - retrieve FAX file from ML::Fax server
- ML::Fax::groupInfo() - retrieve group information from ML::Fax server
- ML::Fax::jobInfo() - return state of a FAX previously submitted via ML::Fax::sendFax()
- ML::Fax::login() - authenticate with ML::Fax service
- ML::Fax::logout() - logout from ML::Fax service
- ML::Fax::printerInit() - retrieve printer initialization data from ML::Fax server
- ML::Fax::privInfo() - retrieve user privlege information from ML::Fax server
- ML::Fax::put() - transfer FAX file to ML::Fax server for subsequent transmission via ML::Fax::sendFax()
- ML::Fax::received() - list contents of ML::Fax received queue
- ML::Fax::sendFax() - submit FAX for transmission
The client application should first call ML::Fax::login() to login to and authenticate with the ML::Fax service.
An authentication token is returned that must be passed into all other ML:Fax functions.
An authentication token has a limited duration and the client application must be designed to handle the failure of an ML::Fax
function due to authentication expiry by re-authenticating via the ML::Fax::login() function and using the new authentication token.
All ML::Fax functions (except ML::Fax::login()) expect the authentication token as the first parameter.
All ML::Fax functions return a return code and message as their last 2 parameters.
The return code has the following values:
- "OK" - ML::Fax function performed the requested function
- "ERROR" - ML::Fax function did not perform the requested function due to an underlying application or OS problem
- "AUTH" - ML::Fax function did not perform the requested function due to an invalid or expired authentication token
- "PRIV" - ML::Fax function did not perform the requested function due to lack of privilege for an otherwise valid authentication token
Note that a return of "AUTH" implies that the application must re-authenticate via ML::Fax:login()
while a return of "PRIV" implies that the authentication token is valid but the user name associated with the last ML::Fax::login()
does not have the privilege to perform the requested function.
The message contains information that provides additional information for the return code.
Typically the message will be logged by the application.
The application should never depend on the contents of the message staying the same for a given ML::Fax function and return value.
For a return of "OK" the message may contain log or trace information.
For a return of "ERROR", "AUTH" or "PRIV" the message may contain addition information on the error condition.
All received faxs are stored in TIFF Class F format.
The ML::Fax service will deduce the format of files at transmission time.
The following file formats are supported for transmission:
- PostScript document text conforming at level 3.0.
A PostScript file is converted at transmission time to TIFF Class F using
the GhostScript PostScript language interpreter.
Any fonts not defined in the PostScript document are rendered using local GhostScript fonts,
so the transmitted document may not exactly match the same document viewed on the client system.
- TIFF Class F
multi-page document,
Resolution: 98 pixels/inch (normal) or 196 pixels/inch (fine),
Image Width: 1728,
Compression Scheme: CCITT Group 3,
Bits/Sample: 1,
Samples/Pixel: 1,
Group 3 Options: EOL padding