NAME

Net::SMS - Sends wireless messages to any carrier including text messages and SMS (Short Message Service).

SYNOPSIS

The Perl SMS SDK provides easy, high-level control of the Simplewire wireless text-messaging platform. The Perl SMS SDK was designed to be as developer-friendly as possible by hiding the intricacies of the XML format required to communicate with the Simplewire WMP (Wireless Message Protocol) servers. The Perl SMS SDK makes it possible to send an SMS message off with as little as two lines of code.

This software is commercially supported. Go to www.simplewire.com for more information.

INSTALLATION

For very detailed instructions, please refer to the .PDF manual that has been included in the /docs directory of the Net-SMS-X.XX.tar.gz download. Once you unzip and untar this file, inside the /docs directory will be very detailed installation instructions.

If you are advanced in Perl, then you may just follow the instructions below. Place the release file in the root directory. In the root directory, execute the following commands, where "X.XX" represents the specific version being used.

[root]# tar -zxvf Net-SMS-X.XX.tar.gz

[root]# cd Net-SMS-X.XX

[Net-SMS-X.XX]# perl Makefile.PL

[Net-SMS-X.XX]# make

[Net-SMS-X.XX]# make install

EXAMPLES

See the /examples folder that is contained within the Net-SMS-X.XX.tar.gz download file.

QUICK START

# Import Module use Net::SMS;

# Create Object my $sms = Net::SMS->new();

# Subscriber Settings $sms->subscriberID("123-456-789-12345"); $sms->subscriberPassword("Password Goes Here");

# Message Settings $sms->msgPin("+1 100 510 1234"); $sms->msgFrom("Demo"); $sms->msgCallback("+1 100 555 1212"); $sms->msgText("Hello World From Simplewire!");

print "Sending message to Simplewire...\n";

# Send Message $sms->msgSend();

# Check For Errors if ($sms->success) { print "Message was sent!\n"; } else { print "Message was not sent!\n"; print "Error Code: " . $sms->errorCode() . "\n"; print "Error Description: " . $sms->errorDesc() . "\n"; print "Error Resolution: " . $sms->errorResolution() . "\n"; }

Receiving SMS

Please see http://www.simplewire.com/services/mo/ for more information on receiving SMS.

EMS (Enhanced Message Service)

Quick start for EMS:

    $sms->optContentType("ems");
    $sms->emsAddPredefinedSound(1);
    $sms->emsAddPredefinedAnimation(1);
    $sms->emsAddSmallPicture("example.gif");
    $sms->emsAddText("This is an EMS from Simplewire!");

Simplewire supports sending EMS messages via its network. The Enhanced Messaging Service (EMS) uses standard SMS and allows the user to add fun visual and audible content to their message. For example, simple animations, pictures, melodies, sounds and even formatting of the text itself, everything mixed together seamlessly into one message.

To activate EMS add the following line to your code:

    $sms->optContentType("ems");

This is a summary of the EMS functions built-in to this SDK:

    emsAddText()
    emsAddPredefinedSound()
    emsAddPredefinedAnimation()
    emsAddUserDefinedSound()
    emsAddSmallPicture()
    emsAddSmallPictureHex()
    emsAddLargePicture()
    emsAddLargePictureHex()
    emsAddUserPromptIndicator()

SMS, and therefore EMS, are not actually sent from handset across the mobile network to handset as it appears to users, but instead messages are sent from handsets, or from Simplewire's network, to a Short Message Service Center (SMSC) resident on the Operator’s network, and then on to the receiving handset.

EMS has a ‘Store and Forward’ model – i.e. messages are forwarded to the receiving handset as soon as it is reachable, and a user does not have to access a network-based inbox to receive messages. Indeed EMS’s can be received whilst a handset is making a voice call, browsing the Internet, etc. Further, delivery reporting is also supported to enable a user to check that a message has been successfully delivered.

Therefore, EMS has many advantages as a messaging platform for the mobile world, where convenience and ease of use are key.

Pictures

    # 16x16 image, black and white
    $sms->emsAddSmallPicture("example.gif");

    # 32x32 image, black and white
    $sms->emsAddLargePicture("large.gif");

        

Pictures are contained within a single SM (Short Message, or ‘segment’ if describing an SM that is part of a concatenated message). It is possible to include either small (16*16 pixels) or large (32*32 pixels). Larger pictures may be sent by joining small pictures together using the emsAddUserPromptIndicator() function. Please see below for UPI description.

EMS Release 4 supports black and white pictures. All pictures are user defined – i.e. although they are either stored on the handset during manufacture, downloaded, or stored from other messages, they are called user-defined as the picture itself is sent over the air (see various ‘predefined’ media detailed below).

