NAME

FTN::Outbound::BSO - Object-oriented module for working with BinkleyTerm Style Outbound.

VERSION

version 20160516

SYNOPSIS

  use Log::Log4perl ();
  use Encode ();
  use FTN::Outbound::BSO ();

  Log::Log4perl -> easy_init( $Log::Log4perl::INFO );

  my $bso = FTN::Outbound::BSO -> new( outbound_root => '/var/lib/ftn/outbound',
                                       domain => 'fidonet',
                                       zone => 2,
                                       domain_abbrev => { fidonet => '_out',
                                                          homenet => 'leftnet',
                                                        },
                                       maximum_session_time => 3600, # one hour
                                     ) or die 'cannot create bso object';

  my $addr = FTN::Addr -> new( '2:451/30' );

  sub poll {
    my $addr = shift;
    my $bso = shift;

    my $flo = $bso -> addr_file_to_change( $addr,
                                           'reference_file',
                                           'normal'
                                         );

    open my $fh, '>>', $flo
      or die sprintf 'cannot open %s: %s', $flo, $!;

    print $fh '';

    close $fh;
  }

  $bso -> busy_protected_sub( $addr,
                              \ &poll,
                            );

DESCRIPTION

FTN::Outbound::BSO module is for working with BinkleyTerm Style Outbound in FTN following specifications from fts-5005.002 document. Figuring out correct file to process might be a tricky process: different casing, few our main domains, other differences. This module helps with this task.

OBJECT CREATION

new

Expects parameters as hash:

  outbound_root - directory path as a character string where whole outbound is located.  Mandatory parameter.  This directory should exist.

By standard constructor needs our domain and zone. They can be provided as:

  our_addr - either FTN::Addr object representing our address or our address as a string which will be passed to FTN::Addr constructor.

or as a pair:

  domain - domain part of our address as described in frl-1028.002.
  zone - our zone in that domain

At least one of the ways should be provided. In case both are our_addr has higher priority.

  domain_abbrev - hash reference where keys are known domains and values are directory names (without extension) in outbound_root for those domains.  Mandatory parameter.

  reference_file_read_line_transform_sub - reference to a function that receives an octet string and returns a character string.  Will be passed to FTN::Outbound::Reference_file constructor.  If not provided reference file content won't be processed.

  maximum_session_time - maximum session time in seconds.  If provided, all found busy files older than 2 * value will be removed during outbound scan.

Returns newly created object on success.

OBJECT METHODS

scan

Scans outbound for all known domains. Old busy files might be removed.

Returns itself for chaining.

scanned_hash

Returns internal structure representing scanned outbound (hash in list context, hashref in scalar context). If scan method hasn't been called, it will be called implicitly by this method.

is_busy

Expects one parameter - address as FTN::Addr object. Returns true if that address is busy (connection session, mail processing, ...).

busy_protected_sub

Expects two parameters:

  address going to be dealt with as a FTN::Addr object

  function reference that will receive passed address and us ($self) as parameters and which should do all required operations related to the passed address.

This method infinitely waits (most likely will be changed in the future) until address is not busy. Then it creates busy flag and calls passed function reference providing itself as an argument for it. After function return removes created busy flag.

Returns itself for chaining.

addr_file_to_change

Expects arguments:

  address going to be dealt with as a FTN::Addr object

  file type as one of netmail, reference_file, file_request, busy, call, hold, try.

  If file type is netmail or reference_file, then next parameter should be its flavour: immediate, crash, direct, normal, hold.

  If optional function reference passed, then it will be called with one parameter - name of the file to process.  After that information in internal structure about that file will be updated.

Does not deal with busy flag implicitly. Recommended usage is in the function passed to busy_protected_sub.

Returns full name of the file to process (might not exists though).

cpanm FTN::Outbound::BSO

perl -MCPAN -e shell
install FTN::Outbound::BSO