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-like 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:

sendpage

Sends SNPP page job to the server. Returns "Client::Queued" object. Takes a hash of the following attributes:

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:

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:

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. Useful 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/document1.ps',
                              '/usr/home/test/document2.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,2006 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/>