lib/Net/GlobalPOPs/MediaServicesAPI.pm

   1 package Net::GlobalPOPs::MediaServicesAPI;
   2
   3 use warnings;
   4 use strict;
   5 use Data::Dumper;
   6 use XML::Simple;
   7 use XML::Writer;
   8 use Net::HTTPS::Any qw(https_post);
   9
  10 =head1 NAME
  11
  12 Net::GlobalPOPs::MediaServicesAPI - Interface to GlobalPOPs Media Services API
  13
  14 =head1 VERSION
  15
  16 Version 0.01
  17
  18 =cut
  19
  20 our $VERSION = '0.01';
  21 our $URL     = 'https://www.loginto.us/VOIP/api.pl';
  22 #could be parsed from URL, if it mattered...
  23 our $HOST    = 'www.loginto.us';
  24 our $PATH    = '/VOIP/api.pl';
  25
  26 our $AUTOLOAD;
  27 our $errstr = '';
  28
  29 =head1 SYNOPSIS
  30
  31     use Net::GlobalPOPs::MediaServicesAPI;
  32
  33     my $handle = Net::GlobalPOPs::MediaServicesAPI->new(
  34         'login'    => 'tofu',
  35         'password' => 'beast',
  36         'debug'    => 1,
  37     );
  38
  39     #DID functions
  40     #auditDIDs
  41     #queryDID
  42     #reserveDID
  43     #assignDID
  44     #configDID
  45     #releaseDID
  46
  47     #911 Functions
  48
  49     #Locator Functions
  50
  51     ...
  52
  53 =head1 METHODS
  54
  55 =head2 new HASHREF | OPTION, VALUE ...
  56
  57 Creates a new Net::GlobalPOPs::MediaServicesAPI object.  Options may be passed
  58 as a hash reference or a flat list of names and values.
  59
  60 =over 4
  61
  62 =item login (required)
  63
  64 =item password (required)
  65
  66 =item login (required)
  67
  68 =back
  69
  70 =cut
  71
  72 #  If there is an error,
  73 #returns false and sets an error string which may be queried with the I<errstr>
  74 #class method.
  75
  76 sub new {
  77   my $proto = shift;
  78   my $class = ref($proto) || $proto;
  79   my $self = ref($_[0]) ? shift : { @_ };
  80   bless($self, $class);
  81 }
  82
  83 =head2 errstr
  84
  85 =cut
  86
  87 sub errstr {
  88   my $class = shift;
  89
  90   return $errstr
  91     unless ref($class) && $class->isa('Net::GlobalPOPs::MediaServicesAPI');
  92
  93   my $self = $class;
  94   $self->{errstr};
  95 }
  96
  97 sub DESTROY { }; # no-op
  98
  99 sub AUTOLOAD {
 100   my $self = shift;
 101   my $opts = ref($_[0]) ? shift : { @_ };
 102
 103   $AUTOLOAD =~ /(^|::)(\w+)$/ or die "unparsable AUTOLOAD: $AUTOLOAD";
 104   my $function = $2;
 105
 106   my $output;
 107   my $w = new XML::Writer(OUTPUT => \$output, DATA_MODE => 1, DATA_INDENT => 3);
 108
 109   $w->xmlDecl('ISO-8859-1');
 110   $w->doctype('request', undef, $URL);
 111
 112   $w->startTag('request', 'id' => '');  #XXX request ID???
 113     $w->startTag('header');
 114       $w->startTag('sender');
 115
 116         if ( $self->{'sessionid'} ) {
 117
 118           #$w->dataElement( 'login'     => ''                   );
 119           #$w->dataElement( 'password'  => ''                   );
 120           $w->dataElement( 'sessionid' => $self->{'sessionid'} );
 121
 122         } else {
 123
 124           $w->dataElement( 'login'     => $self->{'login'}     );
 125           $w->dataElement( 'password'  => $self->{'password'}  );
 126           #$w->dataElement( 'sessionid' => ''                   );
 127
 128         }
 129
 130       $w->endTag('sender');
 131     $w->endTag('header');
 132
 133     $w->startTag('body');
 134
 135       $w->dataElement( 'requesttype' => $function );
 136
 137       if ( keys %$opts ) {
 138         $w->startTag('item');
 139           foreach my $opt ( keys %$opts ) {
 140             $w->dataElement( $opt => $opts->{$opt} );
 141           }
 142         $w->endTag('item');
 143       }
 144
 145     $w->endTag('body');
 146
 147   $w->endTag('request');
 148
 149   #$output =~ s/\n+/\n/g;
 150
 151   warn "XML Request for $function function:\n$output"
 152     if $self->{'debug'};
 153
 154   my( $page, $response, %reply_headers ) = https_post(
 155     'host'         => $HOST,
 156     'path'         => $PATH,
 157     'args'         => { 'apidata' => $output, },
 158     #'content'      => $output,
 159     #'Content-Type' => 'text/plain',
 160     #'Content-Type' => 'text/xml',
 161     #'Content-Type' => 'application/xml',
 162     #'headers' => {},
 163     'debug'        => $self->{'debug'},
 164   );
 165
 166   unless ( $response =~ /^HTTP\/[\d\.]+\s+200/i ) {
 167     $self->{'errstr'} = $response;
 168     return '';
 169   }
 170
 171   warn "XML Response for $function function:\n: $page"
 172     if $self->{'debug'};
 173
 174   my $hashref = XMLin( $page );
 175
 176   warn "Parsed response for $function funtion:\n". Dumper($hashref)
 177     if $self->{'debug'};
 178
 179   my $return = $hashref->{'body'};
 180
 181   warn "Returning data:\n". Dumper($return)
 182     if $self->{'debug'};
 183
 184   $return;
 185
 186 }
 187
 188 =head1 AUTHOR
 189
 190 Ivan Kohler, C<< <ivan-net-globalpops at freeside.biz> >>
 191
 192 =head1 BUGS
 193
 194 Please report any bugs or feature requests to C<bug-net-globalpops-mediaservicesapi at rt.cpan.org>, or through
 195 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-GlobalPOPs-MediaServicesAPI>.  I will be notified, and then you'll
 196 automatically be notified of progress on your bug as I make changes.
 197
 198
 199
 200
 201 =head1 SUPPORT
 202
 203 You can find documentation for this module with the perldoc command.
 204
 205     perldoc Net::GlobalPOPs::MediaServicesAPI
 206
 207
 208 You can also look for information at:
 209
 210 =over 4
 211
 212 =item * RT: CPAN's request tracker
 213
 214 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-GlobalPOPs-MediaServicesAPI>
 215
 216 =item * AnnoCPAN: Annotated CPAN documentation
 217
 218 L<http://annocpan.org/dist/Net-GlobalPOPs-MediaServicesAPI>
 219
 220 =item * CPAN Ratings
 221
 222 L<http://cpanratings.perl.org/d/Net-GlobalPOPs-MediaServicesAPI>
 223
 224 =item * Search CPAN
 225
 226 L<http://search.cpan.org/dist/Net-GlobalPOPs-MediaServicesAPI>
 227
 228 =back
 229
 230
 231 =head1 ACKNOWLEDGEMENTS
 232
 233
 234 =head1 COPYRIGHT & LICENSE
 235
 236 Copyright 2008 Freeside Internet Services, Inc. (http://freeside.biz/)
 237
 238 This program is free software; you can redistribute it and/or modify it
 239 under the same terms as Perl itself.
 240
 241
 242 =head1 ADVERTISEMENT
 243
 244 Open-source billing, trouble ticketing and automation for VoIP providers:
 245
 246 http://freeside.biz/freeside/
 247
 248 =cut
 249
 250 1; # End of Net::GlobalPOPs::MediaServicesAPI