Content Provider Access
CPA
Protocol specification and how to get started
This document specifies how to communicate with Telenor Mobile’s Content Provider Access (CPA).
Revision Log
Version
Date
Description
0.1
05.09.00
Version 0.1 – Preliminary Draft
1.0
12.03.01
Version 1.0 – Positioning Project
1.1
05.12.01
Added reply codes, Info on long/lat field, new pos result codes, flash messages,
new price categories, new message types
2.0
11.03.02
Version 2.0 – Added new functionality
2.1
24.10.02
Updated with positioning stuff and binary messages
2.2
24.04.03
Updated to support PMS 2.0
2.3
22.09.02
Updated to support new StaticId
3.0
09.03.04
Version 3.0 – Added new SMSC functionality and CPSC (Content Provider
Subscription Centre) support
3.1
20.04.05
Updated – removed support for PMS, added connection testing
3.2
01.08.05
Updated – added new acknowledge-code
3.3
01.02.06
Updated – added new field
3.4
09.05.06
Updated – added new pricecatgories CPA6900-CPA10000
3.5
25.09.06
Updatetd – added new parameter BusinessModel
3.6
08.11.06
Updated with concatenated MO example
3.7
29.01.07
Updated with support for age and priceplan check
4.0
22.06.07
Updated with Sonic MQ client API v. 5.0 – See appendix A – changes marked red
4.1
07.09.07
Updated with support for “Age16” parameter for age check
Contents
1
INTRODUCTION .................................................................................................. 1
2
ARCHITECTURE OVERVIEW ............................................................................. 2
3
SECURITY ........................................................................................................... 3
3.1
3.2
4
Firewalls ..................................................................................................................................................... 3
Authentication, Privacy and Integrity ..................................................................................................... 3
MESSAGE FLOW ................................................................................................ 4
4.1
Sending messages to CPA ......................................................................................................................... 4
4.2
Receiving messages from CPA ................................................................................................................. 5
4.3
Performance considerations ..................................................................................................................... 5
4.4
Messages from CPA to Content Provider ............................................................................................... 6
4.4.1
MSG_FROM_OP_SMSC ................................................................................................................... 6
4.4.2
MSG_FROM_OP_CP ......................................................................................................................... 7
4.4.3
MSG_FROM_OP_ACK ..................................................................................................................... 7
4.5
Messages from Content Provider to CPA ............................................................................................... 8
4.5.1
MSG_TO_OP_SMSC ......................................................................................................................... 8
4.5.2
MSG_TO_OP_CP ............................................................................................................................. 11
5
REPLY CODES IN ACKNOWLEDGEMENTS ................................................... 12
6
MESSAGE TYPES ............................................................................................. 15
6.1
Mobile Terminated (MT) Binary messages (Nokia specific) ............................................................... 15
6.1.1
Type “binary” .................................................................................................................................... 15
6.1.2
Type ”binary_simple” ....................................................................................................................... 17
6.2
Mobile Terminated (MT) Flash messages ............................................................................................. 17
6.3
Mobile Terminated (MT) XtraService messages (xs) ........................................................................... 18
6.3.1
XSer type of service 01, GSM UDH information ............................................................................. 18
6.3.2
XSer type of service 02, GSM DCS information .............................................................................. 19
6.4
Mobile Originated (MO) binary messages (e.g. concatenated messages) ........................................... 19
7
7.1
8
8.1
PRICE GROUPS AND BILLING OF MESSAGES ............................................. 21
Billing of long messages (binary and text) ............................................................................................. 22
AGE AND PRICEPLAN CHECK ........................................................................ 22
General information ................................................................................................................................ 22
APPENDIX A – SONICMQ JAVA API .................................................................... 23
APPENDIX B – JAVA SAMPLE IMPLEMENTATION ............................................ 25
APPENDIX C – C SAMPLE IMPLEMENTATION .................................................... 28
APPENDIX D – TESTING THE CONNECTION ....................................................... 29
Content Provider Access
1 Introduction
CPA (Content Provider Access, formerly MSB) is a gateway for SMS-messages between two types of users:

Content providers

