NAME
   Magrathea::API - Easier access to the Magrathea NTS API

 VERSION
   Version 1.5.1

 SYNOPSIS
       use Magrathea::API;
       my $mt = new Magrathea::API;
       my $number = $mt->allocate('01792');
       $mt->deactivate($number);
       my @list = $mt->list('01792');
       my @numbers = $mt->block_allocate('01792', 10);
       $mt->fax2email($numbers[2], '[email protected]');
       $mt->divert($number[3], '+5716027171');
       $emerg = $mt->emergency_info;

 DESCRIPTION
   This module implements most of the Magrathea NTS API
   <https://www.magrathea-telecom.co.uk/assets/Client-Downloads/Numbering-A
   PI-Instructions.pdf> in a simple format.

 EXPORT
   Nothing Exported.

 MAIN API METHODS
 Constructor
  new
   This will create a new Magrathea object and open at telnet session to
   the server. If authorisation fails, it will croak.

       my $mt = new Magrathea::API(
           username    => 'myuser',
           password    => 'mypass',
       );

  Parameters:
   username
   password
       The username and password allocated by Magrathea.

   host
       Defaults to *api.magrathea-telecom.co.uk* but could be overridden.

   port
       Defaults to *777*.

   timeout
       In seconds. Defaults to *10*.

   debug
       If set to a true value, this will output the conversation between
       the API and Magrathea's server. Be careful as this will also echo
       the username and password.

 Allocation Methods
   In all cases where $number is passed, this may be a string containing a
   number in National format (*020 1234 5678*) or in International format
   (*+44 20 1234 5678*). Spaces are ignored. Also, Phone::Number objects
   may be passed.

   When a number is returned, it will always be in the for of a
   Phone::Number object.

  allocate
   Passed a prefix, this will allocate and activate a number. You do not
   need to add the "_" characters. If a number can be found, this routine
   will return a Phone::Number object. If no match is found, this routine
   will return "undef". It will croak on any other error from Magrathea.

  deactivate
   Passed a number as a string or a Phone::Number, this deactivates the
   number.

  reactivate
   Reactivates a number that has previously been deactivated.

  list
   This should be passed a prefix and possibly a quantity (defaulting to
   10. It will return a sorted random list of available numbers matching
   the prefix. These are returned as an array (or an arrayref) of
   Phone::Number. None of the numbers is allocated by this method.

   If none are available, the method will return an empty array.

 Block Methods
  block_allocate
   This should be passed a prefix (without any "_" characters) and an
   optional block size (defaulting to 10). It will attempt to allocate and
   activate a block of numbers.

   If a block can be found, this routine should return an array or arrayref
   of Phone::Number objects. Under odd circumstances, it is possible that
   fewer than the requested quantity of numbers will be returned;

   If no range is found is found, this routine will return "undef" in
   scalar context or an empty array in list context. It will croak on any
   other error from Magrathea.

  block_info
   This should be passed a number (string or Phone::Number) to check
   whether that number is part of a block.

   If it is, the size of the block will be returned in scalar context; In
   list context, the response will be an array of all the numbers in that
   block.

   If it is not a block, this will return "undef" or an empty array.

  block_deactivate
   This should be passed the first number in a block. It will deactivate
   and return the block of numbers.

  block_reactivate
   This should be passed the first number in a block. It will reactivate
   the block and return the size of the block in scalar context or an array
   of the numbers in list context.

   If the block is not available, this method will croak.

   In testing, this method has never worked correctly.

 Service Methods
  fax2email
   Sets a number as a fax to email.

       $mt->fax2email($number, $email_address);

  voice2email
   Sets a number as a voice to email.

       $mt->voice2email($number, $email_address);

  sip
       $mt->sip($number, $host, [$username, [$inband]]);

   Passed a number and a host, will set an inbound sip link to the
   international number (minus leading +) @ the host. If username is
   defined, it will be used instead of the number. If inband is true, it
   will force inband DTMF. The default is RFC2833 DTMF.

  divert
       $mt->divert($number, $to_number);

  status
   Returns the status for a given number.

       my $status = $mt->status($number);
       my @status = $mt->status($number);

   In scalar context, returns the first (and usually only) status as a
   Magrathea::API::Status object. In list context, returns up to three
   statuses representing the three possible setups created with ORDE.

   If the number is not allocated to us and activated, this routine returns
   "undef" in scalar context and an empty list in list context.

   The Magrathea::API::Status object has the following calls:

   "$status->number"
       A Phone::Number object representing the number to which this status
       refers.

   "$status->active"
       Boolean.

   "$status->expiry"
       The date this number expires in the form "YYYY-MM-DD".

   "$status->type"
       One of sip, fax2email, voice2email, divert or unallocated.

   "$status->target"
       The target email or phone number for this number;

   "$status->entry"
       The entry number (1, 2 or 3) for this status;

   In addition, it overloads '""' to provide as tring comprising the type
   and the target, separated by a space.

 Emergency Methods
  emergency_info
   Passed a phone number, this method returns a Magrathea::API::Emergency
   object with the current 999 information.

   Optionally it can be passed a second parameter which, if it is a truthy
   value, will set the "ported" flag.

 Low Level Methods
   All the Magrathea low level calls are available. These are simply passed
   an array of strings which are joined to create the command string. They
   return the raw response on success (minus the leading 0) and die on
   failure. $@ will contain the error.

   See the Magrathea documentation
   <http://www.magrathea-telecom.co.uk/assets/Client-Downloads/Numbering-AP
   I-Instructions.pdf>.

   The functions are:

   auth
       This is called by "new" and should not be called directly.

           $mt->auth('username', 'password');

   quit
       This is called automatically upon the Magrathea::API object going
       out of scope and should not be called directly.

   allo
           $mt->allo('0201235___');

   acti
           $mt->acti('02012345678');

   deac
           $mt->deac('02012345678');

   reac
           $mt->reac('02012345678');

   stat
           $mt->stat('02012345678');

   set
           $mt->set('02012345678 1 441189999999');
           $mt->set('02012345678 1 F:[email protected]');
           $mt->set('02012345678 1 V:[email protected]');
           $mt->set('02012345678 1 S:[email protected]');
           $mt->set('02012345678 1 I:username:[email protected]');

   spin
           $mt->set('02012345678 [pin]');

   feat
           $mt->feat('02012345678 D');
           $mt->feat('02012345678 J');

   orde
           $mt->orde('02012345678 1 0000');

   info
           $mt->info('02012345678 GEN Magrathea, 14 Shute End, RG40 1BJ');

   It will not usually be necessary to call these functions directly.

 AUTHOR
   Cliff Stanford, <[email protected]>

 ISSUES
   Please open any issues with this code on the Github Issues Page
   <https://github.com/CliffS/magrathea-api/issues>.

 COPYRIGHT AND LICENCE
   Copyright (C) 2012 - 2018 by Cliff Stanford

   This library is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself, either Perl version 5.10.1 or, at
   your option, any later version of Perl 5 you may have available.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.