The messaging protocols, including the proprietary MGP, all include functionality to send and receive messages.
In general, messages are kept in the queue for the connector through which it should be sent until successfully sent or until a permanent error has occurred. Most errors are considered temporary though and will cause the message to stay in queue for further delivery attempts. When a temporary error has occurred for a message it is put in the end of the queue in order for other messages to be delivered meanwhile. It is possible to specify a maximum number of delivery attempts after which the message will be considered undeliverable and will be removed from the queue.
Using an HTTP connector
When EMG sends a message to an HTTP server or similar, it uses the URL defined by the ADDRESS keyword and adds options as HTTP parameters to form a complete GET or POST request depending on the DEFAULT_SMSCOP setting for the connector.
The response to the request must be 200 (OK) in order for the message to be considered delivered successfully.
When sending binary messages or UDH the message data will be hex encoded.
EMG supports persistent HTTP/1.1 connections.
EMG supports HTTP basic authentication using the XAUTH* keywords.
Using an SMTP connector
When EMG sends a message using an outgoing SMTP connector this is done via a standard SMTP session using some special mappings for the options associated with the message.
| SOURCEADDR | Put into the MAIL FROM address. |
| DESTADDR | Put into the RCPT TO address. |
| MESSAGE | Put into the DATA body. |
All other message options are put into the message header as X-EMG-Option-<option> user-defined headers.
There are also a few specific connector keywords used by the outgoing SMTP connector:
QUOTEDSUBJECT=c1c2This indicates that the message may include a subject and that the subject is enclosed using the characters c1 and c2 respectively.
Example:
If the keyword is used as follows:
QUOTEDSUBJECT=()and the message body is
(This is the subject) …and this is message body
the subject of the message will be set to “This is the subject” and the message body will be “…and this is the message body”.
Outgoing messages are MIME encoded as text/plain using the ISO8859-1 character set.
EMG supports persistent SMTP connections using the RSET command.
EMG supports SMTP authentication using the XAUTH* keywords.
Sample outgoing SMTP session
Remote SMTP server lines begin with `>’.
>220 host.domain.com ESMTP
HELO nordicmessaging.se
>250 Please to meet you
MAIL FROM:<123456@nordicmessaging.se>
>250 Sender ok
RCPT TO:<987654@domain.com>
>250 Recipient ok
DATA
>354 Enter mail, end with "." on a line by itself
From: 123456@nordicmessaging.se
To: 987654@domain-com
X-EMG-Option-SOURCEADDR: 12345
This is the actual message!
.
>250 Message accepted for delivery
QUIT
>221 Closing connectionAll message options can be used using the “X-EMG-Option-xxx:” user-defined headers. The UDH, if present in the message, will also be sent using a user-defined header with the UDH data hex encoded.
If successful, the message id is returned in the SMTP DATA command response.
When sending binary messages or UDH the message data must be hex encoded.
Using an EBE connector
The EBE connector does not really send the message but rather forwards it to a script or program which will be executed with message information on standard input. This enables the user to invoke external programs and facilitates integration with third-party solutions.
The format of the message information will be two fields per row, where the first field is the message option key (a numeric value) and the second field is the actual value of the option. The fields are tab-separated.
1<TAB>1003
34<TAB>127.0.0.1
30<TAB>emguser
2<TAB>123456
8<TAB>56789
16<TAB>414243The first row indicates that the message id is 1003 (message option 1). The second row that it was received from a client that connected from the IP 127.0.0.1 (localhost). See MGP options chapter for more information about message options.
The exit code of the script is used to indicate whether the delivery was successful or not. An exit code of 0 indicates success, 1 a permanent error and all other exit codes temporary errors (message is kept in queue for new retries).
Sample script:
#!/bin/sh
tmpfile=/tmp/ebe.$$
# Default exit code is 0 (OK)
ret=0
# Write message information to file.
# If cat fails set exit code to non-zero
cat >$tmpfile || ret=1
exit $retUsing emgsend
The utility emgclient implements the MGP protocol and can be used to send messages from the command-line. It checks client.cfg and command-line arguments for server, port and authentication information. The assigned message id will be displayed on standard output by default.
Example sending a plain text message using emgsend.
emgsend -username emguser -password secret -o ROUTE=smsc1-ucp 070123456 "This is a test message"Default values for host, port, username and password are taken from the client.cfg file.
Example sending a ringtone using to a Nokia phone (Nokia Smart Messaging). It is addressed to port 5505 in the phone and CHARCODE=2 indicates a binary message. The message is more than 160 octets so it will be split and 2 SMS will be sent to the phone.
The command-line is split over multiple lines. There is no space between the last digit and the trailing backslash.
emgsend -hex -o SOURCEPORT=0 -o DESTPORT=5505 \
-o CHARCODE=2 461234567 \
0C0106050415811581024A3A6505899195B185E995C80400E4D9\
0413220B1106889268495624B31261892CC4956249B124889348\
493624B31269892CC493424D112610922C495624C31255892284\
9A224B210718926C4966249B107109304495420D31249892AC49\
1620D21258892AC496624AB124D89248496424AB1259892AC493\
620D2124D0924C493624AB124D8926400001Example sending Over The Air settings to an Ericsson T68 phone. It is addressed to port 49999 in the phone and CHARCODE=2 indicates a binary message. The message is more than 160 octets so it will be split and 2 SMS will be sent to the phone.
emgsend -hex -o SOURCEPORT=49154 -o DESTPORT=49999 \
-o CHARCODE=2 461234567 \
01062C1F2A6170706C69636174696F6E2F782D7761702D70726F\
762E62726F777365722D73657474696E67730081EA01016A0045\
C6060187124901871311033132332E34352E362E370001871C11\
03736F6E6F666F6E2E636F6D0001872270010186071103687474\
703A2F2F7761702E646B0001C6080187151103414243000101C6\
7F0187151103576170000187171103687474703A2F2F7761702E\
646B00010101Using emgclient
The utility emgclient can be used to send, query and delete messages and a few other administrative tasks. Online help is available.