Client(3pm)

📦
version 1.02 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

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

okay bestie, pull up a chair, because we're about to talk about Fax::Hylafax::Client, and honestly? it's giving iconic. 🎀

✨ NAME ✨

Fax::Hylafax::Client — a Simple HylaFAX client. yes, that's literally the whole name. short. sweet. slay. 💅

🌸 SYNOPSIS 🌸

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

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

🦋 DESCRIPTION 🦋

so this is a simple Perl client for the HylaFAX fax server (www.hylafax.org). 🫶

here's the part that lowkey makes it the main character: it talks to the server directly through an FTP-like protocol, which means you do not need any HylaFAX software components installed on the client machine. none. zero. nada. it just shows up and does the thing. ✨

👑 MAIN METHODS AND ATTRIBUTES 👑

sendfax 💌

this method sends a fax job to the server. it returns a Client::Queued object. 🎉

it 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. ⚠️ (fr fr, don't get it twisted)
  • 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 ✨

Okay bestie, this is the part where it all comes together. Real code, real vibes. 🎀

Sending 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;
}

See how we just... call it? Iconic. Send the fax, check success, and if it's giving failure energy, dump trace so you can see what the server was actually saying. 🦋

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";

Bestie, let's break this down because there's a LOT happening and it's all delicious. 💅

  • First we set the global variables — $Fax::Hylafax::Client::Host, $Fax::Hylafax::Client::User, $Fax::Hylafax::Client::Password, and $Fax::Hylafax::Client::NotifyAddr — so every call after that just inherits them. No cap, it's a whole mood. 🌸
  • Then sendfax with dialstring and a docfile that's an arrayref of two documents. Multiple files, one job. We love efficiency. ✨
  • $fax->success gives you a yes/no, $fax->trace gives you the server's receipts, $fax->jobid gives you the job id, and $fax->faxinfo gives you the current job status. 🫶
  • faxstat( info => 1, active => 1 )->content pulls the server stats, and if faxinfo($job_id)->content isn't 'DONE', we're still waiting — so we bail out with faxrm. Three flavours of removal are shown: the method $fax->faxrm, the plain faxrm($job_id), and the fully-loaded faxrm( host => ..., user => ..., password => ..., jobid => ... ). Pick your fighter. 🔥
  • Then faxstats (note the plural — it's in the example exactly like this, we don't editorialize 😭) hits a totally different server with its own host, user, and password, and prints content on success or the trace on failure.
  • Finally sendpage with a pin and a message, and we check success again. Time to wake up, bob. 🍓
Heads up bestie: the example uses $task_succeded (with an e in the middle) and calls faxstats — that's how it appears in the original, so copy it as-is if you're copy-pasting. 💀

👑 AUTHOR 👑

Alex Rak arak@cpan.org

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 🌈

And that's the whole page, bestie — go forth and fax. 🦋✨

This one's from perl v5.26.2, dated 2018-08-20 — so it's giving vintage, but the fax energy is timeless. Periodt. 💜

📦 where this page comes from