Simplewire's network will convert color GIF images into black and white automatically using a method that takes any color above 50% brightness and turning it to white, and anything below 50% brightness to black. So #999999 is converted to white, while #336699 is converted to black. Of course this example is representing colors using the standard web pallette, but you get the idea.

For exact image recreation, use Photoshop or another editing program to convert your image to black and white.

Animations

    # I am laughing
    $sms->emsAddPredefinedAnimation(7);

There are a number of predefined animations. These animations are not sent over the air interface, only the identification of them. Basically the originating terminal sends an instruction to the receiving terminal to play, say, pre-defined animation number 9.

As soon as the position of the animation in the SM data is reached, the animation corresponding to the received number is displayed in a manner which is manufacturer specific. Animations are played as soon they are focused. There are 6 predefined animations in Release 4.1.0 (0-5) of EMSI and additional 9 ones as of Release 4.3.0 (0-14) of EMSI. Please find an overview of all these predefined animations below:

Animation Description

    0 I am ironic, flirty
    1 I am glad
    2 I am sceptic
    3 I am sad
    4 WOW!
    5 I am crying
    6 I am winking
    7 I am laughing
    8 I am indifferent
    9 In love/ kissing
    10 I am confused
    11 Tongue hanging out
    12 I am angry
    13 Wearing glasses
    14 Devil

Sounds

These may be inserted into text messages to provide audible indications and experiences to the recipient. When they are received, they are played by the receiving handset at an appropriate point in the message.

Predefined

    # Play the Drums
    $sms->emsAddPredefinedSound(5);

There are a number of predefined sounds. These sounds are not transferred over the air interface, only the identification of them. There are 10 different sounds that can be added in the message, and as soon as the sound mark is in focus (on the display), the sound will be played.

Below please find an overview of all these predefined sounds:

    0 Chimes high
    1 Chimes low
    2 Ding
    3 Ta Da
    4 Notify
    5 Drum
    6 Claps
    7 Fan Fare
    8 Chords high
    9 Chords low

User Defined

    # Play my sound
    $sms->emsAddUserDefinedSound("MELODY:*5c5*5e4*5c5*5e4*4e5*4g4*4e5");

User defined sounds are sent over the air interface. They are monophonic only, use the iMelody format, and have a maximum length of 128 Bytes without the use of the UPI (see the UPI section below). Please note, we have found that many EMS phones do not support UPI for user defined melodies.

We have found that the following format, although based on the EMSI standard, bloats the melody data heavily, and is not needed. The MELODY: line item is typically all you need.

For example, this will work fine:

    MELODY:*5f3r4*5f4*5c4r4*5f1r3*4#g3*4a2*5c3*4f2r3*4a4*5c4*5f3

Rather than:

    BEGIN:IMELODY
        VERSION:1.2
        FORMAT:CLASS1.0
        NAME:A-Team Theme Song
        MELODY:*5f3r4*5f4*5c4r4*5f1r3*4#g3*4a2*5c3*4f2r3*4a4*5c4*5f3
        END:IMELODY