End users (mobile telephone users)
CPA offers transmission and administration of messages between these two types of users, and offers billing
capabilities during the transmission of the messages.
To support positioning services 1, the content provider can get access to a separate positioning platform with the
product POS Access.
The main focus of this document is to explain the communication between the CPA-platform and the content
providers. This communication is handled by a Java Messaging System (JMS) implementation, SonicMQ, from
Progress Software.
For those familiar with the YAP message format (the former protocol used for communication with CPA), the
message format is about the same. That is, the content of the messages is more or less as before, but the medium
of communication has changed.
The first section of this document will explain the security considerations in the communication between Telenor
Mobil and the content providers. Then the message flow and the message format will be examined. After a
general presentation of messages, binary message representation in CPA will be explained in detail because this
is somewhat different from sending normal textual messages.
Then the pricing of messages and the billing capabilities in the CPA platform are handled.
In Appendix B – Java Sample Implementation you will find example code, and a working implementation that
shows how to communicate with the CPA system. Telenor Mobil also provides a GUI application that can be
used to send and receive messages during debugging and testing, see Appendix B – Java Sample
Implementation.
1
The positioning service is not a part of a standard CPA contract. To get access to the positioning platform, the
content providers must take out a new contract with Telenor Mobil.
1
Content Provider Access
2 Architecture Overview
CP1
CP2
CPx
Positioning
Gateway
Load
Balancing
CPA
App 1
CPA
App 2
Qx
Q2
Q1
Qx
Q2
Q1
MQ Server
CPA
App n
Figure 1 – Content Provider view of the CPA system
The CP connects to the CPA Message Queue broker (MQ broker) and send messages to his dedicated send
queue, and receives messages from his dedicated receive queue. The content provider (CP) does not pull for
messages, but receives events when messages are waiting in the queue. At the other end of the broker, the CPA
applications servers are competing for messages from the queues achieving load balancing. In the other scenario
when a message is aimed at a CP, the CPA server handling the request will put the message in the particular
CP’s dedicated queue.
The message queue broker is a JMS (Java Messaging System) compatible messaging system from Progress
Software, SonicMQ.
2
Content Provider Access
3 Security
3.1
Firewalls
Content providers connect on a well-known IP-address at Telenor Mobil. To gain access to this address, the IPaddresses of the content provider server machines must be opened for in the firewall at Telenor Mobil. This
implies that when the content providers plan to connect to the CPA or to change the IP-address of their server,
they must notify Telenor Mobil some days in advance about this change. This will give Telenor Mobil enough
time to make this switch as smooth as possible regarding the firewall rules
3.2
Authentication, Privacy and Integrity
These things are handled by the messaging system used. Authentication is done with a username and password.
The username and password gives the content provider access to send and receive message to and from his
message queues at Telenor Mobil.
The messages sent and received on the connection are currently not encrypted, but this can be switched on by the
CPA system. The integrity of each message is by default protected.
3
Content Provider Access
4 Message flow
Content providers communicate with the CPA system via a third party messaging system as shown in Figure 1.
This means that this product provides reliable communication between the content provider and Telenor Mobile.
When a content provider sends a message to Telenor Mobile, the message queue product (MQ) guaranties that
the message arrives at the broker intact, and it guaranties that it is persisted in the broker until CPA collects the
message to bill and distribute it to its destination.
This separation of the parties leads to that a content provider can deliver messages to the broker as fast as he
wants, or as fast as the MQ product permits. The CPA servers on the other hand will pick messages from the
broker as fast as they can. The same apply for the opposite direction; the CPA servers send messages to the
broker as they arrive, and the content providers pick messages from the broker in their own pace.
4.1
Sending messages to CPA
A content provider deliver a message to the MQ broker by executing one call to a method provided by the MQ
client API, see Appendix A – SonicMQ Java API.
In general, the CPA system only will acknowledge a message if CPA fails to handle the message due to a
problem with the message. If message fails due to errors in the Telenor Mobile system, the message will be
queued, and retried a number of times. The content provider can assume that all unacknowledged messages have
been successfully handled. If it happened that a message fails on the last attempt, the CPA system will
acknowledge the message using the codes defined in Chapter 5
4
Content Provider Access
Reply codes in acknowledgements. Generally there is no point for a content provider to try to re-send a message
that failed.
A content provider can signalise that he wants acknowledge on a particular message, even if it does not fail, by
tagging the message, see Chapter 6 Message formats.
A content provider can send messages to himself, to other content providers or to mobile phones.
Each message sent to the broker can be tagged with a timestamp that specifies its validity time in the message
queue. If the CPA system does not pick the message from the queue within that time, the broker will discard the
message.
4.2
Receiving messages from CPA
Each content provider receives messages from his dedicated queue in the broker. When a message arrive at the
content provider queue, the MQ client at the content provider’s side raises an event and makes the message
available. If a message arrives at the broker when a content provider is not connected, the messages will be
queued until the content provider connects and are ready to receive.
4.3
Performance considerations
Content providers can achieve higher throughput in the communication with the MQ broker by increasing the
number of connections to the broker. It is possible to send messages to one queue, from several connections at
the same time. The same apply for receiving messages from the broker. If several connections listen for
messages on the same queue, they compete for messages from the queue and the messages will divide about
evenly between the connections.
5
Content Provider Access
Message formats
The messages in CPA can be categorised in the following message types:
Messages from CPA to content providers
MSG_FROM_OP_SMSC
Mobile originated message from CPA to content provider.
MSG_FROM_OP_CP
Message from CPA to content provider, originally sent from another content
provider.
MSG_FROM_OP_ACK
Acknowledgement message from CPA to content provider.
Messages from content provider to CPA
MSG_TO_OP_SMSC
Mobile terminated message from content provider to CPA.
MSG_TO_OP_CP
Message from content provider to CPA, aimed at another content provider.
4.4
Messages from CPA to Content Provider
To be able to tell these messages apart from each other when arriving, the content provider can e.g. check the
following:
-
If the parameter “ack_isack” is set to “true”, the message is of type MSG_FROM_OP_ACK
-
If the parameter “source” holds any value, the message is of type MSG_FROM_OP_CP
-
All other messages are of type MSG_FROM_OP_SMSC
4.4.1 MSG_FROM_OP_SMSC
This is a mobile originated message from CPA to content provider.
Field name
Mandatory
Description
messageid
Yes
A CPA generated message identifier, with the syntax <Local
Port>-<timestamp><sequence number>.
msn
Yes
This is the mobile number of the sender of the message.
sno
Yes
The large account that received the message.
msg
Yes
The message content.
timestamp
Yes
The SMSC-timestamp
xser
No
The XtraService-field. Only in use for content providers with the
possibility to receive binary or concatenated messages from an
end-user.
lanumber
No
The total large account number. Only in use for content providers
with extended large account series.
Table 1 - Message fields to content provider from SMSC
4.4.1.1
Extended number range
Extended large account series (extended number-range/sub-range) is a functionality that is available for the
content providers in need of such a service. Generally the use of 14 digits including the four digits CPA is
available. Sub-range must be specified when ordering a CPA account from Telenor.
When an end-user sends an SMS to the extended large-account, the message will be forwarded to the content
provider in the same way as with an ordinary SMS to the large-account, and with information about what
number-range the end-user sent the message to.
Example:
6
Content Provider Access
Short code (4 digits)
Sub range series
From number
To number
19XX0000000000
19XX9999999999
(Every sub range series
must be specified on the
ordering form)
19XX
14
4.4.2 MSG_FROM_OP_CP
This is a message from CPA to content provider, originally sent from another content provider. Note that in
order to be able to receive (and send) messages from (and to) other content providers this has to be explicitly
configured in CPA per content provider. Default configuration is that no content providers is allowed to send
messages to any other content provider.
Field name
Mandatory
Description
messageid
Yes
A message identifier generated by the sending content provider.
This can be a number or a text of any size.
sno
Yes
The CPA large account for the sending content provider.
source
Yes
The name/id of the sending content provider.
XXXXX
No
Any other fields that the content providers may agree upon. Field
names reserved by the CPA system, are those specified in these
tables, and names starting with “system_” or “external_”
Table 2 - Message fields to content provider from another content provider
4.4.3 MSG_FROM_OP_ACK
This is an acknowledgement message from CPA to content provider.
Field name
Mandatory
Description
messageid
Yes
A message identifier, identical with the id of the corresponding
message originally sent from the content provider
(MSG_TO_OP_SMSC or POS_TO_OP_REQ).
ack_isack
Yes
This message is an acknowledgement on a previous message the
content providers sent to CPA.
ack_code
Yes
The reply code, defined in Chapter 5 Reply codes in
acknowledgements.
ack _description
No
This field can contain additional information about the event that
led to the ack. Ie. description of the error
Table 3 - Message fields for acknowledge messages from CPA
7
Content Provider Access
4.5
Messages from Content Provider to CPA
4.5.1 MSG_TO_OP_SMSC
This is a mobile terminated message from content provider to CPA.
Field name
Mandatory Description
messageid
Yes
A message identifier. This can be a number or a text of any size. CPA
uses this id when acknowledging the message.
msn
Yes
This is the telephone number of the recipient of the message. Normally
this is also the number that is billed for the message. In case the provided
msn is not found in our billingsystem the content provider will receive an
ack from CPA indicating “customer not found” (ackcode 1006) when
trying to bill the message, and the message will not be sent to end-user.
The length of the msn cannot exceed 15 characters, in that case CPA
assumes this is an encrypted MSISDN number, and will try to decrypt the
content of the msn field. This will give an ackcode 702 or 809 (see 5
Reply codes in acknowledgements)
billingmsn
No
This is the number that will be billed for the message. Note that to be able
to use this field the content provider must be specially configured for this
on the CPA system. Normally the “msn” number is billed, and the
“billingmsn” field may only be used for content provider with particular
needs.
sno
No
Sender of the message.
Default configuration for all content providers on CPA is that the large
account defined in CPA is set at the sender of the message, regardless of
what this parameter sno holds.
However, it is possible to configure CPA so that the content providers
themselves may decide what the sender of the message will be set to by
filling out this parameter, either with no control in CPA, or checked
against a list of legal senders per content providers. In these cases it is
also possible to use alphanumeric sender up to 11 characters (e.g. the
name of the content provider). To be able to do this the content provider
must specifically ask Telenor Mobile for this possibility.
msg
Yes
This parameter will contain the content to be sent to the end user. The
message must consists of textual strings encoded in ISO-8859-1
pricegroup
Yes
This field contains the price group that should be used when billing the
message. See the pricing information in chapter 9 in this document for
further information. This parameter is case sensitive so it must be written
exactly as in Table 8 - Available price categories.
8
Content Provider Access
type
No
This field is used to state what type of message this is. The different types
of messages are

