.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "SMS::Send 3pm" .TH SMS::Send 3pm "2023-08-18" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" SMS::Send \- Driver\-based API for sending SMS messages .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 5 \& # Create a sender \& my $sender = SMS::Send\->new(\*(AqSomeDriver\*(Aq, \& _login => \*(Aqmyname\*(Aq, \& _password => \*(Aqmypassword\*(Aq, \& ); \& \& # Send a message \& my $sent = $sender\->send_sms( \& text => \*(AqThis is a test message\*(Aq, \& to => \*(Aq+61 (4) 1234 5678\*(Aq, \& ); \& \& # Did the send succeed. \& if ( $sent ) { \& print "Message sent ok\en"; \& } else { \& print "Failed to send message\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`SMS::Send\*(C'\fR is intended to provide a driver-based single \s-1API\s0 for sending \s-1SMS\s0 and \s-1MMS\s0 messages. The intent is to provide a single \s-1API\s0 against which to write the code to send an \s-1SMS\s0 message. .PP At the same time, the intent is to remove the limits of some of the previous attempts at this sort of \s-1API,\s0 like \*(L"must be free internet-based \s-1SMS\s0 services\*(R". .PP \&\f(CW\*(C`SMS::Send\*(C'\fR drivers are installed separately, and might use the web, email or physical \s-1SMS\s0 hardware. It could be a free or paid. The details shouldn't matter. .PP You should not have to care how it is actually sent, only that it has been sent (although some drivers may not be able to provide certainty). .SH "METHODS" .IX Header "METHODS" .SS "installed_drivers" .IX Subsection "installed_drivers" The \f(CW\*(C`installed_drivers\*(C'\fR the list of SMS::Send drivers that are installed on the current system. .SS "new" .IX Subsection "new" .Vb 2 \& # The most basic sender \& $sender = SMS::Send\->new(\*(AqTest\*(Aq); \& \& # Indicate regional driver with :: \& $sender = SMS::Send\->new(\*(AqAU::Test\*(Aq); \& \& # Pass arbitrary params to the driver \& $sender = SMS::Send\->new(\*(AqMyDriver\*(Aq, \& _login => \*(Aqadam\*(Aq, \& _password => \*(Aqadam\*(Aq, \& ); .Ve .PP The \f(CW\*(C`new\*(C'\fR constructor creates a new \s-1SMS\s0 sender. .PP It takes as its first parameter a driver name. These names map the class names. For example driver \*(L"Test\*(R" matches the testing driver SMS::Send::Test. .PP Any additional params should be key/value pairs, split into two types. .PP Params without a leading underscore are \*(L"public\*(R" options and relate to standardised features within the SMS::Send \s-1API\s0 itself. At this time, there are no usable public options. .PP Params \fBwith\fR a leading underscore are \*(L"private\*(R" driver-specific options and will be passed through to the driver unchanged. .PP Returns a new SMS::Send object, or dies on error. .SS "send_sms" .IX Subsection "send_sms" .Vb 5 \& # Send a message to a particular address \& my $result = $sender\->send_sms( \& text => \*(AqThis is a test message\*(Aq, \& to => \*(Aq+61 4 1234 5678\*(Aq, \& ); .Ve .PP The \f(CW\*(C`send_sms\*(C'\fR method sends a standard text \s-1SMS\s0 message to a destination phone number. .PP It takes a set of named parameters to describe the message and its destination, again split into two types. .PP Params without a leading underscore are \*(L"public\*(R" options and relate to standardised features within the SMS::Send \s-1API\s0 itself. .IP "text" 4 .IX Item "text" The \f(CW\*(C`text\*(C'\fR param is compulsory and should be a plain text string of non-zero length. The maximum length is currently determined by the driver, and exceeding this length will result in an exception being thrown if you breach it. .Sp Better functionality for determining the maximum-supported length is expected in the future. You input would be welcome. .IP "to" 4 .IX Item "to" The \f(CW\*(C`to\*(C'\fR param is compulsory, and should be an international phone number as indicated by a leading plus \*(L"+\*(R" character. Punctuation in any form is allowed, and will be stripped out before it is provided to the driver. .Sp If and only if your driver is a regional driver (as indicated by a ::\-seperated name such as AU::Test) the \f(CW\*(C`to\*(C'\fR number can also be in a regional-specific dialing format, \f(CW\*(C`without\*(C'\fR a leading plus \*(L"+\*(R" character. .Sp Providing a regional number to a non-regional driver will throw an exception. .PP Any parameters \fBwith\fR a leading underscore are considered private driver-specific options and will be passed through without alteration. .PP Any other parameters \fBwithout\fR a leading underscore will be silently stripped out and not passed through to the driver. .PP After calling \f(CW\*(C`send_sms\*(C'\fR the driver will do whatever is required to send the message, including (potentially, but not always) waiting for a confirmation from the network that the \s-1SMS\s0 has been sent. .PP Given that drivers may do the actual mechanics of sending a message by quite a large variety of different methods the \f(CW\*(C`send_sms\*(C'\fR method may potentially block for some time. Timeout functionality is expected to be added later. .PP The \f(CW\*(C`send_sms\*(C'\fR returns true if the message was sent, or the driver is fire-and-forget and unable to determine success, or false if the message was not sent. .SH "SUPPORT" .IX Header "SUPPORT" Bugs should be reported via the \s-1CPAN\s0 bug tracker at .PP .PP For other issues, contact the author. .SH "AUTHOR" .IX Header "AUTHOR" Adam Kennedy .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2005 \- 2011 Adam Kennedy. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the \&\s-1LICENSE\s0 file included with this module.