This chapter explains how to use the Oracle Communications Services Gatekeeper binary SMS extended web service interface to add binary SMS support to applications.
The Extended Web Services Binary SMS Web Service allows for the sending and receiving of any generic binary content through SMSs. Both application-initiated and network-triggered requests are supported. The binary content can include data beyond the logos and ringtones specified by Parlay X Short Messaging. Examples of supported binary content include vCards, calendar entries, and WAP Push messages.
The Extended Web Services Binary SMS Web Service supports the automatic chunking of oversized binary SMS messages to handle messages that exceed the maximum size of a single SMS request. Oversized unsegmented messages are automatically divided into size conforming individual messages and handled by Services Gatekeeper if the proper encoding is provided in the message header.
The BinarySMS interface and service use the namespaces:
http://www.bea.com/wlcp/wlng/wsdl/ews/binary_sms/interface
http://www.bea.com/wlcp/wlng/wsdl/ews/binary_sms/service
The BinarySmsNotificationManager interface and service use the namespaces:
http://www.bea.com/wlcp/wlng/wsdl/ews/binary_sms/notification/interface
http://www.bea.com/wlcp/wlng/wsdl/ews/binary_sms/notification/service
In addition, Extended Web Services Binary SMS uses common data type definitions common for all Extended Web Services interfaces, see "Understanding the Extended Web Services Common Definitions".
Fault definitions are according to ETSI ES 202 391-1 V1.2.1 (2006-10) Open Service Access (OSA); Parlay X Web Services; Part 1: Common (Parlay X 2).
The endpoint for the BinarySMS interface is: http://<host:port>/ews/binary_sms/BinarySms
The endpoint for the BinarySmsNotificationManager interface is: http://
host:
port/ews/binary_sms/BinarySmsNotificationManager
Where the values for host and port depend on your specific Services Gatekeeper deployment.
This section explains the sequence diagrams for sending and receiving an SMS.
Figure 32-1 shows the general message sequence for sending a binary SMS message from an Extended Web Services Binary SMS application to the network. In this message sequence the application also receives a notification from the network indicating the delivery status of the SMS, that is that the message has reached its destination. It also displays how an application can query the delivery status of the message.
The interaction between the network and Services Gatekeeper is illustrated in a protocol-agnostic manner. The exact operations and sequences depend on which network protocol is being used.
Note:
The delivery notifications are sent from the Parlay X 2.1 Short Messaging implementation.Figure 32-1 Sequence diagram Application-initiated send Extended Web Services Binary SMS
Figure 32-2 shows the general message sequence for receiving a binary SMS message from the Network using Services Gatekeeper. In this message sequence the application also subscribes for a notifications on network triggered short messages.
The interaction between the network and Services Gatekeeper is illustrated in a protocol-agnostic manner. The exact operations and sequences depend on which network protocol is being used.
Figure 32-2 Sequence diagram receive Extended Web Services Binary SMS
The following data structures are used in the Extended Web Services Binary SMS Web Service.
Defines the binary payload of the SMS for application-initiated messages.
Defines the TP-User Data (TP-UD).
For a description of TP-User Data (TP-UD), TP-User-Data-Header-Indicator (TP UDHI), see 3GPP TS 23.040 V6.5.1, Technical realization of the Short Message Service (SMS) at:
http://www.3gpp.org/ftp/Specs/html-info/23040.htm
Table 32-1 BinaryMessage structure
Element Name | Element type | Optional | Description |
---|---|---|---|
udh |
xsd:base64Binary |
Y if message is set, otherwise N |
Defines the User Data Header. See the description of TP-User Data (TP-UD) in the 3GPP specification for information about how to format the User Data Header. |
message |
xsd:base64Binary |
Y if udh is set, otherwise N |
Binary message data. Must be formatted according to TP-User Data (TP-UD), excluding the User Data Header. |
Defines the binary payload of the SMS for network-triggered messages.
Table 32-2 BinarySmsMessage structure
Element Name | Element type | Optional | Description |
---|---|---|---|
message |
ews_binary_sms_xsd:BinaryMessage[1..unbounded] |
N |
|
dcs |
xsd:byte |
N |
Data code schema, according to SMPP v3.4. |
protocolId |
xsd:byte |
Y |
TP-Protocol-Identifier according to 3GPP 23.040 6.5.1. Defines the TP-User Data (TP-UD). For a description of TP-User Data (TP-UD), TP-User-Data-Header-Indicator (TP UDHI), see 3GPP TS 23.040 V6.5.1, Technical realization of the Short Message Service (SMS) at:
The protocol identifier is the information element by which the short message transport layer either refers to the higher layer protocol being used, or indicates interworking with a certain type of telematic device. Example: 123 |
senderAddress |
xsd:anyURI |
N |
The address of the sender of the short message. Example: tel:1234556 |
smsServiceActivationNumber |
xsd:anyURI |
N |
The destination address of the short message. Example: tel:1222 |
dateTime |
xsd:dateTime |
N |
The timestamp of the message. |
Operations to send SMSs with binary content.
Sends an SMS with any binary data as content.
Input message: sendBinarySMS
Table 32-3 Input message: sendBinarySMS
Part name | Part type | Optional | Description |
---|---|---|---|
addresses |
xsd:anyURI[1..unbounded] |
N |
An array of end-user terminal addresses. Example: tel:1234 |
senderName |
xsd:string |
Y |
The name of the sender. Alphanumeric. Example: tel:7485, Mycompany. |
dcs |
xsd:byte |
N |
Defines the data encoding scheme for the binaryMessage parameter. Formatted according to data_coding parameter in SMPP v3.4. |
binaryMessage |
binary_sms_xsd:BinaryMessage[1..unbounded] |
N |
Message payload. An array comprised of UDH elements and message elements, see "BinaryMessage structure". This array must be equal to or less than 140 bytes in size. |
protocolId |
xsd:byte |
Y |
TP-Protocol-Identifier (TP-PID) according to 3GPP TS 23.040 V6.5.1, Technical realization of the Short Message Service (SMS) at:
Specifies the higher layer protocol being used, or indicates interworking with a certain type of telematic device. |
validityPeriod |
xsd:string |
Y |
Defines the validity period for the short message. Formatted according to validity_period parameter in SMPP v3.4. |
charging |
ews_common_xsd:ChargingInformation |
Y |
Charging information. |
receiptRequest |
ews_common_xsd:SimpleReference |
Y |
It defines the application endpoint, interfaceName and correlator that will be used to notify the application when the message has been delivered to the terminal or if delivery is impossible. |
Output message: sendBinarySMSResponse
Table 32-4 Output message: sendBinarySMSResponse
Part name | Part type | Optional | Description |
---|---|---|---|
result |
xsd:string |
N |
Identifies a specific SMS delivery request. |
Referenced faults
Table 32-5 exceptions and error codes
Exception | Error code | Reason/Action |
---|---|---|
SVC0001 |
BSMS-000001 |
Unable to perform action. Network error |
SVC0001 |
BSMS-000002 |
Unable to retrieve configuration, internal error. |
SVC0001 |
BSMS-000003 |
The used address type is not supported |
SVC0001 |
BSMS-000004 |
Unable to encode message segments. make sure the number of message segments is not 0. |
SVC0001 |
BSMS-000005 |
GSM message format error. |
SVC0001 |
BSMS-000006 |
Binary Message has too many segments. |
SVC0001 |
PLG-000004 |
General plug-in routing error. |
SVC0002 |
N/A |
SenderName in non-alphanumeric format. |
SVC0003 |
N/A |
N/A |
SVC0004 |
N/A |
N/A |
SVC0005 |
N/A |
N/A |
EPOL0001 |
N/A |
N/A |
Operations to start and stop subscriptions for notifications for short messages with binary content.
Starts a subscription for notifications for short messages that have content in the form of binary data. A correlator is provided in the request. This correlator is used when stopping the subscription.
Input message: StartBinarySmsNotification
Table 32-6 Input message: StartBinarySmsNotification
Part name | Part type | Optional | Description |
---|---|---|---|
reference |
ews_common_xsd:SimpleReference |
N |
Defines the application endpoint, interfaceName and correlator that will be used to forward a binary short message from the network. |
smsServiceActivationNumber |
xsd:xsd:anyURI |
Y |
The destination address of the short message. |
Output message: StartBinarySmsNotificationResponse
Table 32-7 Output message: StartBinarySmsNotificationResponse
Part name | Part type | Optional | Description |
---|---|---|---|
N/A |
N/A |
N/A |
N/A |
Referenced faults
Table 32-8 exceptions and error codes
Exception | Error code | Reason/Action |
---|---|---|
SVC0001 |
BSMS-000001 |
Unable to perform action. Network error |
SVC0001 |
BSMS-000002 |
Unable to retrieve configuration, internal error. |
SVC0001 |
BSMS-000003 |
The used address type is not supported |
SVC0001 |
BSMS-000004 |
Unable to encode message segments. make sure the number of message segments is not 0. |
SVC0001 |
BSMS-000005 |
GSM message format error. |
SVC0001 |
BSMS-000006 |
Binary Message has too many segments. |
SVC0001 |
PLG-000004 |
General plug-in routing error. |
SVC0002 |
N/A |
N/A |
SVC0003 |
N/A |
N/A |
SVC0004 |
N/A |
N/A |
SVC0005 |
N/A |
N/A |
EPOL0001 |
N/A |
N/A |
Stops a previously started subscription for notifications for short messages that have content in the form of binary data. A correlator is provided in the request. This correlator was provided when the subscription was started, see "Operation: StartBinarySmsNotification".
Input message: StopBinarySmsNotification
Table 32-9 Input message: StopBinarySmsNotification
Part name | Part type | Optional | Description |
---|---|---|---|
correlator |
xsd:String |
N |
The identifier for the subscription. |
Output message: StopBinarySmsNotificationResponse
Table 32-10 Output message: StopBinarySmsNotificationResponse
Part name | Part type | Optional | Description |
---|---|---|---|
N/A |
N/A |
N/A |
N/A |
Referenced faults
Table 32-11 exceptions and error codes
Exception | Error code | Reason/Action |
---|---|---|
SVC0001 |
BSMS-000001 |
Unable to perform action. Network error |
SVC0001 |
BSMS-000002 |
Unable to retrieve configuration, internal error. |
SVC0001 |
BSMS-000003 |
The used address type is not supported |
SVC0001 |
BSMS-000004 |
Unable to encode message segments. make sure the number of message segments is not 0. |
SVC0001 |
BSMS-000005 |
GSM message format error. |
SVC0001 |
BSMS-000006 |
Binary Message has too many segments. |
SVC0001 |
PLG-000004 |
General plug-in routing error. |
SVC0002 |
N/A |
N/A |
SVC0003 |
N/A |
N/A |
SVC0004 |
N/A |
N/A |
SVC0005 |
N/A |
N/A |
EPOL0001 |
N/A |
N/A |
This interface is implemented by the application. It is used by Services Gatekeeper to deliver short messages with binary content to an application. Only messages that match a previously started subscription for notifications are delivered.
Note:
Notifications on delivered short messages are delivered using the Parlay X 2.1 Short Messaging SmsNotification interface, using the method NotifySmsDeliveryReceipt.Services Gatekeeper calls this methods on
The notification is used to send a short message with binary content to the application. The notification occurs if the short message matched the criteria specified when starting the notification. See "Operation: StartBinarySmsNotification".
The method must be implemented by a Web Service at the application side. It is be invoked by Services Gatekeeper when it receives a short message with binary content form the network and the criteria is fulfilled.
Input message: NotifyBinarySmsReceptionRequest
Table 32-12 Input message: NotifyBinarySmsReceptionRequest
Part name | Part type | Description |
---|---|---|
correlator |
xsd:String |
The correlator for the subscription. |
message |
ews_binary_sms_xsd:BinarySmsMessage |
The message in binary form. |
Output message: NotifyBinarySmsReceptionResponse
Table 32-13 Output message: NotifyBinarySmsReceptionResponse
Part name | Part type | Optional | Description |
---|---|---|---|
N/A |
N/A |
N/A |
N/A |
Referenced faults
None.
This interface includes a feature that automatically separates oversize SMS messages into smaller segments so that even switches that limit the size of SMSs will support them. This feature works for SMS messages that use either user data header (UDH) headers, or Sar_ headers. Each chunk gets its own header segment, so your switches treat them a separate SMS messages.
You use the wlng.smpp.concatenated_message_indicator Services Gatekeeper system property to select the type of header you use. 0 is the default value. It indicates UDH headers. Change this setting to 1 if your implementation processes SMSs with Sar_ headers.
This feature follows the 3GPP TS 23.038 and 3GPP TS 23.040 specifications for UDH and the SMPPv3.4 specification for Sar.
The document/literal WSDL representation of the interfaces can be retrieved from the Web Services endpoints, see "Endpoints".
The notification interface can be downloaded from:
http://host:port/ews/binary_sms/wsdls/ews_binary_sms_notification_service.wsdl http://host:port/ews/binary_sms/wsdls/ews_binary_sms_notification_interface.wsdl
Where the values for host and port depend on the Services Gatekeeper deployment.
The following error codes are defined for SVC0001: Service error:
Error codes defined for Parlay X 2.1 Short Messaging, see "Error Codes".
16133 Too many segments in message.
The following error codes are defined for EPOL0001: Policy error:
See "Code Examples".
Policy error codes defined for Parlay X 2.1 Short Messaging, see "Error Codes".
Example 32-1 Example Send Binary SMS
BinarySmsService service = new BinarySmsService_Impl(”http://localhost:8001/ews/binary_sms/BinarySms?WSDL”); BinarySms port = service.getBinarySms(); com.bea.wlcp.wlng.schema.ews.binary_sms.local.SendBinarySms parameters = new com.bea.wlcp.wlng.schema.ews.binary_sms.local.SendBinarySms(); URI[] addresses = new URI[1]; addresses[0] = new URI("tel:1234"); parameters.setAddresses(addresses); parameters.setDcs((byte)0); parameters.setProtocolId((byte)0x7b); parameters.setSenderName("tel:7878"); parameters.setValidityPeriod("020610233429000R"); com.bea.wlcp.wlng.schema.ews.binary_sms.BinaryMessage[] binaryMessages = new com.bea.wlcp.wlng.schema.ews.binary_sms.BinaryMessage[1]; binaryMessages[0] = new com.bea.wlcp.wlng.schema.ews.binary_sms.BinaryMessage(); byte[] udh = {0}; byte[] message = {0x4d, 0x61, 0x64, 0x65, 0x20, 0x69, 0x6e, 0x20, 0x2e}; binaryMessages[0].setUdh(udh); binaryMessages[0].setMessage(message); parameters.setBinaryMessage(binaryMessages); port.sendBinarySms(parameters);