NAME

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

VERSION

Version 1.6.0

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 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.

activate

Passed a number as a string or a Phone::Number, this will activate that number.

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.

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.

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.