NAME

Mobile::Messaging::ParlayX - Interface to ParlayX OSA.

Version 0.0.3

SYNOPSIS

use Mobile::Messaging::ParlayX;

DESCRIPTION

Mobile::Messaging::ParlayX is an interface to ParlayX web service by Sony Ericsson for SMS and MMS messaging, among other things. This being a Web Service SOAP::Lite would probably be better suited to the task, but I decided to stick with LWP::UserAgent, HTTP::Request and XML::LibXML until things in SOAP::Lite stabilize (it is currently under rewrite as far as I know) and I have more time (not that this will happen anytime soon). Besides, I cannot fully grasp ParlayX just yet, thanks to inadequate documentation and JAVA only code samples for it. Anyway, you need LWP::UserAgent , HTTP::Request and XML::LibXML for this module to work. Most are in the standard distribution already, but any of them are available at your local CPAN mirror.

I tried not to stray too far off the ``native'' JAVA names of method and properties, but chances are some differences exist.

new Mobile::Messaging::ParlayX

new Mobile::Messaging::ParlayX

Parameters/Properties

username: => Your mobile operator should provide you with this, along with
password: => for your authentication against his gateway.
nonce: => This is also supposed to be part of the authentication process, though I`m not quite sure what it does... Note that both password and nonce seem to be some kind of Base64 encoded digests, though I`m not quite sure what they are. If you figure it out, I`ll be happy to include them here.
host: => Your operators` mobile gateway; the one your SOAP request will end up in.
senderName: => Technically, the originator of the SMS. Specs say it can be alphanumeric up to 11 chars in length, though your operator may or may not allow you to set it.
receiptRequest: => You can ask for a delivery report for each SMS message, though the details of this are unclear to me, since my operator does not (for the time being) support this. ``receiptRequest'' should be a hash reference with ``endpoint'', ``correlator'' and ``interfaceName'' as the keys. In theory, endpoint should be a URI of your own, where the operator will POST a SOAP of the results of the SMS. Correlator is supposed to be a unique ID for this message, and your guess is as good as mine what ``interfaceName'' stands for. How this works and how bad, I do not know, since if I put receiptRequest in my SOAP request, my operator will drop the message altogether. You can still try and send me a patch/recommendation though.
ChargingInformation: => This is supposed to carry MT (Mobile Terminated) charging info in it and seems to work better than receiptRequest above, but I cannot confirm this yet. It is also a hash reference with ``description'' (probably will appear on the users` bill as such), ``currency'' and ``amount'' (which are fairly self-explanatory, although amount should be decimal ie not a float) and ``code'' (which I haven`t the faintest idea what it does). if you provide at least the first 3, the module will put the relavant item in the SOAP request, though again I cannot guarantee that it`ll work as expected. UPDATE: Either amount and currency or just plain code will work. Code is supposed to contain what TIM refers to as VASID and VASPID, which in itself is enough for an MT message.

Methods

sendSMS

=> Pretty much finished. It would be highly unusable without named arguments, so call it like so:

$self->sendSMS( { 
	username => 'Your ParlayX Username',
	host => 'ParlayX SMS Gateway',
	password => 'Password',
	nonce => 'No Idea What This Does',
	senderName => 'Where The SMS will Seem to Come From',
	message => 'The actual sms message',
	addresses => 'Recipient(s)',
	receiptRequest => { 
		endpoint => 'URI where the reciept will be sent',
		interfaceName => 'Never used that one and dont quite know what it is',
		correlator => 'Unique ID of the receiver'
	}
	ChargingInformation => {
		description => 'Arbitrary string describing the reason for the MT charge',
		currency => 'Should be self-explanatory, but my operator does not use it',
		amount => 'Ditto, because these are inside argument code',
		code => 'Instead of amount and currency, you have these pre-packaged in code'
		}
} );

Obviously username, host, message and addresses are mandatory for anything to work at all, the rest can be filled in according to your requirements. Your operator should give you a pretty good idea what`s neccessary and what is not. Returns two scalars, the first indicating success (1) or not (0) while the second will give you the unique id of the message (for future delivery report queries) in case of success. In case of failure it will hopefully contain the error string returned by ParlayX Gateway. The module will happily croak() if LWP::UserAgent cannot establish communication with ParlayX Gateway. Ah, message and addresses can be array references, to send different messages to different recipients or the same message to multiple recipients, or even different messages to the same recipient. Mix those as you see fit.

