README
1NAME
2 SMS::Send - Driver-based API for sending SMS messages
3
4SYNOPSIS
5 # Create a sender
6 my $sender = SMS::Send->new('SomeDriver',
7 _login => 'myname',
8 _password => 'mypassword',
9 );
10
11 # Send a message
12 my $sent = $sender->send_sms(
13 text => 'This is a test message',
14 to => '+61 (4) 1234 5678',
15 );
16
17 # Did the send succeed.
18 if ( $sent ) {
19 print "Message sent ok\n";
20 } else {
21 print "Failed to send message\n";
22 }
23
24DESCRIPTION
25 "SMS::Send" is intended to provide a driver-based single API for sending
26 SMS and MMS messages. The intent is to provide a single API against
27 which to write the code to send an SMS message.
28
29 At the same time, the intent is to remove the limits of some of the
30 previous attempts at this sort of API, like "must be free internet-based
31 SMS services".
32
33 "SMS::Send" drivers are installed seperately, and might use the web,
34 email or physical SMS hardware. It could be a free or paid. The details
35 shouldn't matter.
36
37 You should not have to care how it is actually sent, only that it has
38 been sent (although some drivers may not be able to provide certainty).
39
40METHODS
41 installed_drivers
42 The "installed_drivers" the list of SMS::Send drivers that are installed
43 on the current system.
44
45 new
46 # The most basic sender
47 $sender = SMS::Send->new('Test');
48
49 # Indicate regional driver with ::
50 $sender = SMS::Send->new('AU::Test');
51
52 # Pass arbitrary params to the driver
53 $sender = SMS::Send->new('MyDriver',
54 _login => 'adam',
55 _password => 'adam',
56 );
57
58 The "new" constructor creates a new SMS sender.
59
60 It takes as its first parameter a driver name. These names map the class
61 names. For example driver "Test" matches the testing driver
62 SMS::Send::Test.
63
64 Any additional params should be key/value pairs, split into two types.
65
66 Params without a leading underscore are "public" options and relate to
67 standardised features within the SMS::Send API itself. At this time,
68 there are no usable public options.
69
70 Params with a leading underscore are "private" driver-specific options
71 and will be passed through to the driver unchanged.
72
73 Returns a new SMS::Send object, or dies on error.
74
75 send_sms
76 # Send a message to a particular address
77 my $result = $sender->send_sms(
78 text => 'This is a test message',
79 to => '+61 4 1234 5678',
80 );
81
82 The "send_sms" method sends a standard text SMS message to a destination
83 phone number.
84
85 It takes a set of named parameters to describe the message and its
86 destination, again split into two types.
87
88 Params without a leading underscore are "public" options and relate to
89 standardised features within the SMS::Send API itself.
90
91 text
92 The "text" param is compulsory and should be a plain text string of
93 non-zero length. The maximum length is currently determined by the
94 driver, and exceeding this length will result in an exception being
95 thrown if you breach it.
96
97 Better functionality for determining the maximum-supported length is
98 expected in the future. You input would be welcome.
99
100 to The "to" param is compulsory, and should be an international phone
101 number as indicated by a leading plus "+" character. Punctuation in
102 any form is allowed, and will be stripped out before it is provided
103 to the driver.
104
105 If and only if your driver is a regional driver (as indicated by a
106 ::-seperated name such as AU::Test) the "to" number can also be in a
107 regional-specific dialing format, "without" a leading plus "+"
108 character.
109
110 Providing a regional number to a non-regional driver will throw an
111 exception.
112
113 Any parameters with a leading underscore are considered private
114 driver-specific options and will be passed through without alteration.
115
116 Any other parameters without a leading underscore will be silently
117 stripped out and not passed through to the driver.
118
119 After calling "send_sms" the driver will do whatever is required to send
120 the message, including (potentially, but not always) waiting for a
121 confirmation from the network that the SMS has been sent.
122
123 Given that drivers may do the actual mechanics of sending a message by
124 quite a large variety of different methods the "send_sms" method may
125 potentially block for some time. Timeout functionality is expected to be
126 added later.
127
128 The "send_sms" returns true if the message was sent, or the driver is
129 fire-and-forget and unable to determine success, or false if the message
130 was not sent.
131
132SUPPORT
133 Bugs should be reported via the CPAN bug tracker at
134
135 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SMS-Send>
136
137 For other issues, contact the author.
138
139AUTHOR
140 Adam Kennedy <adamk@cpan.org>
141
142COPYRIGHT
143 Copyright 2005 - 2011 Adam Kennedy.
144
145 This program is free software; you can redistribute it and/or modify it
146 under the same terms as Perl itself.
147
148 The full text of the license can be found in the LICENSE file included
149 with this module.
150
151