Binary messages, i.e. the message contains binary data like a
logo or a ring tone for Nokia mobile telephones. For binary
messages, the value of this field can be “binary” or
“binary_simple”. If the value is “binary_simple”, the CPA
system will treat the message as a potential long binary message,
and split it into several messages before it is sent to the mobile
phones. If the value is “binary”, the message is not split, so the
content provider is responsible for the message not being too
long. See chapter 8 for details on binary messages.

Flash messages, i.e. messages that pop up directly in the phone’s
display. For Flash messages the value of this field must be
“flash”.

XtraService messages, i.e. messages where the XSer field is set
manually. (The XSer field is defined in the UCP protocol of the
SMSC, and can be used for EMS and UCS2 messages.) In this
case the value of this field must be “xs”

Concatenated text, i.e. if the message in the msg parameter
contains more than 160 characters, the message is split into two
or more submessages in CPA, which are concatenated in the
mobile phone. In this way mobile phones that are able to display
more than 160 characters in a text message, will display the
entire text in one message. Phones supporting only 160
characters will show several messages (e.g. message 1/3,
message 2/3, and message 3/3). To enable concatenated text
messages this parameter must be set to “text_concat”.
If the field is not set, the message is plain text.
header
No
1
This field is currently only used for the header of binary messages, and
hence not in use if the type field is not set. If the type field specified that
the message is “binary_simple”, this field should contain the port on the
mobile phone the message should be sent to. If the type was “binary”, the
content provider must build the headers as explained in chapter 8.
xser
No2
This field is used to define the XSer (Extra Service) field defined in the
UCP protocol of SMSC. Ex if the message is an EMS or UCS2 message.
The type must be set to “xs”. See chapter 8 for details about the use of the
XSer field
mt
No
This field can be set if type is set to “xs”. See chapter 8 for examples
ia5
No
This field can be set to “true” if type is set to “xs” and the text in the msg
field is already converted into IA5 characters. If this field is not set, CPA
converts the content of the msg field into IA5 characters.
This field has no significance if type is “binary” or “binary_simple” (no
converting in CPA) or for plain text messages (always converted in CPA).
servicename
No
This field can be set to the name of the content provider service this
message corresponds to. This is used in the detailed invoice information
presented for the end users. To be able to use this functionality the content
provider must be configured in a special way on CPA, and the
functionality is primarily meant for internal Telenor Mobile content
providers.
1
Mandatory for messages of type “binary” and “binary_simple”
2
Mandatory for messages of type “xs”
9
Content Provider Access
delivery_notification
No
This field can be set to “true” if a delivery notification/receipt is to be sent
to an msisdn number. Delivery receipt can only be sent to an msisdnnumber.
dn_adress
No
This field can be set if the field delivery_notification is “true”, and it must
be an msisdn number. If the sender of the message (msisdn number) also
is the receiver of the delivery receipt, this field can be empty.
timestamp
No
This field can be filled in to indicate the validity period of the message in
SMSC. Default value if this field is empty is 3 days. This value must be
on the format DD:HH:MM where D-day H-hour M-minute added to the
present time. Example: validity period of 1 day and 2 hours: timestamp =
01:02:00
external_ackwanted
No
Set this field to “true” if acknowledge is wanted on all messages, and not
only the messages that fail. If this is set to “false”, the acknowledge
messages with ackcode 200, 210, and 220 will not be returned
content_indicator
No
This field is used to indicate type of content.
Only content providers with a CPA Streaming agreement shall use this
value, and the value shall be defined only if the SMS is payment for one
of the streaming subscription products defined (01.02.2006):

A : Subscription, sound per week

B : Subscription, sound per month

C : Subscription, video per week

