/ 
SMS-Send-Driver-WebService-0.06
River stage one • 5 direct dependents • 6 total dependents
/ SMS::Send::Driver::WebService

NAME

SMS::Send::Driver::WebService - SMS::Send driver base class for web services

SYNOPSIS

package SMS::Send::My::Driver;
use base qw{SMS::Send::Driver::WebService};
sub send_sms {
  my $self = shift;
  my $ua   = $self->ua;  #isa LWP::UserAgent
  my $uat  = $self->uat; #isa HTTP::Tiny
  my $cfg  = self->cfg;  #isa Config::IniFiles
  #call web service die on critical error
  #parse return with a package like XML::Simple or JSON::XS
  #return 1 for successful or 0 for unsuccessful
}

DESCRIPTION

The SMS::Send::Driver::WebService package provides an SMS::Send driver base class to support two common needs. The first need is a base class that provides LWP::UserAgent as a simple method. The second need is a way to configure various setting for multiple SMS providers without having to rebuild the SMS::Send driver concept.

USAGE

use base qw{SMS::Send::Driver::WebService};

METHODS

new

SMS::Send API; Note: $service isa SMS::Send object in this syntax

my $service = SMS::Send->new("My::Driver",
                                        _username => $username,
                                        _password => $password,
                                        );

Driver API; Note: $service isa SMS::Send::My::Driver object in this syntax

my $service = SMS::Send::My::Driver->new(
                                         username => $username,
                                         password => $password,
                                        );

SMS::Send API with SMS-Send.ini file

SMS-Send.ini
[My::Driver1]
username=user1
password=pass1

[My::Driver2]
username=user2
password=pass2

my $service1 = SMS::Send->new("My::Driver1"); #username and password read from SMS-Send.ini
my $service2 = SMS::Send->new("My::Driver2"); #username and password read from SMS-Send.ini

Driver API with SMS-Send.ini file

my $service = SMS::Send::My::Driver1->new;

initialize

Initializes data to compensate for the API deltas between SMS::Send and this package (i.e. removes underscore "_" from all parameters passed)

In this example

SMS::Send->new("My::Driver", _password => "mypassword");

_password would be available to the driver as password=>"mypassword";

send_sms

You will need to overload this method in your sub class.

Override in sub class (Example from Kannel SMSBox implementation)

sub send_sms {
  my $self = shift;
  my %argv = @_;
  my $to   = $argv{"to"} or die("Error: to address required");
  my $text = defined($argv{"text"}) ? $argv{"text"} : ''; #use < 5.10 syntax to support older Perls
  my $url  = $self->url; #isa URI
  my @form = (
               username   => $self->username,
               password   => $self->password,
               to         => $to,
               text       => $text,
             );
  $url->query_form(\@form); #isa URI
  my $response = $self->ua->get($url); #isa HTTP::Response see LWP::UserAgent->get
  die(sprintf("HTTP Error: %s", $response->status_line)) unless $response->is_success;
  my $content  = $response->decoded_content;
  return $content =~ m/^0:/ ? 1 : 0; #0: Accepted for delivery
}

PROPERTIES

username

Sets and returns the username string value

Override in sub class

sub _username_default {"myusername"};

Override in configuration

[My::Driver]
username=myusername

password

Sets and returns the password string value (passed to the web service as PWD)

Override in sub class

sub _password_default {"mypassword"};

Override in configuration

[My::Driver]
password=mypassword

host

Default: 127.0.0.1

Override in sub class

sub _host_default {"myhost.domain.tld"};

Override in configuration

[My::Driver]
host=myhost.domain.tld

protocol

Default: http

Override in sub class

sub _protocol_default {"https"};

Override in configuration

[My::Driver]
protocol=https

port

Default: 80

Override in sub class

sub _port_default {443};

Override in configuration

[My::Driver]
port=443

script_name

Default: /cgi-bin/sendsms

Override in sub class

sub _script_name_default {"/path/file"};

Override in configuration

[My::Driver]
script_name=/path/file

url

Returns a URI object based on above properties OR returns a string from sub class or configuration file.

Override in sub class (Can be a string or any object that stringifies to a URL)

sub _url_default {"http://myservice.domain.tld/path/file"};

Override in configuration

[My::Driver]
url=http://myservice.domain.tld/path/file

Overriding the url method in the sub class or the configuration makes the protocol, host, port, and script_name methods inoperable.

OBJECT ACCESSORS

uat

Returns a lazy loaded HTTP::Tiny object

ua

Returns a lazy loaded LWP::UserAgent object

cfg

Returns a lazy loaded Config::IniFiles object so that you can read settings from the INI file.

my $cfg=$driver->cfg; #isa Config::IniFiles

cfg_file

Sets or returns the profile INI filename

my $file=$driver->cfg_file;
my $file=$driver->cfg_file("./my.ini");

Set on construction

my $driver=SMS::Send::My::Driver->new(cfg_file=>"./my.ini");

Default: SMS-Send.ini

cfg_path

Sets and returns a list of search paths for the INI file.

my $path=$driver->cfg_path;            # []
my $path=$driver->cfg_path(".", ".."); # []

Default: ["."] Default: [".", 'C:\Windows'] on Windows-like systems that have Win32 installed Default: [".", "/etc"] on other systems that have Sys::Path installed

override in sub class

sub cfg_path {["/my/path"]};

cfg_section

Returns driver name as specified by package namespace

Example package SMS::Send::My::Driver;

Configuration in SMS-Send.ini file

[My::Driver]
username=myuser
password=mypass
host=myserver

cfg_property

my $property=$self->cfg_property("username");
my $property=$self->cfg_property("host", "mydefault");

BUGS

Please log on RT and send an email to the author.

SUPPORT

DavisNetworks.com supports all Perl applications including this package.

AUTHOR

Michael R. Davis
CPAN ID: MRDVT
Satellite Tracking of People, LLC
mdavis@stopllc.com
http://www.stopllc.com/

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

SMS::Send