.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Client 3pm" .TH Client 3pm "2018-08-20" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Fax::Hylafax::Client \- Simple HylaFAX client .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Fax::Hylafax::Client qw(sendfax); \& \& my $fax = sendfax( \& dialstring => \*(Aq5555555555\*(Aq, \& docfile => \*(Aq/usr/home/test/document.ps\*(Aq, \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a simple Perl client for HylaFAX fax server (www.hylafax.org). It communicates with the server directly through FTP-like protocol and thus does not require any HylaFAX software components to be installed on the client machine. .SH "MAIN METHODS AND ATTRIBUTES" .IX Header "MAIN METHODS AND ATTRIBUTES" .IP "\fBsendfax\fR" 4 .IX Item "sendfax" This method sends a fax job to the server. Returns \*(L"Client::Queued\*(R" object. Takes a hash of the following attributes: .RS 4 .IP "host" 4 .IX Item "host" Hostname of the server. Defaults to \*(L"localhost\*(R". [\s-1OPTIONAL\s0] .IP "port" 4 .IX Item "port" Connection port of the server. Defaults to \*(L"4559\*(R". [\s-1OPTIONAL\s0] .IP "user" 4 .IX Item "user" Username of the client. Defaults to \*(L"anonymous\*(R". [\s-1MAY BE REQUIRED\s0] .IP "password" 4 .IX Item "password" Password of the client. Defaults to \*(L"anonymous\*(R". [\s-1MAY BE REQUIRED\s0] .IP "dialstring" 4 .IX Item "dialstring" Destination string (number) to dial. [\s-1REQUIRED\s0] .IP "docfile" 4 .IX Item "docfile" Full pathname of the document file. This attribute takes a single filename (scalar) or a reference to an array of filenames. Document files must be in one of the native HylaFAX formats, i.e. Plain Text, PostScript, \s-1TIFF\s0 Class F, or \s-1PDF.\s0 [\s-1REQUIRED\s0 unless you use \*(L"poll\*(R" option] .IP "coverfile" 4 .IX Item "coverfile" Full pathname of the cover page file. All notes about \*(L"docfile\*(R" apply, except it only takes one filename as scalar. [\s-1OPTIONAL\s0] .IP "notifyaddr" 4 .IX Item "notifyaddr" E\-mail address of the person to be notified about the status of the job. Defaults to \&\*(L"user@hostname\*(R". [\s-1OPTIONAL\s0] .IP "notify" 4 .IX Item "notify" Controls the email notification messages from the server. Possible values: \*(L"none\*(R" \- notify if error only, \*(L"done\*(R" \- notify when done, \*(L"requeue\*(R" \- notify if job is re-queued, \&\*(L"done+requeue\*(R". Defaults to \*(L"none\*(R". [\s-1OPTIONAL\s0] .IP "passive" 4 .IX Item "passive" If set to \*(L"1\*(R" connects to server in \s-1PASSIVE\s0 mode. Defaults to \*(L"0\*(R". [\s-1OPTIONAL\s0] .IP "sendtime" 4 .IX Item "sendtime" Time when the fax should be sent. Possible values: \*(L"now\*(R" or date in format \*(L"\s-1YYYYMMDDHHMM\*(R".\s0 It looks like this value must be in \s-1GMT\s0 time zone. Defaults to \*(L"now\*(R". [\s-1OPTIONAL\s0] .IP "lasttime" 4 .IX Item "lasttime" Kill the job if not successfully sent after this much time. Format \*(L"\s-1DDHHSS\*(R".\s0 Defaults to \*(L"000259\*(R" (3 hours). [\s-1OPTIONAL\s0] .IP "maxdials" 4 .IX Item "maxdials" The maximum number of times to dial the phone. Defaults to \*(L"12\*(R". [\s-1OPTIONAL\s0] .IP "maxtries" 4 .IX Item "maxtries" The maximum number of times to retry sending a job once connection is established. Defaults to \*(L"3\*(R". [\s-1OPTIONAL\s0] .IP "pagewidth" 4 .IX Item "pagewidth" Set the transmitted page width in millimeters. Defaults to \*(L"216\*(R" (Letter size). [\s-1OPTIONAL\s0] .IP "pagelength" 4 .IX Item "pagelength" Set the transmitted page length in millimeters. Defaults to \*(L"279\*(R" (Letter size). [\s-1OPTIONAL\s0] .IP "vres" 4 .IX Item "vres" Set the vertical resolution in lines/inch to use when transmitting facsimile. High resolution equals to \*(L"196\*(R", low resolution equals to \*(L"98\*(R". Defaults to \*(L"196\*(R". [\s-1OPTIONAL\s0] .IP "chopthreshold" 4 .IX Item "chopthreshold" The amount of white space, in inches, that must be present at the bottom of a page before HylaFAX will attempt to truncate the page transmission. Defaults to \*(L"3\*(R". [\s-1OPTIONAL\s0] .IP "schedpri" 4 .IX Item "schedpri" The scheduling priority to assign to the job. Defaults to \*(L"127\*(R" (Normal). [\s-1OPTIONAL\s0] .IP "poll" 4 .IX Item "poll" Try to poll a fax from remote machine. Value can be an empty string or \*(L"selector [passwd]\*(R". [\s-1OPTIONAL\s0] .RE .RS 4 .RE .IP "\fBsendpage\fR" 4 .IX Item "sendpage" Sends \s-1SNPP\s0 page job to the server. Returns \*(L"Client::Queued\*(R" object. Takes a hash of the following attributes: .RS 4 .IP "host" 4 .IX Item "host" Same as in \*(L"sendfax\*(R". .IP "port" 4 .IX Item "port" Connection port of the server. Defaults to \*(L"444\*(R". [\s-1OPTIONAL\s0] .IP "user" 4 .IX Item "user" Same as in \*(L"sendfax\*(R". .IP "password" 4 .IX Item "password" Same as in \*(L"sendfax\*(R". .IP "pin" 4 .IX Item "pin" Pager Identification Number as defined in \*(L"pagermap\*(R" file on the server. [\s-1REQUIRED\s0] .IP "message" 4 .IX Item "message" Text message to be sent (alfa-numeric pagers only). [\s-1OPTIONAL\s0] .IP "notifyaddr" 4 .IX Item "notifyaddr" Same as in \*(L"sendfax\*(R". .IP "notify" 4 .IX Item "notify" Same as in \*(L"sendfax\*(R". .IP "passive" 4 .IX Item "passive" Same as in \*(L"sendfax\*(R". .IP "maxdials" 4 .IX Item "maxdials" Same as in \*(L"sendfax\*(R". .IP "maxtries" 4 .IX Item "maxtries" Same as in \*(L"sendfax\*(R". .IP "level" 4 .IX Item "level" Priority level to assign to the job. Values can be \*(L"0\-7\*(R" (0 being the highest). Defaults to \*(L"1\*(R" (Normal). [\s-1OPTIONAL\s0] .RE .RS 4 .RE .IP "\fBfaxinfo\fR" 4 .IX Item "faxinfo" Request the status of a particular job. Returns \*(L"Client::Instant\*(R" object. Can take only the number of the job as an attribute or a hash of the following attributes: .RS 4 .IP "host" 4 .IX Item "host" Same as in \*(L"sendfax\*(R". .IP "port" 4 .IX Item "port" Same as in \*(L"sendfax\*(R". .IP "user" 4 .IX Item "user" Same as in \*(L"sendfax\*(R". .IP "password" 4 .IX Item "password" Same as in \*(L"sendfax\*(R". .IP "jobid" 4 .IX Item "jobid" \&\s-1ID\s0 of the job. [\s-1REQUIRED\s0] .IP "passive" 4 .IX Item "passive" Same as in \*(L"sendfax\*(R". .RE .RS 4 .RE .IP "\fBfaxrm\fR" 4 .IX Item "faxrm" Remove job from the server (kill it). Returns \*(L"Client::Instant\*(R" object. Behaves like and has the same attributes as \*(L"faxinfo\*(R". .IP "\fBfaxstat\fR" 4 .IX Item "faxstat" Request statistics from the server. Returns \*(L"Client::Instant\*(R" object. Takes a hash of the following attributes: .RS 4 .IP "host" 4 .IX Item "host" Same as in \*(L"sendfax\*(R". .IP "port" 4 .IX Item "port" Same as in \*(L"sendfax\*(R". .IP "user" 4 .IX Item "user" Same as in \*(L"sendfax\*(R". .IP "password" 4 .IX Item "password" Same as in \*(L"sendfax\*(R". .IP "passive" 4 .IX Item "passive" Same as in \*(L"sendfax\*(R". .IP "info" 4 .IX Item "info" If set to \*(L"1\*(R" displays additional status information for the server. This status typically has information such as the HylaFAX version, the physical location of the server machine, and an administrative contact for the server. Defaults to \*(L"0\*(R". [\s-1OPTIONAL\s0] .IP "files" 4 .IX Item "files" If set to \*(L"1\*(R" displays the status of document files located in the docq directory on the server machine. The \*(L"filefmt\*(R" attribute defines the content and format of information reported with this option. Defaults to \*(L"0\*(R". [\s-1OPTIONAL\s0] .IP "queue" 4 .IX Item "queue" If set to \*(L"1\*(R" displays the status of jobs in the send queue on the server machine. The \*(L"jobjmt\*(R" attribute defines the content and format of information reported with this option. Defaults to \*(L"0\*(R". [\s-1OPTIONAL\s0] .IP "done" 4 .IX Item "done" If set to \*(L"1\*(R" displays the status of all jobs that have completed; i.e. those jobs located in the doneq directory on the server machine. The \*(L"jobfmt\*(R" attribute defines the content and format of information reported with this option. Defaults to \*(L"0\*(R". [\s-1OPTIONAL\s0] .IP "received" 4 .IX Item "received" If set to \*(L"1\*(R" displays the receive queue status. The \*(L"rcvfmt\*(R" attribute defines the content and format of information reported with this option. Defaults to \*(L"0\*(R". [\s-1OPTIONAL\s0] .IP "filefmt" 4 .IX Item "filefmt" The format string to use when returning file status information. See \*(L"faxstat\*(R" man pages for details. [\s-1OPTIONAL\s0] .IP "jobfmt" 4 .IX Item "jobfmt" The format string to use when returning job status information. See \*(L"faxstat\*(R" man pages for details. [\s-1OPTIONAL\s0] .IP "rcvfmt" 4 .IX Item "rcvfmt" The format string to use when returning status information about received jobs. See \*(L"faxstat\*(R" man pages for details. [\s-1OPTIONAL\s0] .RE .RS 4 .RE .SH "METHODS AND ATTRIBUTES OF ALL Client::* OBJECTS" .IX Header "METHODS AND ATTRIBUTES OF ALL Client::* OBJECTS" .IP "\fBsuccess\fR" 4 .IX Item "success" Returns true if the task was accepted. This only means the task request was successfully processed by the server. This does not always mean the task itself was successfully completed. Use \*(L"faxinfo\*(R" to check for that. .IP "\fBtrace\fR" 4 .IX Item "trace" Returns responses from the last communication with the server. Useful for debugging. .SH "METHODS AND ATTRIBUTES OF Client::Queued OBJECTS ONLY" .IX Header "METHODS AND ATTRIBUTES OF Client::Queued OBJECTS ONLY" .IP "\fBfaxinfo\fR" 4 .IX Item "faxinfo" Returns the status of the job at this particular moment. .IP "\fBfaxrm\fR" 4 .IX Item "faxrm" Kills the job. .IP "\fBjobid\fR" 4 .IX Item "jobid" Returns the \s-1ID\s0 assigned to the job by the server. .SH "METHODS AND ATTRIBUTES OF Client::Instant OBJECTS ONLY" .IX Header "METHODS AND ATTRIBUTES OF Client::Instant OBJECTS ONLY" .IP "\fBcontent\fR" 4 .IX Item "content" Returns content returned by the server. .SH "GLOBAL VARIABLES" .IX Header "GLOBAL VARIABLES" .IP "\fB\f(CB$Fax::Hylafax::Client::Host\fB\fR" 4 .IX Item "$Fax::Hylafax::Client::Host" Specifies hostname of the server. Used in place of \*(L"host\*(R" attribute. .IP "\fB\f(CB$Fax::Hylafax::Client::Port\fB\fR" 4 .IX Item "$Fax::Hylafax::Client::Port" Specifies connection port of the server. Used in place of \*(L"port\*(R" attribute. .IP "\fB\f(CB$Fax::Hylafax::Client::User\fB\fR" 4 .IX Item "$Fax::Hylafax::Client::User" Username of the client. Used in place of \*(L"user\*(R" attribute. .IP "\fB\f(CB$Fax::Hylafax::Client::Password\fB\fR" 4 .IX Item "$Fax::Hylafax::Client::Password" Password of the client. Used in place of \*(L"password\*(R" attribute. .IP "\fB\f(CB$Fax::Hylafax::Client::Passive\fB\fR" 4 .IX Item "$Fax::Hylafax::Client::Passive" Specifies if \s-1PASSIVE\s0 connections should be used. Used in place of \*(L"passive\*(R" attribute. .IP "\fB\f(CB$Fax::Hylafax::Client::NotifyAddr\fB\fR" 4 .IX Item "$Fax::Hylafax::Client::NotifyAddr" E\-mail address where server notifications will be sent. Used in place of \*(L"notifyaddr\*(R" attribute. .SH "EXAMPLES" .IX Header "EXAMPLES" Send a fax .PP .Vb 1 \& use Fax::Hylafax::Client qw(sendfax); \& \& my $fax = sendfax( \& host => \*(Aqremote.host.name\*(Aq, \& dialstring => \*(Aq14151234567\*(Aq, \& docfile => \*(Aq/usr/home/test/document.ps\*(Aq, \& coverfile => \*(Aq/usr/home/test/cover.ps\*(Aq, \& notifyaddr => \*(Aqtest@user.com\*(Aq, \& ); \& \& if ($fax\->success) \& { \& print "We are OK"; \& } \& else \& { \& print $fax\->trace; \& } .Ve .PP Misc. examples .PP .Vb 1 \& use Fax::Hylafax::Client qw(sendfax sendpage faxstat faxinfo faxrm); \& \& $Fax::Hylafax::Client::Host = \*(Aqremote.server.hostname\*(Aq; \& $Fax::Hylafax::Client::User = \*(Aqfaxuser\*(Aq; \& $Fax::Hylafax::Client::Password = \*(Aq*password*\*(Aq; \& $Fax::Hylafax::Client::NotifyAddr = \*(Aqclient@address.com\*(Aq; \& \& my $fax = sendfax( \& dialstring => \*(Aq14151234567\*(Aq, \& docfile => [ \& \*(Aq/usr/home/test/document1.ps\*(Aq, \& \*(Aq/usr/home/test/document2.ps\*(Aq, \& ], \& ); \& \& my $task_succeded = $fax\->success ? "YES" : "NO"; \& my $server_responses = $fax\->trace; \& my $job_id = $fax\->jobid; \& my $current_job_status = $fax\->faxinfo; \& \& my $server_stats = faxstat( info => 1, active => 1 )\->content; \& if (faxinfo($job_id)\->content ne \*(AqDONE\*(Aq) \& { \& print "We\*(Aqre not done yet"; \& \& $fax\->faxrm; \& \& # or \& \& faxrm($job_id); \& \& # or \& \& my $task = faxrm( \& host => \*(Aqremote.server.hostname\*(Aq, \& user => \*(Aqfaxuser\*(Aq, \& password => \*(Aq*password*\*(Aq, \& jobid => $job_id, \& ); \& print $task\->success ? "We killed it!" : "Server didn\*(Aqt like it: " . $task\->trace; \& } \& \& my $other_server_task = faxstats( host => \*(Aqother.server.host\*(Aq, user => \*(Aqbob\*(Aq, password => \*(Aqwhatever\*(Aq ); \& if ($other_server_task\->success) \& { \& print $other_server_task\->content; \& } \& else \& { \& print "Doh! We failed to get stats from the server: ", $other_server_task\->trace; \& } \& \& my $page = sendpage( \& pin => \*(Aqbob\*(Aq, \& message => \*(AqTime to wake up\*(Aq, \& ); \& my $task_succeded = $page\->success ? "YES" : "NO"; .Ve .SH "AUTHOR" .IX Header "AUTHOR" Alex Rak \fBarak@cpan.org\fR .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2003,2006 Alex Rak. All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" HylaFAX man pages