D : Subscription, video per month
As default, this value shall not be defined.
businessmodel
No
This field is by default “CPASMS” if not used. It will contain the
business model decided by the product manager. Product manager will
contact CP for exact use of this field. The field can maximum contain 10
letters.
age
No
This field can be set to 4 different values:
“Age15” – Message will only be delivered to recipient if age of recipient
is 15 or younger.
“Age16” – Message will only be delivered to recipients if age of recipient
is 16 or older.
“Age17” – Message will only be delivered to recipient if age of recipient
is 16 or 17 years.
“Age18” – Message will only be delivered to recipient if age of recipient
is 18 or older.
The message will be rejected if this field is set, and the age of the
recipient doesn’t match, or the check fails. This feature must be enabled
for the specific account the content provider is using on CPA.
See chapter 8 for more details and examples
priceplan
No
This field can be set to a value containing up to 20 different priceplans.
Each priceplan has its own unique 4 digit number. If more than 1
priceplan is submitted, the different numbers must be separated with a
semicolon “;” .
The message will not be delivered to recipients with other priceplans than
submitted in this field. If the check fails, the message will be rejected. To
be able to use this functionality the content provider must be configured
in a special way on CPA. Product manager will provide the list of
different priceplans to CP.
See chapter 8 for more details and examples
10
Content Provider Access
Table 4 - Message fields from content provider to SMSC
The table contains the message fields that are meaningful in the context of sending messages to a mobile phone.
If any of the mandatory parameters are missing the message will not be sent to the mobile telephone user. The
parameter type is used for binary and flash messages, and when the XSer field is defined manually, and also
when concatenated text messages are to be used. The header is only used for binary messages. If the message is a
binary message, the type field must be set to "binary" or “binary_simple” and the header field should be the
header of the binary message, or in case of “binary_simple” the port on the mobile phone. The msg field will
then contain the binary message. This is explained in chapter 8 of this document.
If the message is a flash message, the type field must be set to “flash”.
If the XSer field is to be defined manually, then the type field must be set to “xs”. In this case the MT field (see
EMI – UCP specification) can also be defined. If its not, it will be set to “3”. If the content in the msg field is
already converted into IA5 characters, the ia5 field must be set to “true”.
4.5.2 MSG_TO_OP_CP
This is a message from content provider to CPA, aimed at another content provider. Note that in order to be able
to send (and receive) messages to (and from) other content providers this has to be explicitly configured in CPA
per content provider. Default configuration is that no content providers are allowed to send messages to any
other content provider.
Field name
Mandatory
Description
messageid
Yes
A message identifier. This can be a number or a text of any size. CPA
uses this id when acknowledging the message.
XXXXX
No
Any other fields that the content providers may agree upon. Field
names reserved by the CPA system, are those specified in these tables,
and names starting with “system_” or “external_”
external_ackwanted
No
Set this field to “true” if acknowledge is wanted on all messages, and
not only the messages that fail. If this is set to “false”, the
acknowledge messages with ackcode 200, 210, and 220 will not be
returned
external_receiver
Yes
The CPA id/name of the receiving content provider
Table 5 - Message fields from content provider to another content provider
11
Content Provider Access
5 Reply codes in acknowledgements
Code Meaning
200
OK. The message was processed and billed successfully. If external_ackwanted is set to false for a
message, this ackcode will not be returned to content provider. Revenuesplit according to the
agreement.
210
The message was successfully sent, but billing of the message failed on the first attempt. The message
will be attempted billed later (a configurable maximum number of times). No point in resending
message, end user has received it. This acknowledgement does not guarantee revenuesplit, cf. the
Main Agreement art. 11.
Messages generating this type of ack will eventually generate an additional ack with the same
messageid when the message is done (either billed succesfully or reached max number of attempts).
This ack will also be sent to the content provider. If external_ackwanted is set to false for a message,
210 will not be returned to content provider. The additional ack will in this case also not be returned to
content provider in cases where billing eventually succeeds (ackcode 200).
220
The message was successfully sent, but real time billing was not done because of problems with rating
system. The message will be attempted billed later (a configurable maximum number of times). No
point in resending message, end user has received it. This acknowledgement does not guarantee
revenuesplit, cf. the Main Agreement art. 11.
Messages generating this type of ack will eventually generate an additional ack with the same
messageid when the message is done (either billed succesfully or billed failed). This ack will also be
sent to the content provider. If external_ackwanted is set to false for a message, 220 will not be
returned to content provider. The additional ack will in this case also not be returned to content
provider in cases where billing eventually succeeds (ackcode 200).
230
The message was successfully sent, but billing was not done. The message was not supposed to be
billed. End user has received message. All messages sent with free price categories (eg. KAT20,
CPA000) will generate this reply code, as well as all messages sent from a content provider to another
content provider, and all positioning requests from content provider.
701
Checksum error in message to SMSC (message not sent to end user)
702
Syntax error in message to SMSC. Possibly wrong header in binary messages (message not sent to
end user)
703
Operation not supported by system (SMSC). Possibly an error in the header field of binary messages
(message not sent to end user).
704
Operation not allowed (by SMSC). Possibly an error in the header field of binary messages or
message buffer in SMSC is full (message not sent to end user).
705
Call barring active. The receiver of the message is not allowed to receive any more messages from the
SMSC at the moment (message not sent to end user).
706
Invalid ADC. The receiver number of the message is invalid according to the SMSC (message not
sent to end user).
707
Other SMSC negative acknowledges.
719
Acknowledgement from SMS-C too long.
720
Not in use.
721
Message not accepted by SMSC (message not sent to end user).
722
Not in use.
723
From SMSC: The message was empty (message not sent to end user).
724
From SMSC: The message was too long (message not sent to end user).
725
From SMSC: Invalid message (message not sent to end user).
726
Acknowledge was not received from SMSC
12
Content Provider Access
727
Invalid acknowledgement from SMSC
728
Not in use.
729
Not in use.
730
Undefined error in communication with SMSC
800
The price group is illegal (message not sent to end user), ie. price group is not defined as a legal price
group for the content provider in CPA.
801
The billing account is illegal (message not sent to end user). If the content provider is configured in
CPA to be able to set the account which is to be billed for the message (in the billingmsn field of the
message), this reply code may be returned if a check against a list of predefined legal billing accounts
in CPA fails, or if the billingmsn field is missing.
802
General internal system error when validating message (message not sent to end user). Error occurred
while checking billing type, billing account and price group of the message.
803
The message is not a valid message (message not sent to end user). Error occurred during converting
message from JMS message to CPA message.
804
Message distribution rejected on the last attempt. The message was tried resent several times
(configurable number of times), but distribution failed. See the field ack_description for information
on what kind of error that occurred in CPA leading to resending. Message not sent to end user.
805
Content provider’s attempt to send a message to another content provider was rejected. In order to be
able to send to another content provider this has to be configured in CPA.
806
No sender information found. Message not sent to end-user. Possible reasons:

Large account is to be set as sender of message, but large account for content provider not
found in CPA, and sno missing in message.

Sno is to be checked against a list of legal sender accounts in CPA, but sno missing in
message.

Anyone can be set as sender of message, but sno missing in message.
807
The parameter sno in message not a legal sender account for content provider (check against a list in
CPA), message not sent to end-user.
808
Sender of message to be set as the same as receiver of message, but msn missing, message not sent to
end-user.
809
Error when trying to get the MSISDN number from a Static Id value sent in message from content
provider (for positioning services).
901
Requested subscription service is unknown in the subscription server
1000 Not in use.
1001 Special account. Billing is turned off, message sent to end-user.
1002 Illegal billing parameters.
1003 Unable to connect to the billing system when trying to recall billing event (when distribution failed),
e.g. timeout when trying to connect to billing system.
If timeout occurs when trying to bill, the message will be sent, the billing event will be put in a queue,
and tried to be billed later. Then the reply code 220 will be returned instead of 1003 (reply code 220 is
described above).
1004 When billing event has been retried a configurable maximum number of times without being billed
(because of error from the billing system), this code is eventually logged in the CPA system. This is
actually no reply code to the content provider; the content provider will receive the reply code 210 the
first time the billing event is put in queue, and no other reply codes for that message.
1005 Prepaid customer has no balance left (message not sent to end user).
1006 Invalid customer account (message not sent to end user). The customer account, which is to be billed
for the message, is not a valid Telenor Mobil customer anymore. If this is a subscription/alert type of
service, the content provider should consider deleting this account from its database.
13
Content Provider Access
1007 Invalid pricecategory in billing system. Can also occur if recipient is part of a priceplan without access
to CPA content.
1008 Billing failed because of an unspecified functional error, message sent to end user.
1009 Customer is barred (message not sent to end user). The customer account is for some reason blocked
by Telenor Mobil (stolen mobile, missing payment etc).
1010 Customer is blocked for CPA services
1020 The parameter “age” or “priceplan” is not allowed for the content provider in CPA.
1021 The parameter “age” or “priceplan” doesn’t match the customer settings in the customer database.
1022 Billing failed because CPA was unable to verify the customers age. Only applicable when parameter
“age” is set.
1023 Billing failed because CPA was unable to verify the customers priceplan. Only applicable when
parameter “priceplan” is set.
1024 Billing failed because customer did not exist in COS (Customer database). Only applicable when
parameter “age” and/or “priceplan” is set.
1050 Not in use.
1051 Not in use.
1052 The customer is blocked for this service, for instance prepaid customers are blocked for certain types
of services.
Table 6 – Acknowledge codes
The table shows the reply codes used in the CPA platform. Reply codes are only used in acknowledgement
messages and have hence no meaning in ordinary messages.
14
Content Provider Access
6 Message types
Messages can either be plain text or binary coded. This section explains how to code or decode binary messages.
For MT (Mobile Terminated) messages, it is the field “type” that indicates what type of message this is. The
different types of messages are

