Making the Premier Open-Source Fax Management System Even Better
The controls program is passed the respective job ID number as the first and only argument.
The controls program should produce a simple line-based ASCII output containing a series of records of the form:
which is parsed the same manner as all HylaFAX config files. Parameter values are parsed exactly as specified in hylafax-config(5F); i.e. values with embedded whitespace may be enclosed in quote marks (``"'').
All output on a line following a ``#'' character is ignored.
The output order is important. The last parameter value in the output overrides any previous values in the output. Otherwise a default value is used from the faxq configuration file.
The following parameters may be output on a per-job basis; consult hylafax-config(5F) for a description of each parameter (except Modem, Priority, and RejectNotice which are described below).
Tag Type Default Description MaxConcurrentCalls integer 1 max concurrent jobs to process for a destination MaxDials integer unlimited max phone calls to make to transmit a job MaxSendPages integer unlimited max pages to permit in a send MaxTries integer 3 max attempts to transmit a job Modem string Any ModemGroup to use for destination Notify string - notification override for job Priority integer - priority to use for job Proxy string - proxy server to which the job should be delivered ProxyUser string - authentication username for the proxy server ProxyPass string - authentication password for the proxy server ProxyMailbox string - E-Mail address for job notification ProxyNotification string none notification request ProxyJobTag string see below jobtag for proxy job ProxyLogMode octal 0600 protection to use for logs retrieved from proxy server ProxyTries integer -1 number of tries proxy should attempt ProxyDials integer -1 number of dials proxy should attempt ProxyReconnects integer 5 number of reconnections to proxy for any job submisison RejectNotice string - rejection notice for transmit job RewriteFaxname string - replace faxname in job request with this RewriteFaxnumber string - replace faxnumber in job request with this TimeOfDay string Any default time-of-day restrictions VRes integer - Vertical resolution UseXVRes integer - Usage of extended resolutions UseColor integer - Usage of color
The Modem parameter controls which ModemGroup is used in sending faxes to the destination. If the user assigns a ModemGroup for a specific job where all modems are outside of this ModemGroup matching a destination, then the value of Modem is overridden by the user's assignment. Likewise, if the user assigns a ModemGroup for a specific job where some, but not all, of the modems are included in this ModemGroup matching a destination, then the value of Modem is overridden by the inclusive set of modems found in both.
The Notify parameter allows an override of whatever notification request the client requested in the job. Options are ``none'', ``when requeued'', ``when done'', and ``when done+requeued''.
The Priority parameter controls the priority to assign to the job. This overrides any priority requested by the submitter.
The Proxy parameter controls to which host the job should be delivered for transmission. This should be a hostname or IP address and may include the modem group name when formatted as the host option for sendfax(1). The proxy server should have login access permitted for the originating server without a password if ProxyUser and ProxyPass are not also provided. Caution: actions such as job removal and job modification (such as those done by faxrm(1) or faxalter(1)) will not currently propagate to the proxy and is a matter for future development. Therefore, such actions should be made on the proxy server directly.
The ProxyMailbox and ProxyNotification identify the e-mail address and the notification mechanism for the proxied job. (This does not change the e-mail address or the notification mechanism for the originating job.)
The ProxyJobTag sets the jobtag for the job on the proxy server. By default this is the jobid for the originating job.
The ProxyLogMode parameter specifies the file mode protection that should be used for the logs that are able to be retrieved from the proxy server. (In order to retrieve logs the proxy server must permit it.)
The ProxyTries and ProxyDials parameters specify the number of respective attempts that the proxy server should make. The default is -1, and any value less than 1 indicates that the proxy server should be delegated all remaining attempts.
The ProxyReconnects parameter specifies the number of reconnections that should be made to the proxy server in the event that the network connection is lost. Attempts are made no sooner than 60 seconds apart, so to tolerate a network outage of 30 minutes ProxyReconnects should be set to ``30'' or higher.
The RejectNotice parameter controls whether or not to reject jobs to the destination. Jobs that are rejected are done so without placing a phone call and the associated message is returned to the job submitter. This facility can be used to disallow calling sensitive phone numbers; for example
RejectNotice: "Calls to emergency numbers are not permitted"
The RewriteFaxname and RewriteFaxnumber parameters allow the ``faxname'' and ``faxnumber'' parameters in the job request file to be replaced and rewritten with the given values.
The VRes parameter controls the vertical resolution. Possible values are 98 (normal resolution, equivalent to sendfax -l option) and 196 (fine resolution, equivalent to sendfax -m option).
The UseColor parameter is used to enable or disable the usage of color as supported by the receiver. Possible values are 1 (enable color usage, equivalent to sendfax -O usecolor:yes option) and 0 (disable color usage). This parameter may be used in conjunction with DesiredDF: 6 in order to abort fax transmission if the receiver does not support color facsimile.
The UseXVRes parameter is used to enable or disable the usage of extended resolutions supported by the receiver. Possible values are 1 (enable extended resolutions usage, equivalent to sendfax -G option) and 0 (disable extended resolutions usage). This parameter supersedes the usage of VRes.
In addition to the above parameters, any other parameters that are specified are automatically accumulated and passed to programs invoked by faxq, such as faxsend and pagesend. (Note that in a batched-jobs instance that these parameters will apply to all jobs in the batch.) This is a convenient mechanism for defining configuration parameters for all modems without having to modify each modem-specific configuration file. For example,
This mechanism also makes it easy to control transmit-related parameters according to the destination phone number. For example, to disable use of ECM and restrict the transmit speed when placing international phone calls one might use:
DesiredBR: 3 DesiredEC: 0 DesiredDF: 1
1. Create file bin/jobcontrol with the following content:
#!/bin/sh echo "MaxDials: exit 0
2. Ensure that bin/jobcontrol is marked as executable:
chmod +x bin/jobcontrol
3. Add parameter JobControlCmd to hylafax-config(5F); (etc/config) file:
The controls program will likely need to refer to the sendq file corresponding to the job in order to obtain information such as the number being dialed, the job owner, or the number of send attempts. For this purpose the parseQfile function has been placed in bin/common-functions to assist in this. For example:
#!/bin/sh . etc/setup.cache . bin/common-functions QFILE=sendq/q$1 SetupPrivateTmp parseQfile case "$number-$owner-$tottries" in 5551212-lee-3) echo "Class1ECMSupport: no";; *-sam-*) echo "LocalIdentifier: +1.800.555.1212";; 911-*) echo "RejectNotice: \"Calls to 911 are not permitted\"";; esac exit 0