4 Extended Web Services Binary SMS

The Extended Web Services Binary SMS Web Service allows for the sending and receiving of any generic binary content via SMS. Both application-initiated and network-triggered requests are supported. The binary content can be other than the Logos and Ringtones as specified by Parlay X Short Messaging. An example would be a vCard.

Namespaces

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 "Extended Web Services Common".

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).

Endpoints

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_notification/BinarySmsNotificationManager

The values for host and port depend on the specific Services Gatekeeper deployment.

Sequence Diagram

This section explains the sequence diagrams for sending and receiving an SMS.

Send SMS

The following diagram 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 4-1 Sequence diagram Application-initiated send Extended Web Services Binary SMS

Description of "Figure 4-1 Sequence diagram Application-initiated send Extended Web Services Binary SMS"

Receive SMS

The following diagram 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 4-2 Sequence diagram receive Extended Web Services Binary SMS

Description of "Figure 4-2 Sequence diagram receive Extended Web Services Binary SMS"

XML Schema data type definition

The following data structures are used in the Extended Web Services Binary SMS Web Service.

BinaryMessage structure

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 4-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.

BinarySmsMessage structure

Defines the binary payload of the SMS for network-triggered messages.

Table 4-2 BinarySmsMessage structure

Element Name	Element type	Optional	Description
message	ews_binary_sms_xsd:BinaryMessage[1..unbounded]	N	See "BinaryMessage structure".
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: http://www.3gpp.org/ftp/Specs/html-info/23040.htm 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:[phone]
smsServiceActivationNumber	xsd:anyURI	N	The destination address of the short message. Example: tel:1222
dateTime	xsd:dateTime	N	The timestamp of the message.

Interface: BinarySms

Operations to send SMSs with binary content.

Operation: sendBinarySMS

Sends an SMS with any binary data as content.

Input message: sendBinarySMS

Table 4-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. See http://www.smsforum.net/
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: http://www.3gpp.org/ftp/Specs/html-info/23040.htm 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. See http://www.smsforum.net/
charging	ews_common_xsd:ChargingInformation	Y	Charging information. See "ChargingInformation structure".
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. See "SimpleReference structure"

Output message: sendBinarySMSResponse

Table 4-4 Output message: sendBinarySMSResponse

Part name	Part type	Optional	Description
result	xsd:string	N	Identifies a specific SMS delivery request.

Referenced faults

Table 4-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

Interface: BinarySmsNotificationManager

Operations to start and stop subscriptions for notifications for short messages with binary content.

Operation: StartBinarySmsNotification

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 4-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. See "SimpleReference structure"
smsServiceActivationNumber	xsd:xsd:anyURI	Y	The destination address of the short message.

Output message: StartBinarySmsNotificationResponse

Table 4-7 Output message: StartBinarySmsNotificationResponse

Part name	Part type	Optional	Description
N/A	N/A	N/A	N/A

Referenced faults

Table 4-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

Operation: StopBinarySmsNotification

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 4-9 Input message: StopBinarySmsNotification

Part name	Part type	Optional	Description
correlator	xsd:String	N	The identifier for the subscription.

Output message: StopBinarySmsNotificationResponse

Table 4-10 Output message: StopBinarySmsNotificationResponse

Part name	Part type	Optional	Description
N/A	N/A	N/A	N/A

Referenced faults

Table 4-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

Interface: BinarySmsNotification

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.

Operation: NotifyBinarySmsReception

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 4-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. See "BinarySmsMessage structure".

Output message: NotifyBinarySmsReceptionResponse

Table 4-13 Output message: NotifyBinarySmsReceptionResponse

Part name	Part type	Optional	Description
N/A	N/A	N/A	N/A

Referenced faults

None.

WSDLs

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_notification/wsdls/ews_binary_sms_notification_service.wsdl
http://host:port/ews/binary_sms_notification/wsdls/ews_binary_sms_notification_interface.wsdl

Where host and port are depending on the Services Gatekeeper deployment.

Error Codes

The following error codes are defined for SVC0001: Service error:

• See "General error codes".

• 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".

Sample Send Binary SMS

Example 4-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);