binary_simple

binary

flash

xs

text_concat
If the type field is empty, the message is in plain text.
For MO (Mobile Originated) messages, all messages are plain text by default. If the Content Provider is
configured in the CPA system to receive binary messages (messages with UDH-information), the MO message
will contain coding information in the cases that the message contains binary data. The coding elements are
found in the xser-field.
6.1
Mobile Terminated (MT) Binary messages (Nokia specific)
The CPA-platform supports sending of binary messages from content providers. These messages currently can
contain logos, ring tones, group symbols and picture messaging for Nokia mobile phones (check the Nokia web
page for an overview of the different models that support this feature).
The support for binary messages implies that two extra fields in the message are required. The type field, which
states that the message is binary (“binary” or “binary_simple”), and the header field which must contain a header
of the binary message.
If the value of the type field is “binary”, the content provider must split the message, and compose the header
field himself. If the value of the type field is "binary_simple" CPA will split the message into pieces that can be
handled by the mobile phones, and send the messages one by one to the mobile phone. New content providers
should for simplicity consider using the “binary_simple” approach.
6.1.1 Type “binary”
An example of a message with binary data (type “binary”) is then as follows:
messageid=1
msn=99999999
sno=1999
msg=024A3A69212531114925391D4D500400A5226986105586906185506986104585525405586105584
D0558590618A26849C61A01041061A61841561A41861541A61841161549501361141361541761841A61
C21061A61841761801041061A61B41A6184288B126D0698610598692680718A22849C61A4289B08A127
18690A22C49C0104000
pricegroup=CPA000
type=binary
header=06050415810000
This example is a ringtone. The msg parameter in binary messages contains ASCII-representations of
hexadecimal numbers, which in turn represents the binary values. Each hexadecimal number represents four
binary numbers. The message can be obtained by transferring a logo, ringtone, group symbol or picture message
from your Nokia phone via Nokia Data Suite to your PC. Note that the letters in the binary message must be
upper case.
Messages with type “binary” can conceptually be divided into two categories; short binary messages and
concatenated binary messages.
15
Content Provider Access
Short binary messages
Short binary messages are messages where the sum of the length of the binary message and the header is less
than 280 HEX characters (140 octets of binary numbers). For these messages the header field should be created
in the following manner:
<LH>0504<DPORT1><DPORT2><OPORT1><OPORT2>
An explanation of these fields can be found in the table below.
Examples of headers for short binary messages are then as follows:

06050415811581 - specifies that the message is a ringtone

06050415821582 - specifies that the message is an operator logo

06050415831583 - specifies that the message is a group symbol
If the length of the message and the header exceeds 280 hexadecimal characters (140 octets), the message must
be divided into two or more submessages, and the headers must be defined differently, as described below.
Concatenated binary messages
If the sum of the length of the binary message and the header is more than 280 HEX characters characters (140
octets), the message must be divided into several submessages, and each of the submessages must be sent
separate, due to SMSC limitations. The submessages are linked together with the help of the their headers. The
layout of the header for a submessage in a concatenated message is as follows:
<LH>0003<REFNO><NOFSUB><SEQNO>0504<DPORT1><DPORT2><OPORT1><OPORT2>
Each of the <>-fields in the descripton of the header above is the ASCII-representation of one octet, an octet
being equivalent to two hexadecimal numbers. Each of the fields is described in the following table:
Field
Description
<LH>
Length of header: This octet shall state the number of octets in the rest of the header
0003
The first octet (00) is a socalled Information-Element-Identifier, which indicates that this is a
submessage of a concatenated message. The next octet (03) defines how many of the
following octets will describe the properties of the concatenated message.
<REFNO>
Concatenated message reference number: This octet shall contain a modulo 256 counter
indicating the reference number for a particular concatenated message. The reference number
must be constant for every submessage in the same concatenated message. Note that this is
not the same reference number as in the refno field in the YAP-protocol.
<NOFSUB>
Number of submessages in concatenated message: This octet is a value in the range of 0 to
255 indicating the total number of submessages within the concatenated message. (If the value
is zero SMSC ignores the part of the header which describes the concatenated message.) The
value must be constant for every submessage in the same concatenated message.
<SEQNO>
Sequence number of current submessage: This octet is a value in the range of 0 to 255
indicating the sequence number of a particular submessage within the concatenated message.
(If the value is zero or greater than the octet described above, SMSC ignores the part of the
header which describes the concatenated message.) The value shall start at 1 and increment by
one for every submessage sent within the concatenated message.
0504
The first octet (05) is an Information-Element-Identifier indicating that a 16 bit application
port addressing scheme is to be used. The next octet (04) defines the number of following
octets that will describe the application port addressing scheme.
<DPORT1> and Destination port 1 & 2: These two octets contain a number indicating the receiving port, i.e.
<DPORT2>
application, in the receiving device. As for now the following ports are supported: Ringtone:
1581 (first octet 15, second octet 81, decimal: 5505) Operator logo: 1582 (first octet 15,
second octet 82, decimal: 5506) Group symbol: 1583 (first octet 15, second octet 83, decimal:
5507)
<OPORT1> and Originator port 1 & 2: These two octets contain a number indicating the sending port, i.e.
<OPORT2>
application, in the sending device. The values in these octets are not important and might be
the same as the destination port described above.
16
Content Provider Access
Example of headers for a concatenated binary message
The following is an example of the headers for a concatenated message with the following properties:

The concatenated message is a ringtone (port 1581)

Number of submessages: 3

