NAME Net::Magrathea - Perl interface to the Magrathea Telecom NTS API VERSION This document describes Net::Magrathea version 0.02 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 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 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 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 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. 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 . AUTHOR Gavin Henry "" LICENCE AND COPYRIGHT Copyright (C) 2009, Suretec Systems Ltd. Copyright (c) 2009, Gavin Henry . 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.