man Fax::Hylafax::Client () - Simple HylaFAX client

NAME

Fax::Hylafax::Client - Simple HylaFAX client

SYNOPSIS

     use Fax::Hylafax::Client qw(sendfax);

     my $fax = sendfax(
          dialstring    => '5555555555',
          docfile       => '/usr/home/test/document.ps',
     );

DESCRIPTION

This is a simple Perl client for HylaFAX fax server (www.hylafax.org). It communicates with the server directly through FTP protocol and thus does not require any HylaFAX software components to be installed on the client machine.

MAIN METHODS AND ATTRIBUTES

sendfax
This method sends a fax job to the server. Returns Client::Queued object. Takes a hash of the following attributes:
host
Hostname of the server. Defaults to localhost. [OPTIONAL]
port
Connection port of the server. Defaults to 4559. [OPTIONAL]
user
Username of the client. Defaults to anonymous. [MAY BE REQUIRED]
password
Password of the client. Defaults to anonymous. [MAY BE REQUIRED]
dialstring
Destination string (number) to dial. [REQUIRED]
docfile
Full pathname of the main (document) file. Document file must be in one of the native HylaFAX formats, i.e. Plain Text, PostScript, TIFF Class F, or PDF. [REQUIRED unless you use poll option]
coverfile
Full pathname of the cover page file. All notes about docfile apply. [OPTIONAL]
notifyaddr
E-mail address of the person to be notified about the status of the job. Defaults to user@hostname. [OPTIONAL]
notify
Controls the email notification messages from the server. Possible values: none - notify if error only, done - notify when done, requeue - notify if job is re-queued, done+requeue. Defaults to none. [OPTIONAL]
passive
If set to 1 connects to server in PASSIVE mode. Defaults to 0. [OPTIONAL]
sendtime
Time when the fax should be sent. Possible values: now or date in format YYYYMMDDHHMM. It looks like 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]
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 3. [OPTIONAL]
schedpri
The scheduling priority to assign to the job. Defaults to 127 (Normal). [OPTIONAL]
poll
Try to poll a fax from remote machine. Value can be an empty string or selector [passwd]. [OPTIONAL]
sendpage
Sends SNPP page job to the server. Returns Client::Queued object. Takes a hash of the following attributes:
host
Same as in sendfax.
port
Connection port of the server. Defaults to 444. [OPTIONAL]
user
Same as in sendfax.
password
Same as in sendfax.
pin
Pager Identification Number as defined in pagermap file on the server. [REQUIRED]
message
Text message to be sent (alfa-numeric pagers only). [OPTIONAL]
notifyaddr
Same as in sendfax.
notify
Same as in sendfax.
passive
Same as in sendfax.
maxdials
Same as in sendfax.
maxtries
Same as in sendfax.
level
Priority level to assign to the job. Values can be 0-7 (0 being the highest). Defaults to 1 (Normal). [OPTIONAL]
faxinfo
Request the status of a particular job. Returns Client::Instant object. Can take only the number of the job as an attribute or a hash of the following attributes:
host
Same as in sendfax.
port
Same as in sendfax.
user
Same as in sendfax.
password
Same as in sendfax.
jobid
ID of the job. [REQUIRED]
passive
Same as in sendfax.
faxrm
Remove job from the server (kill it). Returns Client::Instant object. Behaves like and has the same attributes as faxinfo.
faxstat
Request statistics from the server. Returns Client::Instant object. Takes a hash of the following attributes:
host
Same as in sendfax.
port
Same as in sendfax.
user
Same as in sendfax.
password
Same as in sendfax.
passive
Same as in sendfax.
info
If set to 1 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 0. [OPTIONAL]
files
If set to 1 displays the status of document files located in the docq directory on the server machine. The filefmt attribute defines the content and format of information reported with this option. Defaults to 0. [OPTIONAL]
queue
If set to 1 displays the status of jobs in the send queue on the server machine. The jobjmt attribute defines the content and format of information reported with this option. Defaults to 0. [OPTIONAL]
done
If set to 1 displays the status of all jobs that have completed; i.e. those jobs located in the doneq directory on the server machine. The jobfmt attribute defines the content and format of information reported with this option. Defaults to 0. [OPTIONAL]
received
If set to 1 displays the receive queue status. The rcvfmt attribute defines the content and format of information reported with this option. Defaults to 0. [OPTIONAL]
filefmt
The format string to use when returning file status information. See faxstat man pages for details. [OPTIONAL]
jobfmt
The format string to use when returning job status information. See faxstat man pages for details. [OPTIONAL]
rcvfmt
The format string to use when returning status information about received jobs. See faxstat man pages for details. [OPTIONAL]

METHODS AND ATTRIBUTES OF ALL Client::* OBJECTS

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 faxinfo to check for that.
trace
Returns responses from the last communication with the server. Userful for debugging.

METHODS AND ATTRIBUTES OF Client::Queued OBJECTS ONLY

faxinfo
Returns the status of the job at this particular moment.
faxrm
Kills the job.
jobid
Returns the ID assigned to the job by the server.

METHODS AND ATTRIBUTES OF Client::Instant OBJECTS ONLY

content
Returns content returned by the server.

GLOBAL VARIABLES

$Fax::Hylafax::Client::Host
Specifies hostname of the server. Used in place of host attribute.
$Fax::Hylafax::Client::Port
Specifies connection port of the server. Used in place of port attribute.
$Fax::Hylafax::Client::User
Username of the client. Used in place of user attribute.
$Fax::Hylafax::Client::Password
Password of the client. Used in place of password attribute.
$Fax::Hylafax::Client::Passive
Specifies if PASSIVE connections should be used. Used in place of passive attribute.
$Fax::Hylafax::Client::NotifyAddr
E-mail address where server notifications will be sent. Used in place of notifyaddr attribute.

EXAMPLES

Send a fax

     use Fax::Hylafax::Client qw(sendfax);

     my $fax = sendfax(
          host          => 'remote.host.name',
          dialstring    => '14151234567',
          docfile       => '/usr/home/test/document.ps',
          coverfile     => '/usr/home/test/cover.ps',
          notifyaddr    => 'test@user.com',
     );

     if ($fax->success){
          print "We are OK";
     } else {
          print $fax->trace;
     }

Misc. examples

     use Fax::Hylafax::Client qw(sendfax sendpage faxstat faxinfo faxrm);

     $Fax::Hylafax::Client::Host       = 'remote.server.hostname';
     $Fax::Hylafax::Client::User       = 'faxuser';
     $Fax::Hylafax::Client::Password   = '*password*';
     $Fax::Hylafax::Client::NotifyAddr = 'client@address.com';

     my $fax = sendfax(
          dialstring    => '14151234567',
          docfile       => '/usr/home/test/document.ps',
     );

     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 'DONE'){
          print "We're not done yet";

          $fax->faxrm;

          #   or

          faxrm($job_id);

          #   or

          my $task = faxrm(
                host     => 'remote.server.hostname',
                user     => 'faxuser',
                password => '*password*',
                jobid    => $job_id,
          );
          print $task->success ? "We killed it!" : "Server didn't like it: " . $task->trace;
     }

     my $other_server_task = faxstats( host => 'other.server.host', user => 'bob', password => 'whatever' );
     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      => 'bob',
          message  => 'Time to wake up',
     );
     my $task_succeded = $page->success ? "YES" : "NO";

AUTHOR

Alex Rak arak@cpan.org

COPYRIGHT

Copyright (c) 2003 Alex Rak. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

HylaFAX man pages <http://www.hylafax.org/man/>