Reference number: 64 (decimal) -> 40 (hexadecimal)
The headers will then look like this:

Header for submessage 1: 0B0003400301050415811581

Header for submessage 2: 0B0003400302050415811581

Header for submessage 3: 0B0003400303050415811581
For more information on the information in headers, see the GSM specification (GSM 03.40 version 5.8.1
Release 1996) section 9.2.3.24, or the ETSI UCP specification version 3.1.2.
6.1.2 Type ”binary_simple”
If the type field has the value “binary_simple”, the msg field should contain a binary message of arbitrary length.
The header field must contain the mobile phone port that the message should be sent to. The value of the port
depends on the type of binary message in question (logo, ring tone, group symbol or picture message).
An example of a message with binary data is then as follows:
messageid=1
msn=99999999
sno=1999
msg=024A3A69212531114925391D4D500400A5226986105586906185506986104585525405586105584
D0558590618A26849C61A01041061A61841561A41861541A61841161549501361141361541761841A61
C21061A61841761801041061A61B41A6184288B126D0698610598692680718A22849C61A4289B08A127
18690A22C49C0104000
pricegroup=CPA000
type=binary_simple
header=1581
This example is a ringtone. The msg parameter in binary messages contains ASCII-representations of
hexadecimal numbers, which in turn represents the binary values. Each hexadecimal number represents four
binary numbers. The message can be obtained by transferring a logo, ringtone, group symbol or picture message
from your Nokia phone via Nokia Data Suite to your PC.
The following table shows the different ports to which ringtones, logos, group symbols and picture messages
should be sent, respectively.
Type
Port
Ringtone
1581
Logo
1582
Group Symbol
1583
Picture Message
158A
Table 7 - Ports for binary messages
6.2
Mobile Terminated (MT) Flash messages
In order to send Flash Messages, i.e. messages that pop up directly in the phone’s display, the value of the field
Type in the message from content provider to CPA must be set to the string “flash”:
Type = flash
17
Content Provider Access
6.3
Mobile Terminated (MT) XtraService messages (xs)
MT messages of type “xs” allows the Content Provider to define the entire binary message, and can be used for
concatenated messages, pictures, EMS, UCS2 among others.
When using this type of message, the Content Provider defines the xser field (extraservice-field) and the mt-field
(message type) in the message sent to SMSC.
The xser field allows the specification of one or more additional services, all in the format TTLLDD… where
1.
TT represents two HEX characters defining the type of service. Available services are 01 – GSM UDH
information and 02 – GSM Data Coding Scheme information
2.
LL represents two HEX characters defining the number of octets present in the data field DD. (Note
that the number of HEX characters in the data DD is twice the number of octets)
3.
DD represents a stream of HEX characters defining the service specific data itself.
If more than one additional service is to be specified in one message, this service information is concatenated
without any separators, i.e. TT1LL1DD1…DD1TT2LL2DD2…DD2. This is usually the case with mobile
originated messages.
6.3.1 XSer type of service 01, GSM UDH information
With this service type GSM User Data Header information can be specified. The data field DD of this service
type contains the octets of the GSM User Data Header as specified in GSM 03.40. (UDHL, IEIa, IEIDLa, IEDa,
IEIb, … , IEIn, IEDLn, IEDn) Every UDH octet is encoded in two IA5 hex characters.
The length of the GSM UDH information, related to the length of the Msg field content, is restricted to the
maximum length of the GSM TP-UD field: 140 octets c.q. 160 septets.
Example encoding the xser field containing UDH information:
The UDH information field consisting of the following two UDH information elements is to be encoded:
1.
Concatenated short messages, Concatenated short message reference number = 64, Maximum number
of short messages in the concatenated short message = 4, Sequence number of the current short message
=2
2.
Application Port addressing 16 bit address, destination port = 158A, originator port = 0000
TTLLDD… encoding: 010C0B0504158A00000003400402
This same TTLLDD… annotated:
01
0C
0B
05
=
=
=
=
04
15
8A
00
00
00
03
40
04
02
=
=
=
=
=
=
=
=
=
=
TT, specifies type of service 01, GSM UDH information
LL, specifies that DD part contains of 12 octets
DD,
UDHL, Length of user data header, 11 octets
DD,
IEIa, Information–Element-Identifier a, Application port addressing,
16 bit address
DD,
IEIDLa, Length of information element a = 4 octets
DD,
IEDa, Destination port
DD,
IEDa, Destination port
DD,
IEDa, Originator port
DD,
IEDa, Originator port
DD,
IEIb, Information-Element-Identifier b, Concatenated short messages
DD,
IEIDLb, Length of information element b = 3 octets
DD,
IEDb, Concatenated short message reference number = 64
DD,
IEDb, Max number of short messages in the concatenated message=4
DD,
IEDb, Sequence number of the current short message = 2
For an MO message, this information will appear in the xser-field, and the rest of the message attributes will
appear as usual in the fields messageid, msn, sno etc
Example EMS message (EMS – Enhanced Messaging Service)
EMS messages use GSM UDH information.
Simple EMS Example:
messageid = 1
msn = 99999999
sno = 1999
msg = test
18
Content Provider Access
pricegroup = CPA000
type = xs
xser=0144430C41003F0C3D004D454C4F44593A6533673372332A35236433643372322A346733236133
623372312E67336134673423663372322A3362332A34653323633372300D0A
This is a ringtone example. The xtraservice field is build up like this:
01
44
43
0C
41
00
=
=
=
=
=
=
TT,
LL,
DD
DD
DD
DD
specifies XSer Type of service 01, GSM UDH information
specifies that DD part contains 68 octets
UDHL, Length of user data header = 67 octets
IEIa, Information Element Identifier a, ringtone
IEIDLa,
Length of information element a, 65 octets
IEDa, Position of ringtone in message, 00 at the
beginning
3F0C3D004D454C4F44593A6533673372332A35236433643372322A346733236133623372312E6733613
4673423663372322A3362332A34653323633372300D0A
= DD….DD
IEDa, The ringtone, 64 octets
6.3.2 XSer type of service 02, GSM DCS information
DCS (Data Coding Scheme) type of service always has a total length of 6 numeric characters. So the sequence
TTLLDD is set to:
TT = 02
LL= 01
DD = 00…FF
The meaning of the DCS values are explained in GSM 03.38
Example UCS2 message
UCS2 coded short messages uses GSM DCS information.
Simple UCS2 example:
messageid = 1
msn = 99999999
sno = 1999
msg = 03A003B103B203B303C30394
ia5 = true
pricegroup = CPA000
type = xs
mt = 4
xser = 020119
This message is:

