传真(Fax)编程

开发平台：
C/C++

jobcontrol.1m：源码内容
							."	$Id: jobcontrol.1m,v 1.6 2008/07/26 16:50:35 faxguy Exp $
."
." HylaFAX Facsimile Software
."
." Copyright (c) 1994-1996 Sam Leffler
." Copyright (c) 1994-1996 Silicon Graphics, Inc.
." HylaFAX is a trademark of Silicon Graphics
." 
." Permission to use, copy, modify, distribute, and sell this software and 
." its documentation for any purpose is hereby granted without fee, provided
." that (i) the above copyright notices and this permission notice appear in
." all copies of the software and related documentation, and (ii) the names of
." Sam Leffler and Silicon Graphics may not be used in any advertising or
." publicity relating to the software without the specific, prior written
." permission of Sam Leffler and Silicon Graphics.
." 
." THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
." EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
." WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
." 
." IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
." ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
." OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
." WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
." LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
." OF THIS SOFTWARE.
."
.if n .po 0
.ds Fx fIHylas-1FAXs+1fP
.TH JOBCONTROL ${MANNUM1_8} "Mar 27, 2006"
.SH NAME
jobcontrols - per-job controls for *(Fx servers
.SH DESCRIPTION
The *(Fx configuration parameter
.B JobControlCmd
specifies the script that is used to apply 
per-job controls on job characteristics
such as the time-of-day to place a call.
.PP
The controls program is passed the respective job ID number as the first and only argument.
.PP
The controls program should produce a simple line-based
.SM ASCII
output containing a series of records of the form:
.sp .5
.RS
param: value
.RE
.sp .5
which is parsed the same manner as all HylaFAX config files.
Parameter values are parsed exactly as specified in
.IR hylafax-config (${MANNUM4_5});
i.e. values with embedded whitespace may be enclosed in quote marks (``"'').
.PP
All output on a line following a ``#'' character is ignored.
.PP
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
.I faxq
configuration file.
.PP
The following parameters may be output on a per-job basis;
consult
.IR hylafax-config (${MANNUM4_5})
for a description of each parameter
(except
.BR Modem ,
.BR Priority ,
and
.B RejectNotice
which are described below).
.sp .5
.nf
.ta w'MaxConcurrentCalls    'u +w'integer    'u +w'fIunlimitedfP    'u
fBTag	Type	Default	DescriptionfP
MaxConcurrentCalls	integer	s-11s+1	max concurrent jobs to process for a destination
MaxDials	integer	s-1fIunlimitedfPs+1	max phone calls to make to transmit a job
MaxSendPages	integer	s-1fIunlimitedfPs+1	max pages to permit in a send
MaxTries	integer	s-13s+1	max attempts to transmit a job
Modem	string	s-1Anys+1	ModemGroup to use for destination
Notify	string	-	notification override for job
Priority	integer	-	priority to use for job
RejectNotice	string	-	rejection notice for transmit job
TimeOfDay	string	s-1Anys+1	default time-of-day restrictions
VRes	integer	-	Vertical resolution
UseXVRes	integer	-	Usage of extended resolutions
.fi
.PP
The
.B Modem
parameter controls which
.B ModemGroup
is used in sending faxes to the destination.  If the user
assigns a
.B ModemGroup
for a specific job where all modems are outside of this
.B ModemGroup
matching a destination, then the value of
.B Modem
is overridden by the user's assignment.  Likewise, if the user
assigns a
.B ModemGroup
for a specific job where some, but not all, of the modems are
included in this
.B ModemGroup
matching a destination, then the value of
.B Modem
is overridden by the inclusive set of modems found in both.
.PP
The
.B 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''.
.PP
The
.B Priority
parameter controls the priority to assign to the job.  This
overrides any priority requested by the submitter.
.PP
The
.B 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
.sp .5
.nf
.ft C
    RejectNotice: "Calls to emergency numbers are not permitted"
.ft P
.fi
.PP
The
.B VRes
parameter controls the vertical resolution. Possible values are 98 (normal resolution, equivalent to
.I sendfax
-l option) and 196 (fine resolution, equivalent to
.I sendfax
-m option).
.PP
The
.B 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
.I sendfax
-G option) and 0 (disable extended resolutions usage).
This parameter supersedes the usage of
.B VRes.
.PP
In addition to the above parameters, any other parameters that are specified
are automatically accumulated and passed to programs invoked by
.IR faxq ,
such as
.I faxsend
and
.IR 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,
.sp .5
.nf
.ft C
    SessionTracing: 0x4f
.ft P
.fi
.PP
This mechanism also makes it easy to control transmit-related parameters
according to the destination phone number.  For example, to disable use
of 
.SM ECM
and restrict the transmit speed when placing
international phone calls one might use:
.sp .5
.nf
.ft C
    DesiredBR: 3
    DesiredEC: 0
    DesiredDF: 1
.ft P
.fi
.SH EXAMPLES
Change (overlap) MaxDials parameter to 3 for all outgoing calls.
.PP
1. Create file bin/jobcontrol with the following content:
.sp .5
.nf
.ft C
   #!/bin/sh
   echo "MaxDials: "3""
   exit 0
.ft P
.fi
.PP
2. Ensure that bin/jobcontrol is marked as executable:
.sp .5
.nf
.ft C
    chmod +x bin/jobcontrol
.ft P
.fi
.PP
3. Add parameter JobControlCmd to
.IR hylafax-config (5F);
(etc/config) file:
.sp .5
.nf
.ft C
    JobControlCmd: bin/jobcontrol
.ft P
.fi
.PP
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:
.nf
.ft C
    #!/bin/sh
    . etc/setup.cache
    . bin/common-functions
    QFILE=sendq/q$1
    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
.ft P
.fi
.SH NOTES
.B JobControlCmd
is run each time the job moves into the run-queue ("READY" state), and all
output is effective on each instance.  If the administrator wishes to vary
output based on the attempt sequence, then the q-file values should be
consulted in the process.  Furthermore, blind usage of options such as
.B Priority
could be confusing as it would essentially prevent a job from increasing or
decreasing in job priority as usually expected after call attempts.
.SH "SEE ALSO"
.IR faxq (${MANNUM1_8}),
.IR hylafax-config (${MANNUM4_5}),
.IR re_format (7).

						