The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-EMI-Client-1.0
River stage zero No dependents
/ Net::EMI::Client

NAME

Net::EMI::Client - EMI/UCP GSM SMSC Protocol Client Class

DEPENDENCIES

Net::EMI::Client uses the following modules:

IO::Socket

Net::EMI::Common

SYNOPSIS

use Net::EMI::Client

$emi = Net::EMI::Client->new(SMSC_HOST=>'smsc.somedomain.tld', SMSC_PORT=>3024, SENDER_TEXT=>'My Self 123');

DESCRIPTION

This module implements a Client Interface to the EMI (External Machine Interface) specification, which itself is based on the ERMES UCP (UNIVERSAL Computer Protocol) with some SMSC-specific extensions.

The EMI protocol can be used to compose, send, receive, deliver... short messages to GSM Networks via EMI-enabled SMSC's (Short Message Service Center). Usually the Network connection is based on TCP/IP or X.25. The EMI/UCP specification can be found at http://www.cmgtele.com/docs/SMSC_EMI_specification_3.5.pdf .

This EMI Client class can be used to send an SMS message to an SMSC. You will of course be required to have a valid login at the SMSC to use their services. (Unless there is an SMSC which provides their services for free. Please, let me know about any such service provider. :-)

A Net::EMI::Client object must be created with the new() constructor. Once this has been done, all commands are accessed via method calls on the object.

EXAMPLE

use Net::EMI::Client;

($recipient,$text,$sender)=@ARGV;

my($acknowledge,$error_number,$error_text);

$emi = Net::EMI::Client->new(SMSC_HOST=>'smsc.somedomain.tld', SMSC_PORT=>3024, SENDER_TEXT=>'MyApp', WARN=>1) || die("Failed to create SMSC object");

$emi->open_link() || die("Failed to connect to SMSC")

($acknowledge,$error_number,$error_text) = $emi->login(SMSC_ID=>'your_account_id', SMSC_PW=>'your password');

die("Login to SMSC failed. Error nbr: $error_number, Error txt: $error_text\n") unless($acknowledge);

($acknowledge,$error_number,$error_text) = $emi->send_sms(RECIPIENT=>$recipient, MESSAGE_TEXT=>$text, SENDER_TEXT=>$sender);

die("Sending SMS failed. Error nbr: $error_number, Error txt: $error_text\n") unless($acknowledge);

$emi->close_link();

CONSTRUCTOR

new( SMSC_HOST=>'smsc.somedomain.tld', SMSC_PORT=>3024, SENDER_TEXT=>'My App', WARN=>1 )

The parameters may be given in arbitrary order.

SMSC_HOST=> Mandatory. The hostname or ip-address of the SMCS.

SMSC_PORT=> Optional. The TCP/IP port number of your SMSC. If omitted, port number 3024 will be used by default.

SENDER_TEXT=> Optional. The text that will appear in the receivers mobile phone, identifying you as a sender. If omitted, the text 'Net::EMI::Client' will be used by default. You will probably want to provide a more meaningful text than that.

WARN=> Optional. If this parameter is given and if it evaluates to true, then any warnings and errors will be written to STDERR. If omitted, or if the parameter evaluates to false, then nothing is written to STDERR. It is strongly recommended to turn on warnings during the development of an application using the Net::EMI::Client module. When development is finished, the developer may chose to not require warnings but to handle all error situations completely in the main application by checking the return values from Net::EMI::Client.

The constructor returns undef if mandatory information is missing or invalid parameter values are detected. In this case, the object is discarded (out of scope) by the Perl interpreter and you cannot call any methods on the object handle.

Any errors detected will be printed on STDERR if the WARN=> parameter evaluates to true.

Test the return value from the constructor!

METHODS

open_link()

Open the communication link to the SMSC. In reality, this opens up a socket to the SMSC. Be aware that this is not an authenticated login but that the login() method must also be called before any SMS messages can be sent to the SMSC. open_link() is useful since the main application can verify that it's at all possible to communicate with the SMSC. (Think: getting through a firewall.)

This method takes no parameters since it will use the data given in the constructor parameters.

Any errors detected will be printed on STDERR if the WARN=> parameter in the constructor evaluates to true.

open_link() returns true on success and undef in case something went wrong.

login(SMSC_ID=>'my_account_id', SMSC_PW=>'MySecretPassword')