For Mobile Terminated messages, the mt field must be set to the value 4, and the ia5 field must be set to true.
The ia5 field is set in cases where the msg field contains the ASCII-representations of hexadecimal numbers,
which in turn represents the binary values. Each hexadecimal number represents four binary numbers.
6.4
Mobile Originated (MO) binary messages (e.g. concatenated messages)
MO messages containing binary information, for example concatenated messages or picture messages will
contain information about the binary coding scheme in addition to the actual message content. This information
will appear in the xser-field.
The xser-field is encoded the same way as for MT messages, with type 01 (User Data Header, UDH) or 02 (Data
Coding Scheme, DCS) as described in sections XSer type of service 01, GSM UDH information and XSer type
of service 02, GSM DCS information.
The most common use of binary MO messages is for text messages longer than 160 characters. Since CPA
doesn’t concatenate these messages before passing it on, the Content Provider needs to put the messages together
in the correct order.
19
Content Provider Access
Example Concatenated message
This message (177 characters) is sent from the phone, and CP receives it as two messages:
This message contains more than 160 characters. A concatenated message is when a single logical message is
sent over multiple physical messages to overcome SMS size limitations.
Message 1:
msn=99999999
msg=This message contains more than 160 characters. A concatenated message is when
a single logical message is sent over multiple physical messages to overco
xser=0106050003140201020100
sno=1999
Message 2:
msn=99999999
msg=me SMS size limitations.
xser=0106050003140202020100
sno=1999
To decode the message and concatenate correctly, the xser-field needs to be investigated:
Message 1:
0106050003140201020100
00
03
14
02
01
–
–
–
–
–
Information-Element-Identifier, Concatenated short messages
Length of information element = 3 octets
Concatenated short message reference number = 20
Max number of short messages in the concatenated message = 2
Sequence number of the current short message = 1
Message 2:
0106050003140202020100
00
03
14
02
02
–
–
–
–
–
Information-Element-Identifier, Concatenated short messages
Length of information element = 3 octets
Concatenated short message reference number = 20
Max number of short messages in the concatenated message = 2
Sequence number of the current short message = 2
20
Content Provider Access
7 Price groups and billing of messages
All content providers usually have the same set of price categories available3. The available price groups are on
the format “CPAxxx”, where x currently is the price in øre (100 øre = 1 NOK), e.g. “CPA000” or “CPA650”. As
in the agreement the categories to be used are:
Category
3
Price in NOK
incl. VAT
Category
Price in NOK
incl. VAT
Category
Price in NOK
incl. VAT
CPA000
0,-
CPA3100
31,-
CPA8000
80,-
CPA100
1,-
CPA3200
32,-
CPA8900
89,-
CPA150
1,50
CPA3300
33,-
CPA9000
90,-
CPA200
2,-
CPA3400
34,-
CPA9900
99,-
CPA300
3,-
CPA3500
35,-
CPA10000
100,-
CPA400
4,-
CPA3600
36,-
CPA500
5,-
CPA3700
37,-
CPA600
6,-
CPA3800
38,-
CPA650
6,50
CPA3900
39,-
CPA700
7,-
CPA4000
40,-
CPA800
8,-
CPA4100
41,-
CPA900
9,-
CPA4200
42,-
CPA1000
10,-
CPA4300
43,-
CPA1100
11,-
CPA4400
44,-
CPA1200
12,-
CPA4500
45,-
CPA1300
13,-
CPA4600
46,-
CPA1400
14,-
CPA4700
47,-
CPA1500
15,-
CPA4800
48,-
CPA1600
16,-
CPA4900
49,-
CPA1700
17,-
CPA5000
50,-
CPA1800
18,-
CPA5100
51,-
CPA1900
19,-
CPA5200
52,-
CPA2000
20,-
CPA5300
53,-
CPA2100
21,-
CPA5400
54,-
CPA2200
22,-
CPA5500
55,-
CPA2300
23,-
CPA5600
56,-
CPA2400
24,-
CPA5700
57,-
CPA2500
25,-
CPA5800
58,-
CPA2600
26,-
CPA5900
59,-
CPA2700
27,-
CPA6000
60,-
CPA2800
28,-
CPA6900
69,-
CPA2900
29,-
CPA7000
70,-
This might not be the case for internal Telenor Mobil content providers.
21
Content Provider Access
CPA3000
30,-
CPA7900
79,-
Table 8 - Available price categories
The content providers should add one of these categories to the “pricegroup”-field of the message. The account
to be billed for the message will then be billed according to the prices in the table above. Note that the price
category CPA000, which is a free price category for mobile users, will imply a cost for the content providers as
in agreement with Telenor Mobil.
7.1
Billing of long messages (binary and text)
When sending a long binary or text message (where the message and header is longer than 280 HEX characters)
with the type “binary_simple” or “text_concat”, the message will be split in CPA, and each of the sub-messages
sent via the SMSC will imply a cost for the content provider according to the contract with Telenor Mobil.
When sending a concatenated binary message with the type “binary”, the CPA handles all the sub-messages
independently. This means that the price of each sub-message should not be equal to the price the end user
should pay, since the total price of the binary message then would be some multiple of the price they actually
should pay. One way of doing this is to bill one of the sub-messages with the price of the entire message, and the
rest of the sub-messages with a free price category. Note again, though, that the messages with the free price
category will imply a cost for the content provider.
8 Age and priceplan check
8.1
General information
CPA SMS provides the possibility to verify that the recipient resides inside a valid age- or priceplan-group (or
both). To be able to use this functionality, the originating account needs to be configured on the CPA platform as
an “Age” , “Priceplan” or “Both Age and Priceplan” enabled account. An error (1020) will be returned to the CP
if the parameter ‘age’ or ‘priceplan’ is submitted and is not according to the settings for the actual CP.
If age and priceplan check is requested for a NON-TELENOR subscriber, the check will fail with error “1024
Customer not found in COS”. COS is the Telenor Subscirber database. Normally (without age or priceplan
check), this situation will return an error “1006 Customer not found”. The reason for the different errorcodes is
related to the fact that age and priceplan check is executed before the billing execution. 1024 is the responsecode
for the failed age and priceplan check. 1006 is the responsecode for the failed billingrequest to a NONTELENOR subscriber.
If the subscribers age is “unknown” in our customer database, the error “1022 Age unavailable” will be returned
no matter what age-group the request is for. This will happen if there is no “user” registered to the subscription
in our customer database. The legal owner of a subscription can register a user with name and birth date trough
our customer care. For corporate/business subscribers the age will be set to 18 if the owner of the subscription
has not registered a valid birth date for the user. This means that the parameters Age16 and Age18 will give a
positive result if the recipient is a corporate/business subscriber.
If age check is requested, the message will be rejected if the check or the result of the check is unsuccessful.
See Table 4 for available age and priceplan values.
See Table 6 for responsecodes.
22
Content Provider Access
Appendix A – SonicMQ Java API
This appendix contains a description of the SonicMQ client API, which is of interest when communicating with
CPA. The complete SonicMQ API documentation is also available.
Connecting to the MQ Broker
The code shown below demonstrates how to create a connection to the message broker for sending and receiving
messages. The latest client.jar and sonic_Crypto.jar is available for download at http://cpa.telenor.no/cpa/ These
library files needs to be in the Classpath
//The ip address and port where the MQ broker is listening.
String broker = “xxx.xxx.xxx:60000”;
String username = “username”;
String password = “password”;
//The queue where the content provider should send messages
String queue_from_cp = “username_from_CP”;
//The queue where the content provider receive messages from
String queue_to_cp = “username_to_CP”;
//Create a connection factory to the particular broker. The factory can be used to
//create several connections
QueueConnectionFactory factory;
factory
= (new progress.message.jclient.QueueConnectionFactory (broker, username, password));
//Establish a connection
connection = factory.createQueueConnection();
//Set the interval between each time the MQ client should ping the broker to check if the
//connection is ok
((progress.message.jclient.Connection)(connection)).setPingInterval(10000L);
((progress.message.jimpl.Connection)(connection)).setPingInterval(10000L);
//Register an exception listener object that will receive notification when there is a
//problem with the connection to the broker. The object must implement the single
//method in the ExceptionListener interface
connection.setExceptionListener(this);
//Create session. The second parameter can be AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE,
//by using AUTO_ACKNOWLEDGE the messages will automatically be acknowledge by the
//MQ client api.
session = connection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
//Create sender queue object for the queue that will receive messages
Queue sendQueue = session.createQueue (queue_from_cp);
//Create a sender object that can be used to send messages to the particular queue
sender = session.createSender(sendQueue);
//Create receiver queue object for the queue that the content provider will receive messages
from
Queue receiveQueue = session.createQueue (queue_to_cp);
//Create a receiver object that will receive messages from the particular queue
receiver = session.createReceiver(receiveQueue);
//Register a message listener object that will receive messages as soon as they are
23
Content Provider Access
//available in the receiver queue. The object must implement the single
//method in the MessageListener interface
receiver.setMessageListener(this);
//At
this point we are ready to send/receive messages to/from the MQ broker.
//To start receiving messages, the connection
// will be used for sending messages.
must be started. This is not required if the connection only
connection.start();
Sending Messages to a Queue
//Create a message object
javax.jms.Message message = new progress.message.jclient.Message();
javax.jms.Message message = new progress.message.jimpl.Message();
//Add the message fields
message.setStringProperty(“messageid”,”1232”);
message.setStringProperty(“msn”,”99999999”);
message.setStringProperty(“sno”,”19xx”);
message.setStringProperty(“pricegroup”,”19xx”);
message.setStringProperty(“msg”,”This is a short message”);
message.setStringProperty(“businessmodel”,”Tippeliga”);
(Optional field, maximum 10 letters)
//Set JMS correlation id. This id only will be used by CPA if the messageid field
//is not existing.
message.setJMSCorrelationID(“jms-” + message.getStringProperty(“messageid”));
//Send the message. If this method call is executed without throwing an exception, the
//message is guarantied to be persistent in the broker
sender.send(message, jms.DeliveryMode.NON_PERSISTENT,
Message.DEFAULT_PRIORITY, messageLifeSpan);
//The delivery mode can be NON_PERSISTENT or PERSISTENT
Receiving messages from a Queue
When a message is pending in the queue, the onMessage method of the receiver object that was created above
will be called.
//This method is called by the MQ client API when a message is available in the queue
public void onMessage(Message message) {
String messageId = message.getStringProperty(“messageid”);
String msg = message.getStringProperty(“msg”);
…
}
24
Content Provider Access
Appendix B – Java Sample Implementation
This appendix describes the Java sample client implementation.
The CPAConnection class
The class demonstrates how to connect to the CPA system, receive messages from the system, and send
messages to the system. In addition to the communication specific code, the class also contains a primitive
mechanism that will try to re-establish the connection to the broker if it is lost.
The Configuration file
The configuration contains a handful of properties, which must be set up before the sample application can
connect to the broker. The file is used from the CPA Test GUI application. The properties must appear in the file
as <property name>=<property value>
Property name
Values
Description
broker
Default value:
212.17.129.150:60000
The message broker’s ip-address on the form
<xxx.xxx.xxx.xxx>:<port>
username
Proved by Telenor Mobil
Gives the content provider access to his queues
password
Proved by Telenor Mobil
Gives the content provider access to his queues
read_queue
<username>_to_CP
The queue that receives messages from Telenor Mobil
write_queue
<username>_from_CP
The queue that should receive messages from the content
provider
message_lifespan
0-n
The number of milliseconds a message will be kept in the
broker before it is discarded. If this value is zero, the message
never will be discarded.
persistens
non_persistent
non_persistent - This is the lowest overhead delivery mode
because it does not require that the message be logged to stable
storage.
persistent
persistent This mode instructs the JMS provider to log the
message to stable storage as part of the client's send operation.
Basically : non_persistent means faster, while persistent means
safer (if the broker goes down)
25
Content Provider Access
The Test GUI
The application can be used to send and receive messages for test and debugging purposes.
Figur 1 - Content Provider Test GUI
26
Content Provider Access
The text area in the upper left corner shows the content of the current configuration file. The buttons “connect”
and “disconnect”, connects and disconnects the broker. The button “send message” are to send a single message,
and the button “send many” are used to send a number of equal messages (this is only interesting for testing
throughput). The text area to the right shows the messages received from CPA. All messages received and sent
will also be printed to the console.
27
Content Provider Access
Appendix C – C Sample Implementation
A C sample implementation does not exist, but Progress Software announce that the have a SonicMQ thin C
client that can be downloaded from the web.
See: http://www.sonicsoftware.com/products/sonicmq/clients/index.ssp
28
Content Provider Access
Appendix D – Testing the connection
To test the connection to Telenors CPA (SonicMQ), there are two different alternatives to choose between:
1.
Using SonicMQ API
By using the functionality for ping-intervals in the client API for SonicMQ, the client application can
check if the connection is ok.
If not, the client shall reconnect with the broker.
//Set the interval between each time the MQ client should ping the broker to check if the
//connection is ok
((progress.message.jclient.Connection)(connection)).setPingInterval(10000L);
((progress.message.jimpl.Connection)(connection)).setPingInterval(10000L);
2.
Sending test message to SonicMQ
With this alternative, the Content Provider can send a message to its own read-queue (XXX_to_CP). If
the connection is up and running, the client application will receive the same message within a short
amount of time. The content of the message, the attributes, is not important in this context, but it has to
be a valid JMS-message.
With this alternative, the Content Provider will decide how frequently a test message should be sent,
and what to do if the message doesn’t return within a reasonable amount of time. It is not recommended
though, that the interval between the test-messages is less than 5 minutes
29