传真(Fax)编程

开发平台：
C/C++

hylafax-client.1：源码内容
							."	$Id: hylafax-client.1,v 1.3 2008/01/31 02:26:36 faxguy Exp $
."
." HylaFAX Facsimile Software
."
." Copyright (c) 1993-1996 Sam Leffler
." Copyright (c) 1993-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
.ds Sn s-1SNPPs+1
.ds Ps Ps-2OSTs+2Ss-2CRIPTs+2
.TH HYLAFAX-CLIENT 1 "May 8, 1996"
.SH NAME
HylaFAX-client - introduction to *(Fx client applications and usage
.SH SYNOPSIS
.B sendfax
.RI [ options ]
.RI [ files .|.|.]
.br
.B sendpage
.RI [ options ]
.RI [ message .|.|.]
.br
.B faxstat
.RI [ options ]
.br
.B faxrm
.RI [ options ]
.br
.B faxalter
.RI [ options ]
.IR jobid .|.|.
.br
.B fax2ps
.RI [ options ]
.RI [ files .|.|.]
.SH DESCRIPTION
*(Fx is a telecommunication system for 
.SM UNIXc
(rg systems.
Among the features of *(Fx are:
.IP (bu 3
*(Fx runs as a network service; this means
a modem may be effectively shared by a large number of users.
.IP (bu 3
*(Fx can be configured to work with a wide variety of modems
on a wide variety of systems.
.IP (bu 3
Access to the system can be restricted by the administrator
to selected hosts and/or users.
.IP (bu 3
Transmission requests may be processed immediately (default)
or queued for processing at a later time,
in the manner of the
.IR at (1)
command.
.IP (bu 3
Remote facsimile machines may be polled to retrieve
publicly available documents.
.IP (bu 3
*(Ps(rg, PDF, and
.SM TIFF
Class F documents are passed directly to the fax server for transmission;
the system attempts to convert other file formats to either *(Ps or
.SM TIFF
through the use of an extensible file typing and conversion facility.
In normal operation
.SM ASCIIc
-text,
.IR troff (1)
output,
and
Silicon Graphics images are automatically converted.
Additional file formats can be added; see
.IR typerules (${MANNUM4_5}).
.IP (bu 3
The
.IR faxcover (1)
program can be automatically invoked to
create a cover page for each facsimile,
using information deduced by the
.IR sendfax
command.
Alternatively, users may supply their own cover pages using
their preferred tools.
.IP (bu 3
Facsimile are normally imaged in a system-default page size
(usually letter-size pages, 8.5" by 11", for sites in North America).
Alternate page sizes can be specified with a
.B -s
option to all *(Fx programs.
Well known page sizes include:
.SM "ISO A3,"
.SM "ISO A4,"
.SM "ISO A5,"
.SM "ISO A6,"
.SM "ISO B4,"
North American Letter,
American Legal,
American Ledger,
American Executive,
Japanese Letter,
and
Japanese Legal.
Note that it may not be permissible to image into the
full page area; the guaranteed reproducible area for a page is 
typically smaller.
Also, note that while arbitrary page sizes can be specified,
only a limited number of page dimensions are supported by the
facsimile protocol.
Thus if an odd-size facsimile is submitted for transmission
it may not be possible to determine if it can be sent
until the fax server establishes communication
with the remote facsimile machine.
.IP (bu 3
Facsimile can be sent at low
resolution (98 lines/inch) or
medium resolution (196 lines/inch)(emoften
called
.IR "fine mode" .
Documents with mixed resolution pages
are handled correctly.
.IP (bu 3
Users are notified by electronic mail if a job can not be
transmitted.
It is also possible to receive notification by mail when
a job has been completed successfully and each time that
the job is requeued for retransmission.
Any untransmitted documents are returned to the sender
by electronic mail in a form suitable for re-submission.
.IP (bu 3
Support is provided for broadcasting facsimile.
The *(Fx server software optimizes preparation of broadcast
documents and the client applications support the notion of a
.I "job group"
which permits a group of jobs to be manipulated together.
.IP (bu 3
Support is provided for transmitting alpha-numeric messages to
pager devices or GSM mobiles using the Simple Network Paging Protocol (*(Sn)
and the s-1IXOs+1 or s-1UCPs+1 protocol (for message delivery).
.PP
The *(Fx software is divided into two packages: software used on client
machines and software used on machines where one or more
modems reside.
Client software includes:
.IP (bu 3
.IR sendfax ,
a program to submit outgoing facsimile;
.IP (bu 3
.IR sendpage ,
a program to submit alpha-numeric messages to *(Sn servers;
.IP (bu 3
.IR faxstat ,
a program obtain status information
about *(Fx servers;
.IP (bu 3
.IR faxrm ,
a program to remove jobs and documents;
.IP (bu 3
.IR faxalter ,
a program to change parameters of queued jobs; and
.IP (bu 3
.IR fax2ps ,
a program that converts facsimile documents to *(Ps so that they
may be viewed with a *(Ps previewer or printed on a *(Ps printer
(this program is actually part of the companion 
.SM TIFF
distribution that is used by *(Fx).
.PP
Many systems also support submission of outgoing
facsimile by electronic mail and/or graphical interfaces to the
.I sendfax
program.
Such facilities are site-dependent; consult local documentation for
more information.
.SH "GETTING STARTED"
To use the *(Fx
client software on your machine you need to either load the appropriate
software on your machine, or you need to locate a machine that
already has the client software installed and setup symbolic links to
the appropriate directories.
If you choose the latter, then beware that you need links to three
directories: the directory where client applications reside,
.IR ${BIN} ,
the directory where the client application database files reside,
.IR ${LIBDATA} ,
and the directory where document conversion programs reside,
.I ${LIBEXEC}
(the last two directories may be the same on your system).
.PP
Once the software is setup on your machine you need to locate a
host that has a facsimile server that you can use.
The host, and possibly the modem on the host, should be defined
in your environment in the
.SM FAXSERVER
variable.
For example, for 
.I csh
users,
.IP
setenv FAXSERVER flake.asd
.LP
or for
.I ksh
or
.I sh
users,
.IP
FAXSERVER=flake.asd; export FAXSERVER
.LP
If there are multiple modems on your server then you may be
assigned to use a specific modem.
For example, if you are to use the modem attached to the 
.I ttym2
port on the server machine, then the
.SM FAXSERVER
variable should be setup as
.IP
FAXSERVER=ttym2@flake.asd; export FAXSERVER
.LP
(Note: the
.SM SNPPSERVER
environment variable is used instead of 
.SM FAXSERVER
by the
.I sendpage
program;  consult
.IR sendpage (${MANNUM1_8})
for more information.)
.LP
Note also, that before you can submit outgoing facsimile jobs
the administrator for the facsimile server may need to register
your identity in an access control list.
You will encounter the message
``fI530 User %s access denied.fP''
if access to your server is controlled and you are not properly
registered or you may be prompted for a password and then denied
service with ``fI530 Login incorrect.fP''.
.SH "DIAL STRINGS"
A dial string specifies how to dial the telephone in order to
reach a destination facsimile machine.
*(Fx permits arbitrary strings to be passed to the facsimile server
so that users can specify credit card information, 
.SM PBX
routing information, etc.
Alphabetic characters are automatically mapped to their numeric
key equivalents (e.g. ``1800GotMilk'' becomes ``18004686455'').
Other characters can be included for readability;
anything that must be stripped will be removed by the server
before the dialing string is passed to the fax modem.
Private information such as credit card access codes are
withheld from status messages and publicly accessible log files
(with proper configuration).
Facsimile servers also automatically insert any leading dialing
prefixing strings that are required to place outgoing phone calls;
e.g. dialing ``&9'' to get an outside line.
Additionally, if a phone number is fully specified with the
international direct dialing digits (c
.SM IDDDc
), then any
prefixing long distance or international dialing codes
that are required to place the call will be inserted
in the dial string by the server.
For example, ``+31.77.594.131'' is a phone number in
the Netherlands; it would be converted to ``&0113177594131''
if the call is placed in the United States.
The number ``+14159657824'' is a phone number in California;
if this number is called from within the 415 area code in the
United States, then the server would automatically convert this
to ``&9657824'' because in the San Francisco Bay Area, local phone
calls must not include the area code and long distance prefixing
code.
.PP
The general rule in crafting dial strings is to specify
exactly what you would dial on your telephone; and,
in addition, the actual phone number can be specified in a
location-independent manner by using the 
.SM IDD
syntax of ``+fIcountry-codefP fIlocal-partfP''.
.SH "COVER PAGES"
The
.I sendfax
program can automatically generate a cover page for each outgoing
facsimile.
Such cover pages are actually created by the
.IR faxcover (1)
program by using information that is deduced by
.I sendfax
and information that is supplied on the command line invocation of
.IR sendfax .
Users may also request that
.I sendfax
not supply a cover page and then provide their own cover page
as part of the data that is to be transmitted.
.PP
Automatically-generated cover pages may include the following
information:
.IP (bu 3
the sender's name, affiliation, geographic location, fax number,
and voice telephone number;
.IP (bu 3
the recipient's name, affiliation, geographic location, fax number,
and voice telephone number;
.IP (bu 3
text explaining what this fax is ``regarding'';
.IP (bu 3
text commentary;
.IP (bu 3
the local date and time that the job was submitted;
.IP (bu 3
the number of pages to be transmitted.
.LP
Certain of this information is currently obtained from a user's
personal facsimile database file; 
.BR ~/.faxdb .
Note that this file is deprecated; it is described here only
because it is still supported for compatibility with
older versions of the software.
.PP
The 
.B .faxdb
file is an
.SM ASCII
file with entries of the form
.IP
fIkeywordfP fB:fP fIvaluefP
.LP
where
.I keyword
includes:
.RS
.TP 14
.B Name
a name associated with destination fax machine;
.TP 14
.B Company
a company name;
.TP 14
.B Location
in-company locational information, e.g. a building#;
.TP 14
.B FAX-Number
phone number of fax machine;
.TP 14
.B Voice-Number
voice telephone number.
.RE
.PP
Data is free format.
Whitespace (blank, tab, newline) can be
freely interspersed with tokens.
If tokens include whitespace, they
must be enclosed in quote marks (``"'').
The ``#'' character introduces a comment(emeverything to the end of
the line is discarded.
.PP
Entries are collected into aggregate records by enclosing them in ``[]''.
Records can be nested to create a hierarchy that that supports the
inheritance of information(emunspecified information is
inherited from parent aggregate records.
.PP
For example, a sample file might be:
.sp .5
.nf
.RS
s-1[   Company:	"Silicon Graphics, Inc."
    Location:	"Mountain View, California"
    [ Name: "Sam Leff&ler"	FAX-Number: +1.415.965.7824 ]
]s+1
.fi
.RE
.LP
which could be extended to include another person at Silicon Graphics
with the following:
.sp .5
.nf
.RS
s-1[   Company:	"Silicon Graphics, Inc."
    Location:	"Mountain View, California"
    [ Name: "Sam Leff&ler"	FAX-Number: +1.415.965.7824 ]
    [ Name: "Paul Haeberli"	FAX-Number: +1.415.965.7824 ]
]s+1
.RE
.fi
.PP
Experience indicates that the hierarchical nature of this database
format makes it difficult to maintain with automated mechanisms.
As a result it is being replaced by other, more straightforward
databases that are managed by programs that front-end the
.I sendfax
program.
.SH "CONFIGURATION FILES"
*(Fx client applications can be tailored on a per-user and
per-site basis through configuration files.
Per-site controls are placed in the file
.BR ${LIBDATA}/hyla.conf ,
while per-user controls go in
.BR ~/.hylarc .
In addition a few programs that have many parameters that are
specific to their operation support an additional configuration
file; these files are identified in their manual pages.
.PP
Configuration files have a simple format and are entirely
.SM ASCII.
A configuration parameter is of the form
.sp .5
.ti +0.5i
fBtagfP: fIvaluefP
.br
.sp .5
where a fItagfP identifies a parameter and a fIvaluefP
is either a string, number, or boolean value.
Comments are introduced by the ``#'' character
and extend to the end of the line.
String values start at the first non-blank character
after the ``:'' and continue to the first non-whitespace
character or, if whitespace is to be included, may be
enclosed in quote marks (``"'').
String values enclosed in quote marks may also use the
standard C programming conventions for specifying escape
codes; e.g. ``en'' for a newline character and ``exxx''
for an octal value.
Numeric values are specified according to the C programming
conventions (leading ``0x'' for hex, leading ``0'' for octal, otherwise
decimal).
Boolean values are case insensitive.
For a true value, either ``Yes'' or ``On'' should
be used.
For a false value, use ``No'' or ``Off''.
.SH "RECEIVED FACSIMILE"
Incoming facsimile are received by facsimile servers and deposited
in a receive queue directory on the server machine.
Depending on the server's configuration, files in this directory
may or may not be readable by normal users.
The
.I faxstat
program can be used to view the contents of the receive queue
directory:
.sp .5
.nf
.RS
s-1fChyla% faxstat -r
HylaFAX scheduler on hyla.chez.sgi.com: Running
Modem ttyf2 (+1 510 999-0123): Running and idle
Protect Page  Owner        Sender/TSI  Recvd@ Filename
-rw-r--    9  fax       1 510 5268781 05Jan96 fax00005.tif
-rw-r--    8  fax       1 510 5268781 07Jan96 fax00009.tif
-rw-r--    2  fax       1 510 5268781 07Jan96 fax00010.tif
-rw-r--    3  fax        +14159657824 08Jan96 fax00011.tif
-rw-r--    2  fax        +14159657824 08Jan96 fax00012.tiffPs+1
.RE
.fi
.LP
Consult the 
.I faxstat
manual page for a more detailed description of this information.
.PP
Received facsimile are stored as
.SM TIFF
Class F files.
These files are Bi-level images that are encoded using the
.SM "CCITT T.4"
or
.SM "CCITT T.6"
encoding algorithms.
The
.IR fax2ps (1)
program can be used to view and print these files.
A file can be viewed by converting it to *(Ps and then
viewing it with a suitable *(Ps previewing program, such
as
.IR xpsview (1)
(Adobe's Display *(Ps-based viewer),
.IR ghostview (1)
(a public domain previewer),
or image viewer programs such as
.IR viewfax (1)
(public domain),
.IR faxview (1)
(another public domain 
.SM TIFF
viewer program),
.IR xv (1)
(shareware and/or public domain), or
.IR xtiff (1)
(a program included in the public domain
.SM TIFF
software distribution).
Consult your local resources to figure out what tools are available
for viewing and printing received facsimile.
.SH "CLIENT-SERVER PROTOCOL"
*(Fx client applications communicate with servers using
either a special-purpose
.I "communications protocol"
that is modeled after the Internet File Transfer Protocol (s-1FTPs+1)
or, when submitting alpha-numeric pages, the Simple Network Paging Protocol
(*(Sn), specified in
.SM RFC
1861.
All client programs support a
.B -v
option that can be used to observe the protocol message exchanges.
In some situations it may be more effective to communicate directly
with a *(Fx server using the client-server protocol.
This can be accomplished with an
.SM FTP
or Telnet client application; though an
.SM FTP
client is recommended because it implements the protocol needed
to obtain server status information.
For information on the server-side support provided with *(Fx consult
.IR hfaxd (${MANNUM1_8}).
For documentation on the client-server fax protocol consult s-1RFC XXXXs+1
(fIto be filled infP).
.SH EXAMPLES
This section gives several examples of command line usage;
consult the manual pages for the individual commands for
information on the options and program operation.
.PP
The following command queues the file
.B zall.ps
for transmission to John Doe at the number (123)456-7890 using fine mode;
the server will attempt to send it at 4:30 A.M.:
.sp .5
.RS
s-1fCsendfax -a "0430" -m -d "John Doe@1.123.456.7890" zall.psfPs+1
.RE
.sp .5
(the leading ``1.'' is supplied to dial area code ``123'' in the
United States.)
.PP
The following command generates a one-page facsimile that
is just a cover page:
.sp .5
.nf
.RS
s-1fCfaxcover -t "John Doe" -n "(123)456-7890" 
    -c "Sorry John, I forgot the meeting..." |
    sendfax -n -d "(123)456-7890"fPs+1
.RE
.fi
.sp .5
(note that the line was broken into several lines solely for presentation.)
.PP
The following command displays the status of the facsimile
server and any jobs queued for transmission:
.sp .5
.RS
s-1fCfaxstat -sfPs+1
.RE
.PP
The following command displays the status of the facsimile
server and any documents waiting in the receive queue on the
server machine:
.sp .5
.RS
s-1fCfaxstat -rfPs+1
.RE
.PP
The following command shows how to use an 
.SM FTP
client program to communicate directly with a *(Fx server:
.sp .5
.nf
.RS
s-1fChyla% fBftp localhost hylafaxfP
Connected to localhost.
220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
Name (localhost:sam): 
230 User sam logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> fBdir sendqfP
200 PORT command successful.
150 Opening new data connection for "sendq".
208  126 S    sam 5268781       0:3   1:12   16:54 No local dialtone
226 Transfer complete.
ftp> fBquote jkill 208fP
200 Job 208 killed.
ftp> fBdir doneqfP
200 PORT command successful.
150 Opening new data connection for "doneq".
208  126 D    sam 5268781       0:3   1:12         No local dialtone
226 Transfer complete.
ftp> fBquote jdele 208fP
200 Job 208 deleted; current job: (default).
ftp> fBdir docqfP
200 PORT command successful.
150 Opening new data connection for "docq".
-rw----   1      sam    11093 Jan 21 16:48 doc9.ps
226 Transfer complete.
ftp> fBdele docq/doc9.psfP
250 DELE command successful.
ftp> fBdir recvqfP
200 PORT command successful.
150 Opening new data connection for "recvq".
-rw-r--    4  fax       1 510 5268781 30Sep95 faxAAAa006uh
-rw-r--    9  fax        +14159657824 11Nov95 faxAAAa006nC
-rw----   25  fax        +14159657824 Fri08PM fax00016.tif
226 Transfer complete.
ftp> fBquitfP
221 Goodbye.fPs+1
.RE
.fi
.LP
The following command shows how to use a Telnet client program
to communicate directly with an *(Sn server:
.sp .5
.nf
.RS
s-1fChyla% fBtelnet melange.esd 444fP
Trying 192.111.25.40...
Connected to melange.esd.sgi.com.
Escape character is '^]'.
220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
fBlogin samfP
230 User sam logged in.
fBhelpfP
214 The following commands are recognized (* =>'s unimplemented).
214 2WAY*   ALER*   DATA    HOLD    LOGI    MSTA*   PING    RTYP*   STAT 
214 ABOR    CALL*   EXPT*   KTAG*   MCRE*   NOQU*   QUIT    SEND    SUBJ 
214 ACKR*   COVE*   HELP    LEVE    MESS    PAGE    RESE    SITE 
250 Direct comments to FaxMaster@melange.esd.sgi.com.
fBpage 5551212fP
250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
fBsendfP
250 Message processing completed.
fBquitfP
221 Goodbye.
Connection closed by foreign host.
.RE
.SH FILES
.ta w'${LIBDATA}/faxcover.ps        'u
.nf
${BIN}/sendfax	for sending facsimile
${BIN}/sendpage	for sending alpha-numeric pages
${BIN}/fax2ps	for converting facsimile to *(Ps
${BIN}/faxalter	for altering queued jobs
${BIN}/faxcover	for generating cover sheets
${BIN}/faxmail	for converting email to *(Ps
${BIN}/faxrm	for removing queued jobs
${BIN}/faxstat	for facsimile server status
${LIBEXEC}/sgi2fax	s-1SGIs+1 image file converter
${LIBEXEC}/textfmt	s-1ASCIIs+1 text converter
${LIBDATA}/typerules	file type and conversion rules
${LIBDATA}/pagesizes	page size database
${LIBDATA}/faxcover.ps	prototype cover page
${LIBDATA}/dialrules	optional client dialstring rules
${SPOOL}/tmp/sndfaxXXXXXX	temporary files
.fi
.SH "SEE ALSO"
.IR at (1),
.IR fax2ps (1),
.IR faxalter (1),
.IR faxcover (1),
.IR faxmail (1),
.IR faxrm (1),
.IR faxstat (1),
.IR sgi2fax (1),
.IR faxq (${MANNUM1_8}),
.IR viewfax (1),
.IR hylafax-server (${MANNUM4_5}),
.IR dialrules (${MANNUM4_5}),
.IR pagesizes (${MANNUM4_5}),
.IR typerules (${MANNUM4_5}),
.IR services (4)

						