getSmsDeliveryStatus

=> Pretty much finished too. It would be highly unusable without named arguments, so call it like so:

$self->getSmsDeliveryStatus( { 
	username => 'Your ParlayX Username',
	host => 'ParlayX SMS Gateway',
	password => 'Password',
	nonce => 'No Idea What This Does',
	messageid => 'A message unique ID, obtained from sendSMS() above',
} );

Needs username, host and messageid for anything to work at all, the rest can be filled in according to your requirements. Your operator should give you a pretty good idea what`s neccessary and what is not. Returns a scalar indicating success (1) or not (0) and a hash reference (if you only asked for a single message ID) containing deliveryStatus and recipients` address (addresses). if you used an array reference to ask for multiple message IDs, the 2nd returning value will be an array reference with hashes like the one above inside it (should work, but could not be tested in time).

ReceiveSms

=> Works quite well for me YMMV.

$self->ReceiveSms( { 
	username => 'Your ParlayX Username',
	host => 'ParlayX SMS Gateway',
	password => 'Password',
	nonce => 'No Idea What This Does',
	registrationIdentifier => 'Never seen this used, so dont know what it does - username should be enough to identify you',
} );

This is the polling interface for receiving SMS from ParlayX. Using it will result in ParlayX ``de-spooling'' awaiting SMSs for you. Obviously needs a username to work and may need registrationIdentifier, the rest can be filled in according to your requirements. Your operator should give you a pretty good idea what`s neccessary and what is not. Returns a scalar indicating success (1) or not (0) and a hash reference (if only a single SMS was waiting in line) containing message, senderAddress and the number the SMS was sent to (smsServiceActivationNumber). if multiple messages are waiting, the 2nd returning value will be an array reference with hashes like the one above inside it.

ReceiveAutoSms

=> $self->ReceiveAutoSms($incoming_soap_post);

This is the other (lets call on-demand) interface for receiving SMS from ParlayX. You need to register yourself with the gateway (see startSmsNotification() and stopSmsNotification() below) and then, whenever you have an incoming SMS, the gateway will POST any SMS to the URI you specified there. Returns a hash reference containing message, senderAddress and the number the SMS was sent to (smsServiceActivationNumber). An example, written in mod_perl/Apache::ASP, script accepting SMS follows.

<%
	use strict;
	use Mobile::Messaging::ParlayX;
	my $incoming = $Request->BinaryRead();
	$incoming =~ s|<message>|<result>|s;
	$incoming =~ s|(smsServiceActivationNumber>.*?)</message>|$1</result>|s;
	my $ret = $sms->ReceiveAutoSms(\$incoming);
%>>

In the example above, now $ret->{'message'} contains the SMS, $ret->{'smsServiceActivationNumber'} contains the number the SMS was sent to (but prefixed with ``tel:'' so you might want to remove this before replying) and $ret->{'senderAddress'} contains the number of the person who sent the SMS (which can be used as is in the reply). Due to (our operator`s only ?) ParlayX being slightly liberal (for lack of a better word) it uses <message>, while it meant <result>. The regex is there to make the message compatible with ReceiveSms() parsing above. Also note the use of ``\$incoming'': In general, I try to avoid copying large strings back and forth and most of the module will happily accept a scalar or a reference when either would apply. So you could use ``my $ret = $sms->ReceiveAutoSms($incoming);'' instead if you feel more comfortable with it. Personally, I designed it so I could use ``my $ret = $sms->ReceiveAutoSms(\$Request->BinaryRead());'' and I would too, if it were not for the funky <message> instead of <result> stuff.