Authenticates against the SMSC with the given SMSC-id and password. Operation 60 of EMI Protocol. If the open_link() method has not explicitly been called by the main application, the login() method will do it before trying to authenticate with the SMSC.

The parameters may be given in arbitrary order.

SMSC_ID=> Mandatory. A string which should be a valid account ID at the SMSC.

SMSC_PW=> Mandatory. A valid password at the SMSC.

Any errors detected will be printed on STDERR if the WARN=> parameter in the constructor evaluates to true.

Return values:

In a scalar context, login() will return true for success, false for transmission failure and undef for application related errors. Application related errors may be for instance that a mandatory parameter is missing. All such errors will be printed on STDERR if the WARN=> parameter in the constructor evaluates to true.

In an array context, login() will return three values: ($acknowledge, $error_number, $error_text); where $acknowledge holds the same value as when the method is called in scalar context (i.e. true, false or undef), $error_number contains a numerical error code from the SMSC and $error_text contains a (relatively) explanatory text about the error.

Be aware that both $error_number and $error_text are provided in a response from the SMSC, which means that the data quality of these entities depends on how well the SMSC has implemented the protocol.

If $acknowledge is undef, then $error_number will be set to 0 (zero) and $error_text will contain a zero length string.

It is strongly recommended to call login() in an array context, since this provides for an improved error handling in the main application.

send_sms( RECIPIENT=>'9999999999', MESSAGE_TEXT=>'A Message', SENDER_TEXT=>'Some text' )

Submits the SMS message to the SMSC (Operation 51) and waits for an SMSC acknowledge.

The parameters may be given in arbitrary order.

RECIPIENT=> Mandatory. This is the phone number of the recipient in international format with leading + or 00.

MESSAGE_TEXT=> Optional. A text message to be transmitted. It is accepted to transfer an empty message, so if this parameter is missing, a zero length string will be sent.

SENDER_TEXT=> Optional. The text that will appear in the receivers mobile phone, identifying you as a sender. This text will temporarily replace the text given to the constructor. If omitted, the text already given to the constructor will be used.

Any errors detected will be printed on STDERR if the WARN=> parameter in the constructor evaluates to true.

Return values:

In a scalar context, send_sms() will return true for success, false for transmission failure and undef for application related errors. Application related errors may be for instance that a mandatory parameter is missing. All such errors will be printed on STDERR if the WARN=> parameter in the constructor evaluates to true.

In an array context, send_sms() will return the three values: ($acknowledge, $error_number, $error_text); where $acknowledge holds the same value as when the method is called in scalar context (i.e. true, false or undef), $error_number contains a numerical error code from the SMSC and $error_text contains a (relatively) explanatory text about the error.

Be aware that both $error_number and $error_text are provided in a response from the SMSC, which means that the data quality of these entities depends on how well the SMSC has implemented the protocol.

If $acknowledge is undef, then $error_number will be set to 0 (zero) and $error_text will contain a zero length string.

It is strongly recommended to call send_sms() in an array context, since this provides for an improved error handling in the main application.

Note! The fact that the message was successfully transmitted to the SMSC does not guarantee immediate delivery to the recipient or in fact any delivery at all.

logout()
close_link()

logout() is an alias for close_link(). Whichever method name is used, the very same code will be executed.

What goes up, must also come down. If the main application will continue working on other tasks once the SMS message was sent, it is possible to explicitly close the communications link to the SMSC with this method.

If the Net::EMI::Client object handle (returned by the new() method) goes out of scope in the main application, the link will be implicitly closed and in this case it is not necessary to explicitly close the link.

In reality, this method closes the socket established with the SMSC and does some additional house-keeping. Once the link is closed, a new call to either open_link() or to login() will try to re-establish the communications link (socket) with the SMSC.

returns nothing (void)

SEE ALSO

IO::Socket

IO::Socket::INET

Net::EMI::Common

AUTHOR

Gustav Schaffter <schaffter_cpan@hotmail.com>

ACKNOWLEDGMENTS

I'd like to thank Jochen Schneider for writing the first beta releases under the name Net::EMI and also for letting me in on the project.

In February 2003, Jochen gave me free hands to distribute this class module which is primarily built upon his work. Without Jochens initial releases this module would probably not have seen the light.

And, as everyone else I owe so much to Larry. For having provided Perl.

COPYRIGHT

Copyright (c) 2002 Jochen Schneider. Copyright (c) 2003 Gustav Schaffter. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.