NAME

Net::Magrathea - Perl interface to the Magrathea Telecom NTS API

VERSION

This document describes Net::Magrathea version 0.03

SYNOPSIS

  use strict;
  use warnings;
  use Net::Magrathea;
  
  my $ntsapi = Net::Magrathea->new(
      username => 'user',
      password => 'pass',
      debug    => 1,
  );
  
  my $index = 1;
  my $dest  = 'S:01224279484@sip.surevoip.co.uk';
  
  my $number = $ntsapi->allocate('01224______');
  
  $ntsapi->activate($number) if $ntsapi->success;
  
  $ntsapi->set( $number, $index, $dest ) if $ntsapi->success;
  
  $ntsapi->status($number) if $ntsapi->success;
  
  $ntsapi->user_info(
      $number, 'Suretec Systems Ltd., 24 Cormack Park,
      Rothienorman, Inverurie, AB51 8GL.'
  ) if $ntsapi->success;
  
  $ntsapi->deactivate($number) if $ntsapi->success;
  $ntsapi->quit;

DESCRIPTION

This module provides a Perl interface allowing you to connect to and operate the Magrathea Telecom 'Number Translation Service' API.

INTERFACE

quit

Terminates the session. Should be called after the final command.

$ntsapi->quit;

allocate

Attempt to allocate a phone number. The <number> can either be an entire number, or may include underscores, to indicate any digit is acceptable. This is the only command that accepts underscores as part of the <number> parameter (now allocate_ten also accepts underscores).

NOTE: This command does NOT reserve the number – you must issue an immediate activate command to ensure the number is allocated to your account and not available for allocation by others.

$ntsapi->allocate('01224______');

Returns an allocated number.

activate

Activates a number obtained using the allocate command. This command must be used to finalise the reservation process.

$ntsapi->allocate($number);

Result available via

my $message = $ntsapi->result;

deactivate

Deactivate the specified number. The number will no longer operate when dialled.

The exact number must be entered; underscores are not permitted when using this command.

NOTE: If you deactivate a number it becomes available for others to allocate, so it cannot be guaranteed that you will be able to retrieve the number at a later date

$ntsapi->deactivate($number);

Result available via

my $message = $ntsapi->result;

reactivate

Reactivates a number that has previously been deactivated using the DEAC command (if it has not since been allocated by someone else).

$ntsapi->reactivate($number);

Result available via

my $message = $ntsapi->result;

status

Query the current status of the specified number. A successful reply contains the information about the number’s current settings.

$ntsapi->status($number);

Result available via

my $message = $ntsapi->result;

set

This command sets up destination for when the number is dialled.

my $index = 1;
my $dest  = 'S:01224279484@sip.surevoip.co.uk';

$ntsapi->set( $number, $index, $dest ) if $ntsapi->success;

See the full NTS API docs for complete information (more than two pages).

user_info

This command has been added to enable storage of information about the user of the number.

$ntsapi->user_info(
    $number, 'Suretec Systems Ltd., 24 Cormack Park, Rothienorman, 
              Inverurie, AB51 8GL.'
    if $ntsapi->success;

feature

The FEAT command can be used to check, enable or disable a particular feature for an account.

NOTE: Not supported yet.

secure_pin

Set a PIN for the number.

NOTE: Not supported yet.

time_of_day_route

This command sets the destination usage by time of day, allowing (for advanced NTS only) multiple targets to be setup and configuration when each target is active.

NOTE: Not supported yet.

allocate_ten

This command has been provided to help locate ranges of ten numbers that are available for allocation. The syntax of the <number> parameter is identical to that of ALLO and the system will attempt to find a range of ten numbers (0 through to 9) that matches the passed <number> format.

NOTE: Not supported yet.

ported_numbers

NOTE: Not supported yet.

Control numbers that have been ported to Magrathea, if your NTSAPI account has been given permission to do so.

errormsg

Retrieve the last message from the NTS API

DIAGNOSTICS

The last message from the Magrathea session can be retrieved via

print $ntsapi->errormsg

If you have set $ntsapi->debug(1) the session messages will be printed via print

CONFIGURATION AND ENVIRONMENT

Net::Magrathea requires no configuration files or environment variables.

DEPENDENCIES

Moose

Net::Telnet

namespace::autoclean

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-net-magrathea@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Gavin Henry <ghenry@suretecsystems.com>

LICENCE AND COPYRIGHT

Copyright (C) 2009, Suretec Systems Ltd. <http://www.suretecsystems.com>

Copyright (c) 2009, Gavin Henry <ghenry@suretecsystems.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm Net::Magrathea

perl -MCPAN -e shell
install Net::Magrathea