API Description for Parlay X
SMS
The following sections describe the SMS API used for sending and receiving SMS:es:
Send SMS API
sendSms
Send an SMS to one or several destinations.
Table 6-1 sendSms (destAddressSet, senderName, charging, message)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
destAddressSet
|
EndUserIdentifier[]
|
Array of EndUserIdentifier.
MSISDN of the destination terminal(s).
|
|
senderName
|
String
|
Format is tel:<mailbox ID>\<mailbox password>\tel:<originator address>
Mailbox ID and password are supplied by the service provider.
Example:
"tel:50000\apassword\tel:+46541768700"
|
|
charging
|
String
|
Optional.
|
|
message
|
String
|
Message.
For GSM systems, if containing characters not in the GSM 7-bit character set, the SMS is sent as a Unicode SMS.
If longer than the maximum supported length (for example. for GSM, 160 GSM 7-bit characters or 70 Unicode characters), the message will be sent as several concatenated short messages.
|
|
Returns
|
|
|
String
|
ID of the SMS delivery request.
|
|
Possible exceptions
|
|
UnknownEndUserException
|
|
ServiceException
|
|
InvalidArgumentException
|
|
MessageTooLongException
|
|
PolicyException
|
sendSmsLogo
Send an SMS logo to one or several destinations.
Table 6-2 sendSmsLogo (destAddressSet, senderName, charging, image, smsFormat, message)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
destAddressSet
|
EndUserIdentifier[]
|
Array of EndUserIdentifier.
MSISDN of the destination terminal(s).
|
|
senderName
|
String
|
Format is tel:<mailbox ID>\<mailbox password>\tel:<originator address>
Mailbox ID and password are supplied by the service provider.
Example:
"tel:50000\apassword\tel:+46541768700"
|
|
charging
|
String
|
Optional.
|
|
image
|
Base64Binary
|
The image/logo to send. See Handling of SMS Logos for a description of the different formats supported. Note that the image encoding must be according to the one stated in the parameter smsFormat.
|
|
smsFormat
|
smsFormat
|
Possible values are:
[EMS | SmartMessaging]
EMS for EMS message
SmartMessaging for Smart Messaging messages.
|
|
Returns
|
|
|
String
|
ID of the SMS delivery request.
|
|
Possible exceptions
|
|
UnknownEndUserException
|
|
ServiceException
|
|
InvalidArgumentException
|
|
MessageTooLongException
|
|
PolicyException
|
|
UnsupportedFormatException
|
sendSmsRingtone
Send an SMS ringtone to one or several destinations.
Table 6-3 sendSmsRingtone (destAddressSet, senderName, charging, ringtone, smsFormat, message)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
destAddressSet
|
EndUserIdentifier[]
|
Array of EndUserIdentifier.
MSISDN of the destination terminal(s).
|
|
senderName
|
String
|
Format is tel:<mailbox ID>\<mailbox password>\tel:<originator address>
Mailbox ID and password are supplied by the service provider.
Example:
"tel:50000\apassword\tel:+46541768700"
|
|
charging
|
String
|
Optional.
|
|
ringtone
|
String
|
See Handling of SMS Ringtones for a description of the different formats supported. Note that the ringtone encoding must be according to the one stated in the parameter smsFormat.
|
|
smsFormat
|
smsFormat
|
Possible values are:
[EMS | SmartMessaging]
EMS for EMS message
SmartMessaging for Smart Messaging messages.
|
|
Returns
|
|
|
String
|
ID of the SMS delivery request.
|
|
Possible exceptions
|
|
UnknownEndUserException
|
|
ServiceException
|
|
InvalidArgumentException
|
|
MessageTooLongException
|
|
|
|
UnsupportedFormatException
|
getSmsDeliveryStatus
Requests the status of a previous SMS delivery request identified by requestIdentifier.
Table 6-4 getSmsDeliveryStatus(requestIdentifier)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
requestIdentifier
|
String
|
ID of the SMS delivery request.
|
|
Returns
|
|
|
DeliveryStatusType[]
|
Array of DeliveryStatusType.
Each entry in the array corresponds to a destination address as given when the message was sent.
See DeliveryStatusType.
|
|
Possible exceptions
|
|
UnknownRequestIdentifierException
|
|
ServiceException
|
SMS notification API
notifySmsReception
When an SMS arrives to WebLogic Network Gatekeeper, a SOAP request with this operation, will be invoked to the server-side of the Parlay X client.
This method must be implemented on the server-side of the Parlay X client.
WebLogic Network Gatekeeper must be aware of the location of the Web Service implementing this interface. The location of the web service is defined using OAM in WebLogic Network Gatekeeper.
Table 6-5 notifySmsReception( registrationIdentifier, smsServiceActivationNumber, senderAddress, message)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
registrationIdentifier
|
String
|
ID of the mailbox.
|
|
smsServiceActivationNumber
|
String
|
Address to service.
|
|
senderAddress
|
EndUserIdentifier
|
Sender address.
|
|
message
|
String
|
Message. Up to 160 characters.
|
|
Returns
|
|
Void
|
|
|
|
Possible exceptions
|
|
ApplicationException
|
Receive SMS API
getReceivedSms
Gets all SMS:es received to a mailbox since last invocation of the methods on the mailbox.
Table 6-6 getReceivedSms(registrationIdentifier)
|
Parameter Name
|
Type
|
Description
|
|
Input
|
|
|
|
registrationIdentifier
|
String
|
The mailbox.
Format is <mailbox ID>\<mailbox password>
Mailbox ID and password are supplied by the service provider.
Example:
"tel:50000\apassword"
|
|
Returns
|
|
|
|
|
SmsType[]
|
Array of SMSType.
Lists of SMS:es received SMS since last invocation.
|
|
Possible exceptions
|
|
UnknownRegistrationIdentifierException
|
|
ServiceException
|
Data Types
Table 6-7 Data types specific for SMS
|
Data type
|
Description
|
|
|
DeliveryStatusType
|
Structure containing the following parameters:
|
|
|
destinationAddress
|
It indicates the destination address to which the notification is related
Datatype: EndUserIdentifier.
|
|
|
deliveryStatus
|
Indicates the delivery result for destinationAddress.
Possible values are: [Delivered |DeliveryUncertain | DeliveryImpossible]
Datatype: DeliveryStatus
|
|
|
|
|
|
DeliveryStatus
|
The DeliveryStatus data type is an enumeration with the following values:
|
|
|
Delivered
|
Successful delivery.
In case of concatenated messages, only when all the SMS-parts have been successfully delivered.
|
|
|
DeliveryUncertain
|
Cannot resolve status. For example, because it was handed off to another network.
|
|
|
DeliveryImpossible
|
Unsuccessful delivery; the message could not be delivered before it expired.
|
|
|
MessageWaiting
|
The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
|
|
SmsType
|
Structure containing the following parameters:
|
|
|
message
|
Text received in SMS.
Datatype: String
|
|
|
senderAddress
|
It indicates address sending the SMS.
Datatype: EndUserIdentifier
|
|
SmsFormat
|
Enumeration with the following values:
|
|
|
Ems
|
Enhanced Messaging Service, standardized in 3GPP TS 23.040, which defines a logo/ringtone format.
|
|
|
SmartMessaging
|
Nokia's de facto standard, which defines a logo/ringtone format.
|
Exceptions
Table 6-8 Exceptions specific for SMS
|
ID
|
Exception
|
Description
|
|
SMS1000E
|
UnsupportedFormatException
|
The smsFormat supplied is not one of the permitted values of the SmsFormat data type.
|
|
SMS1001E
|
UnknownRegistrationIdentifierException
|
The registrationIdentifier supplied is not known by the server
|
|
SMS1002E
|
UnknownRequestIdentifierException
|
The requestIdentifier supplied does not relate to any known SMS request or has expired.
|
Handling of SMS Logos
Smartmessaging
Logos sent in Smartmessaging format will result in Nokia operator logos being sent to the handset. The subscriber must be registered in it's home network.
Formats supported:
- Standard: 72x14 pixels, monochrome bitmap
- Bigger: 78x21, monochrome bitmap
The image is sent as an hexadecimal string with a leading Mobile Country Code (MCC) and the Mobile Network Code (MNC):
<MCC><NCC><image data>
<MCC> is a 3-digit decimal value, that should be encoded as little endian BCD, resulting in two octets with "f" as filler.
<NCC> is a 2-digit decimal value, that should be encoded as little endian BCD, resulting in one octet.
For example, if the MCC is 240 and NCC is 01, <MCC> will be 42F0 and <NCC> will be 10. The resulting hexadecimal string will be 42F010<image data>.
Below is an example of tools and the procedure to code the hexadecimal string to be used when sanding the logos.
- Start with a monochrome bitmap image in the correct dimensions.
- Convert it to a wireless bitmap image (WBMP). A converter can be found at
http://elvis.teraflops.com/wbmp
- The WBMP a should be converted to a hexadecimal string. A converter can be found at
http://www.clickatell.com/central/skins/converters/convert_bitmaps.php
- Add the Mobile Country Code (MCC) and the Mobile Network Code (MNC) first in the string as described above. Values for MCC and MNC can be found at
http://www.gsmworld.com/roaming/gsminfo
EMS
Formats supported:
- Small Picture
- Large Picture
Only pictures that can be fitted into one SMS are supported.
The picture should be encoded as a hexadecimal string according to format specified in the Ericsson document Developer's Guidelines, Enhanced Messaging Service (EMS), EN/LZT 103 5256 R6A.
Handling of SMS Ringtones
Smartmessaging
Hexadecimal string representing a ringtone.
A tool for converting midi-files to Nokia ringtones is found at
http://www.clickatell.com/central/skins/converters/convert_mid.php
EMS
Hexadecimal string representation of an iMelody.
See http://www.irda.org/standards/specifications.asp
for a specification of the format.
