Provided by: libfax-hylafax-client-perl_1.02-3_all bug

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:

           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 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, TIFF Class F, or PDF.
               [REQUIRED unless you use "poll" option]

           coverfile
               Full pathname of the cover page file. All notes about "docfile" apply, except it
               only takes one filename as scalar. [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. 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/>