The official format of the iMelody is constituted of a header, the melody and a footer.

    Desc:      “BEGIN:IMELODY”<cr><line-feed>
    Example:   “BEGIN:IMELODY”<cr><line-feed>
    Status:    Mandatory

    Desc:      “VERSION:”<version><cr><line-feed>
    Example:   “VERSION:1.2”<cr><line-feed> 
    Status:    Mandatory (We've found this to be optional)

    Desc:      “FORMAT:”<format><cr><linefeed>
    Example:   “FORMAT:CLASS1.0”<cr><line-feed> 
    Status:    Mandatory (We've found this to be optional)

    Desc:      “NAME:”<characters-notlf><cr><line-feed>
    Example:   “NAME:My song”<cr><line-feed> 
    Status:    Optional

    Desc:      “COMPOSER:”<characters-notlf><cr><line-feed>
    Example:   “COMPOSER:John Doe”<cr><line-feed> 
    Status:    Optional

    Desc:      “BEAT:”<beat><cr><line-feed> 
    Example:   “BEAT:240”<cr><line-feed> 
    Status:    Optional

    Desc:      “STYLE:”<style><cr><line-feed>
    Example:   “STYLE:S2”<cr><line-feed> 
    Status:    Optional

    Desc:      “VOLUME:”<volume><cr><linefeed>
    Example:   “VOLUME:V8”<cr><line-feed> 
    Status:    Optional

    <format> ::= “CLASS1.0”
    iMelody also defines a "CLASS2.0" format.

    <beat>::="25" | "26" | "27" | ... | "899" | "900"
    <style>::= "S0" | "S1" | "S2"
    <volume-modifier>::=”V+”|”V-“ (changes volume + or – from current volume)
    <volume>::="V0" | "V1" | ... | "V15" |<volume-modifier>
    <characters-not-lf> ::= ’Any character in the ASCII character-set except <line-feed>.’
    Desc:      “END:IMELODY”<cr><line-feed> 
    Example:   “END:IMELODY”<cr><line-feed> 
    Status:    Mandatory

Melody

    Desc:      “MELODY:”<melody><cr><linefeed>
    Example:   “MELODY:c2d2e2f2”<cr><line-feed> 
    Status:    Mandatory

The melody is composed as follow: <melody> ::= { <silence> | <note> | <led> | <vib> | <backlight> | <repeat> | <volume> }+ <volume-modifier>::=”V+”|”V-“ (changes volume + or – from current volume) <volume>::="V0" | "V1" | ... | "V15" |<volume-modifier> <led> ::= “ledoff” | “ledon” <vibe> ::= “vibeon” | “vibeoff” <backlight> ::= “backon” | “backoff” <repeat> ::= “(“ | “)” | “@”<repeat-count> <repeat-count> ::= “0” | “1” | ... <silence> ::= “r”<duration>[<duration-specifier>] <note> ::= [<octave-prefix>]<basic-ess-iss-note><duration>[<duration-specifier>] <duration> := “0” | “1” | “2” | “3” | “4” | “5” <duration-specifier> ::= “.” | “:” | “;” <octave-prefix> ::= “*0” | “*1” | ... | “*8” (A=55Hz) | (A=110Hz) | ... | (A=14080Hz) <basic-ess-iss-note> ::= <basic-note> | <ess-note> | <iss-note> <basic-note> ::= “c’” | “d” | “e” | “f” | “g” | “a” | “b” <ess-note> ::= “&d” | “&e” | “&g” | “&a” | “&b” <iss-note> ::= “#c” | “#d” | “#f” | “#g” | “#a”

Duration

    Value Duration
    0     Full-note
    1     ½-note
    2     ¼-note
    3     1/8-note
    4     1/16-note
    5     1/32-note

Duration Specifier

    Value Duration
          No special duration
    .     Dotted note
    :     Double dotted note
    ;     2/3 length

The octave prefix only applies to the immediately following note. If not specified, the default octave-prefix is *4. i.e. A=880Hz.

The repeat blocks cannot be nested in this simple CLASS1.0 definition. The default character set is UTF-8.

The maximum length for a melody is 128 bytes (this includes the melody header and footer).

Example of a «CLASS1» iMelody object:

    Mandatory Header       BEGIN:IMELODY
                           VERSION:1.2
                           FORMAT:CLASS1.0
    Mandatory Melody       MELODY:&b2#c3V–c2*4g3d3V+#d1r3d2e2:d1V+f2f3.
    Mandotory Footer       END:IMELODY

Concatenation

    # Concatenate three SMS messages to make one
    # Each SMS can contain 140 bytes, and we've
    # added enough content to take up 320 bytes
    # 140 bytes - 1st message
    # 140 bytes - 2nd message
    # 40 bytes  - 3rd message
    $sms->emsAddUserPromptIndicator(3);

The Simplewire network supports concatenated EMS messages – the ability for the SMS handset to automatically combine several Short Messages. This feature is extremely useful because of the restrictions on the amount of information that an SMS can carry - in GSM the amount of information that can be carried within an SMS is only 140 bytes.

The handset is therefore able to both send and receive longer, richer messages. The Standard allows up to 255 messages to be concatenated into one, however, current phones support anywhere between 3 and 10 segments, and each handset should be investigated for its level of support.

User Prompt Indicator

This feature introduced in 3GPP TS 23.040 Release 4 allows handsets to stitch pictures and user-defined sounds. It also allows the user to be prompted upon reception of the message to execute media specific actions (storage, handset personalisation, etc.).

UNICODE

For Unicode characters in the range 0x00 to 0xFF, you can use the Perl hexadecimal escape sequence.

Format: \x##

Backslash + Lowercase 'x' + Two Hex Digits

Example: $r->msgText( "Uppercase Z: \x5A" );

For Unicode characters in the range 0x0000 to 0xFFFF, Simplewire provides its own escape sequence. This is only for use with the msgFrom and msgText methods.

Format: \\X####

Backslash + Backslash + Uppercase 'X' + Four Hex Digits

Example: $r->msgText( "Smiley Face: \\X263A" );

Note: Both sequences can be used in the same string. Example: $r->msgText( "Degree Sign: \xB0 \n Tilde: \\X007E" );

SEE ALSO

/Net-SMS-X.XX/examples/

/Net-SMS-X.XX/docs/sw-doc-manual-perl-2.4.0.pdf

Visit http://www.simplewire.com/

AUTHOR

Simplewire <support@simplewire.com> www.simplewire.com

COPYRIGHT

Please refer to License.txt within the Net-SMS-X.XX.tar.gz file for licensing information.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 2728:

Non-ASCII character seen before =encoding in 'Operator’s'. Assuming CP1252