lib/Net/Indosoft/Voicebridge.pm

   1 package Net::Indosoft::Voicebridge;
   2
   3 use warnings;
   4 use strict;
   5 use Data::Dumper;
   6 use SOAP::Lite;
   7
   8 our $AUTOLOAD;
   9 our $DEBUG = 1;
  10
  11 =head1 NAME
  12
  13 Net::Indosoft::Voicebridge - Interface to Indosoft Voicebridge API
  14
  15 =head1 VERSION
  16
  17 Version 0.01
  18
  19 =cut
  20
  21 our $VERSION = '0.01';
  22
  23 =head1 SYNOPSYS
  24
  25   use Net::Indosoft::Voicebridge;
  26
  27   my $handle = Net::GlobalPOPs::MediaServicesAPI->new(
  28     'url'    => 'http://your_tag.kanobe.net:8080/vbsoap/voicebridgeAPI.php',
  29   );
  30
  31 =head1 METHODS
  32
  33 =head2 new
  34
  35 Creates a new Net::Indosoft::Voicebridge object.
  36
  37 =cut
  38
  39 sub new {
  40   my $proto = shift;
  41   my $class = ref($proto) || $proto;
  42   my $self = ref($_[0]) ? shift : { @_ };
  43
  44 #  my $soap = new SOAP::Lite (
  45 #    'service' => $URL.'?wsdl',
  46 #  );
  47 #  $self->{soap} = $soap;
  48
  49   bless($self, $class);
  50 }
  51
  52 #ideally this could be retreived from the WSDL, but hey
  53 # or at least derived from the method name?
  54 our %requestobj = (
  55   'addAccount'       => 'Account',
  56   'modifyAccount'    => 'Account',
  57   'addClient'        => 'Client',
  58   'modifyClient'     => 'Client',
  59   'addConference'    => 'Conference',
  60   'modifyConference' => 'Conference',
  61 );
  62
  63 #this is think they're just on crack.  returnning a string to parse inside
  64 #a ton of XML?  somehow that misses the point.
  65 our %returnparse = (
  66   'addAccount'       => [ qw( account_id ) ],
  67   'modifyAccount'    => [ qw( account_id ) ],
  68   'addClient'        => [ qw( client_id  ) ],
  69   'modifyClient'     => [ qw( client_id  ) ],
  70   'addConference'    => [ qw( conference_id moderator_pin participant_pin ) ],
  71   'modifyConference' => [ qw( conference_id ) ],
  72 );
  73
  74 sub AUTOLOAD {
  75   my $self = shift;
  76
  77   $AUTOLOAD =~ /(^|::)(\w+)$/ or die "unparsable AUTOLOAD: $AUTOLOAD";
  78   my $function = $2;
  79   return if $function eq 'DESTROY';
  80
  81   my $uri = "voicebridgeAPI/$function";
  82
  83
  84   my $soap = SOAP::Lite
  85 #    -> readable(1)
  86     -> proxy($self->{url})
  87 #    -> on_action( sub { join '/', @_ } ) #according to the wsdl, right?
  88 #    -> on_action( sub { "urn:voicebridgeAPI/$function" } )
  89     -> autotype(0)
  90 #    -> default_ns("urn:voicebridgeAPI")
  91   ;
  92
  93   my $request;
  94   my $obj = $requestobj{$function};
  95   if ( $obj ) {
  96
  97     my $opts = ref($_[0]) ? shift : { @_ };
  98     if ( $DEBUG > 1 ) {
  99       warn "$_: ". $opts->{$_}. "\n" foreach keys %$opts;
 100     }
 101
 102     $request = SOAP::Data->name( $obj =>
 103       \SOAP::Data->value(
 104         map SOAP::Data->name( $_ )->value( $opts->{$_} ), keys %$opts
 105       )
 106     );
 107
 108   } else {
 109
 110     $request = shift;
 111
 112   }
 113
 114   my $som = $soap->call( $function, $request );
 115
 116   die $som->faultstring if $som->fault;
 117   return { 'error' => $som->faultdetail } if $som->fault;
 118
 119   warn Dumper($som->body) if $DEBUG > 1;
 120
 121   my $return = $som->valueof("//${function}Response/return");
 122
 123   if ( $return =~ /^<errors/i ) {
 124     my $rsom = SOAP::Deserializer->deserialize($return);
 125     my @errors = $rsom->valueof('//errors/error');
 126     return { 'error' => join(' / ', @errors ) } if @errors;
 127   }
 128
 129   if ( $function =~ /^delete/ && $return !~ /Deleted Success?fully/i ) {
 130     return { 'error'  => 'Deletion unsuccessful',
 131              'return' => $return,
 132            };
 133   }
 134
 135   my %return = ( 'return'=>$return );
 136   foreach my $rp ( @{ $returnparse{$function} || [] } ) {
 137                               #are they always numeric?
 138     $return =~ /\W$rp\s*=\s*(\d+)/ and $return{$rp} = $1;
 139   }
 140
 141   return \%return;
 142 }
 143
 144 =head2 addAccount
 145
 146 Pass a list of key=>value pairs or a hash reference:
 147
 148 i.account_name: Required Field: Alpha Numeric
 149 ii.account_desc: Alpha Numeric
 150 iii.account_addr: Alpha Numeric
 151 iv.account_city: Alpha Numeric
 152 v.account_state: Alpha Numeric
 153 vi.account_country: Alpha Numeric
 154 vii.account_zip: Alpha Numeric
 155 viii.account_phone: Required Field: Alpha Numeric Ex: 123-123-1234
 156 ix.account_fax: Alpha Numeric
 157 x.account_email: Required Field, have to be in valid email format
 158 xi.account_password: Required Field: Alpha Numeric
 159
 160 Returns a hash reference with one element, either 'error' for error conditions,
 161 or 'account_id' if the account is created sucessfully.
 162
 163 =head2 modifyAccount
 164
 165 Pass a list of key=>value pairs or a hash reference:
 166
 167 xiv.account_id: Required Field (Provided when the account was created)
 168 xv.account_name: Required Field
 169 xvi.account_desc
 170 xvii.account_addr
 171 xviii.account_city
 172 xix.account_state
 173 xx.account_country
 174 xxi.account_zip
 175 xxii.account_phone: Required Field
 176 xxiii.account_fax
 177 xxiv.account_email: Required Field
 178 xxv.account_password: Required Field
 179
 180 Returns a hash reference with one element, either 'error' for error conditions,
 181 or 'account_id' if the account is modified sucessfully.
 182
 183 =head2 addClient
 184
 185 Pass a list of key=>value pairs or a hash reference:
 186
 187 account_id: Required Field Alpha Numeric
 188 client_contact_name: Required Field Alpha Numeric
 189 client_contact_addr Alpha Numeric
 190 client_contact_city Alpha Numeric
 191 client_contact_state Alpha Numeric
 192 client_contact_country Alpha Numeric
 193 client_contact_zip Alpha Numeric
 194 client_contact_phone: Required Field Alpha Numeric
 195 client_contact_fax Alpha Numeric
 196 client_contact_email: Required Field Alpha Numeric
 197 client_contact_password: Required Field Alpha Numeric
 198
 199 Returns a hash reference with one element, either 'error' for error conditions,
 200 or 'client_id' if the account is created sucessfully.
 201
 202 =head2 modifyClient
 203
 204 Pass a list of key=>value pairs or a hash reference:
 205
 206 client_id: Required Field
 207 account_id: Required Field
 208 client_contact_name: Required Field
 209 client_contact_addr
 210 client_contact_city
 211 client_contact_state
 212 client_contact_country
 213 client_contact_zip
 214 client_contact_phone: Required Field
 215 client_contact_fax
 216 client_contact_email: Required Field
 217 client_contact_password: Required Field
 218
 219 Returns a hash reference with one element, either 'error' for error conditions,
 220 or 'client_id' if the account is modified sucessfully.
 221
 222 =head2 addConference
 223
 224 Pass a list of key=>value pairs or a hash reference:
 225
 226 client_id: Required Field Alpha Numeric (Required to associate conference to client, client ID provided when new client is added)
 227 conference_name: Required Field Alpha Numeric
 228 conference_desc Alpha Numeric
 229 start_time: Required Field Alpha Numeric
 230 moderated_flag:
 231 1 ¿ Presentation mode
 232 0 ¿ Conversation Mode
 233 entry_ann_flag: Integer
 234 0 ¿ None
 235 1 -  Tone
 236 2 - Name
 237 record_flag: Integer
 238 0 ¿ Stop Recording
 239 1 ¿ Start Recording
 240 moh_flag: Integer
 241 0 ¿ Stop MOH
 242 1 ¿ Start MOH
 243 talk_detect_flag
 244 play_user_cnt_flag: Integer
 245 1- Announce number of conference members currently in conference
 246 0 ¿ no Announcement
 247 wait_for_admin_flag: Integer
 248 1 - Only start conference once admin enters
 249 0 ¿ all users without admin
 250 stop_on_admin_exit_flag: Integer
 251 1 - End conference when admin exits:
 252 0 - No
 253 second_pin_flag: Integer
 254 1 - Prompt conference members for a second pin/password when logging in?
 255 0 - No Extra conference PIN
 256 secondary_pin: Integer
 257 If second_pin_flag is 1 also pass the PIN
 258 allow_sub_conf: Integer
 259 1 ¿ Allow sub conference for this conference
 260 0 ¿ Donot Allow sub conference
 261 duration: Integer
 262 Duration in minutes e.g 30 for 30 minutes
 263 conference_type: reservationless/reserved
 264
 265 On errors, returns a hash reference with one element, 'error', otherwise
 266 returns a hash reference with the following keys: conference_id, moderator_pin
 267 and participant_pin.
 268
 269 =head2 modifyConference
 270
 271 Pass a list of key=>value pairs or a hash reference:
 272
 273 conference_id: Required Field
 274 client_id: Required Field
 275 conference_name: Required Field
 276 conference_desc
 277 start_time: Required Field
 278 moderated_flag:
 279 1 ¿ Presentation mode
 280 0 ¿ Conversation Mode
 281 entry_ann_flag: Integer
 282 0 ¿ None
 283 1 -  Tone
 284 2 - Name
 285 record_flag: Integer
 286 0 ¿ Stop Recording
 287 1 ¿ Start Recording
 288 moh_flag: Integer
 289 0 ¿ Stop MOH
 290 1 ¿ Start MOH
 291 play_user_cnt_flag: Integer
 292 1- Announce number of conference members currently in conference
 293 0 ¿ no Announcement
 294 wait_for_admin_flag: Integer
 295 1 - Only start conference once admin enters
 296 0 ¿ all users without admin
 297 stop_on_admin_exit_flag: Integer
 298 1 - End conference when admin exits:
 299 0 - No
 300 second_pin_flag: Integer
 301 1 - Prompt conference members for a second pin/password when logging in?
 302 0 - No Extra conference PIN
 303 secondary_pin: Integer
 304 If second_pin_flag is 1 also pass the PIN
 305 allow_sub_conf: Integer
 306 1 ¿ Allow sub conference for this conference
 307 0 ¿ Donot Allow sub conference
 308 duration: Integer
 309 Duration in minutes e.g 30 for 30 minutes
 310
 311 Returns a hash reference with one element, either 'error' for error conditions,
 312 or 'conference_id' if the conference is modified sucessfully.
 313
 314 =head2 deleteAccount
 315
 316 Pass a list of key=>value pairs or a hash reference:
 317
 318 i.account_id: Required Field
 319
 320 On errors, should returns a hash reference with one element, 'error'.
 321
 322 =head2 deleteClient
 323
 324 Pass a list of key=>value pairs or a hash reference:
 325
 326 ii.client_id: Required Field
 327
 328 On errors, should returns a hash reference with one element, 'error'.
 329
 330 =head2 deleteConference
 331
 332 Pass a list of key=>value pairs or a hash reference:
 333
 334 iii.conference_id: Required Field
 335
 336 On errors, should returns a hash reference with one element, 'error'.
 337
 338 =head1 The services below are not yet documented/online
 339
 340 =head2 addConferencePIN
 341
 342 =head2 modifyConferencePIN
 343
 344 =head2 deleteConferencePIN
 345
 346 =head2 addDNIS
 347
 348 =head2 modifyDNIS
 349
 350 =head2 deleteDNIS
 351
 352 =head1 AUTHOR
 353
 354 Ivan Kohler, C<< <ivan-voicebridge at freeside.biz> >>
 355
 356 =head1 BUGS
 357
 358 Please report any bugs or feature requests to C<bug-net-indosoft-voicebridge at rt.cpan.org>, or through
 359 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Indosoft-Voicebridge>.  I will be notified, and then you'll
 360 automatically be notified of progress on your bug as I make changes.
 361
 362 =head1 SUPPORT
 363
 364 You can find documentation for this module with the perldoc command.
 365
 366     perldoc Net::Indosoft::Voicebridge
 367
 368 You can also look for information at:
 369
 370 =over 4
 371
 372 =item * RT: CPAN's request tracker
 373
 374 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Indosoft-Voicebridge>
 375
 376 =item * AnnoCPAN: Annotated CPAN documentation
 377
 378 L<http://annocpan.org/dist/Net-Indosoft-Voicebridge>
 379
 380 =item * CPAN Ratings
 381
 382 L<http://cpanratings.perl.org/d/Net-Indosoft-Voicebridge>
 383
 384 =item * Search CPAN
 385
 386 L<http://search.cpan.org/dist/Net-Indosoft-Voicebridge>
 387
 388 =back
 389
 390 =head1 ACKNOWLEDGEMENTS
 391
 392 This module was developed by Freeside Internet Services, Inc.
 393 If you need a complete, open-source web-based application to manage your
 394 customers, conferences, billing and trouble ticketing, please visit
 395 http://freeside.biz/
 396
 397 Development sponsored by NxxTcom Conferencing.  If you need a cost-effective
 398 voice, web or video conference, please visit http://www.nxxtcom.net/
 399
 400 =head1 COPYRIGHT & LICENSE
 401
 402 Copyright (c) 2009 Freeside Internet Services, Inc. <http://freeside.biz/>
 403 All rights reserved.
 404
 405 This program is free software; you can redistribute it and/or modify it
 406 under the same terms as Perl itself.
 407
 408 =cut
 409
 410 1;
 411