stopSmsNotification

$self->stopSmsNotification( { 
	username => 'Your ParlayX Username',
	host => 'ParlayX SMS Gateway',
	password => 'Password',
	nonce => 'No Idea What This Does',
	correlator => 'Unique Identifier for you (assigned when you did startSmsNotification()'
} );

if you previously registered yourself with ParlayX with startSmsNotification() and you do not want to automatically recieve SMS from now on, use this. It tells ParlayX to stop sending you SMS to the URI you specified. You`ll probably never have to use this, but it is included for the sake of completeness. I have no idea if it works without a correlator (mine doesn`t), but if you implementation is different, feel free to fix this.

startSmsNotification

$self->startSmsNotification( { 
	username => 'Your ParlayX Username',
	host => 'ParlayX SMS Gateway',
	password => 'Password',
	nonce => 'No Idea What This Does',
	endpoint => 'YOUR URI that ParlayX will send SMS to',
	correlator => 'A unique ID for you (more on this later)',
	interfaceName => 'No idea..always empty as far as I know'
} );

To register yourself with ParlayX you need to use this. After you do, all SMS to your number will be sent to the URI you specify in ``endpoint''. if you do not specify a correlator, time() will be used. Returns 3 scalars, the first indicating success (1) or failure (0), the second your designated correlator (keep this somewhere safe) and the third will normall be empty, except for error cases, where it will contain extended error information. Probably one-off use for it...

Esoterics

Before we do this, know that all this is subject (rather mandatory I think) to change.
soap_header
soap_footer
parse_xml
doHTTP
soap_startsms_body
soap_stopsms_body
soap_deliv_body
soap_send_body
soap_receivesms_body
receipt_request
charging_info: => In very particular order, the top 4 things are not very likely to change anytime soon, unless SOAP::Lite transforms into something usable by a poor smuck like me soon. About the rest, I do not know, especially charging_info and receipt_request are only written based on (shoddy) documentation and have never been used in real life.

Revision History

 0.0.1 
	Initial Release
 0.0.2 
	Requisite XML::LibXML 1.62 specified in Makefile.PL
	Fixed some POD formatting issues
	Fixed some POD typos
 0.0.3
	Corrected tag ``ChargingInformation'' to ``charging'' in sub charging_info, as per documentation

Caveats

I really mean to split this to Mobile::Messaging::ParlayX::SMS, Mobile::Messaging::ParlayX::MMS and Mobile::Messaging::ParlayX::TS (Terminal Status), but I really ran out of time. Perhaps in the future (along with better SOAP handling). while on the subject of SOAP handling, I use XML::LibXML to validate all objects before sending, receiving or processing them, but this is obviously one area that needs quite a lot of work. I`ve also done very little in terms of charsets, partly because my operator was in no position to tell me and partly because I was lazy. I have no clue what happens with GSM 03.38, UTF-8 and numeric encoded UTF-8 thrown in the mix. I`ve reached a point where it works semi-reliably for me and - after I take a break - I`ll look further into this.

BUGS

Initial release...what did you expect ;) - well, not any more, but 0.0.2 fixes were purely cosmetic in nature. Seriously now, most of the stuff is confirmed to work but probably not all angles are covered (in fact, I suspect very few are).

ACKNOWLEDGEMENTS

Obvious thanks to LWP::UserAgent, HTTP::Request and XML::LibXML authors, for none of this would be possible without them (although some may argue that this would be a good thing). Big thanks should also go to Joshua Chamas for Apache::ASP and the mod_perl gurus.

AUTHOR

Thanos Chatziathanassiou <tchatzi@arx.net> http://www.arx.net

COPYRIGHT

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

To install Mobile::Messaging::ParlayX, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mobile::Messaging::ParlayX

CPAN shell

perl -MCPAN -e shell
install Mobile::Messaging::ParlayX

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)