Client(3pm)						User Contributed Perl Documentation					       Client(3pm)

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. Docu-
	       ment 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 ver-
	       sion, 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/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/>

perl v5.8.8							    2008-03-02							       Client(3pm)