JSR 281 IMS Services API - Oracle Software Delivery Cloud

JSR 281 IMS Services API 

for Java Micro Edition 

Maintenance Release Version 1.1 

JSR 281 Expert Group 

jsr-281-comments@ericsson.com 

Java Community Process 

JSR 281 IMS Services API -- 2009-04-08 Page 1 of 199

JSR 281 SPECIFICATION LICENSE AGREEMENT (”AGREEMENT”) 

ERICSSON AB (“ERICSSON”) IS WILLING TO LICENSE THIS SPECIFICATION (AS DEFINED BELOW) 

TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS AND CONDITIONS 

OF THIS AGREEMENT. PLEASE READ THE TERMS AND CONDITIONS CAREFULLY. BY ACCESSING 

OR USING THE SPECIFICATION (AS DEFINED BELOW) YOU WILL BE BOUND BY THE TERMS AND 

CONDITIONS OF THIS AGREEMENT. 

DEFINITIONS 

“Specification” shall mean JSR 281 IMS Services API specification 

“Independent Implementation” shall mean an implementation of the Specification that neither derives 

from nor includes any of source code or binary code materials of the Reference Implementation. 

“Licensee” shall mean the individual downloading the Specification and where such individual downloads 

the Specification for other than private use, the legal entity represented by such individual. 

“Reference Implementation” shall mean the reference implementation of the Specification. 

“Reserved Name Space” shall mean the public class or interface declarations whose names begin with 

javax.microedition.ims or their equivalents in any subsequent naming convention adopted through the Java 

Community Process, or any recognized successors or replacements thereof. 

“TCK” and “Technology Compatibility Kit” shall mean technology compatibility kit for the Specification. 

1 LICENSE GRANTS 

1.1 Ericsson hereby grants Licensee a non-exclusive, non-transferable, worldwide, royalty free, fully paid up 

limited license (without the right to sublicense), solely under the intellectual property rights licensable by 

Ericsson to view, down load, use and reproduce the Specification only for the purpose of internal evaluation. 

1.2 Subject to the reciprocity requirement set forth below, Ericsson hereby grants Licensee a non-exclusive, 

non-transferable, worldwide, royalty free, fully paid up limited license (without the right to sublicense), solely 

under the intellectual property rights licensable by Ericsson to view, down load, use and reproduce the 

Specification only for the purposes of development of Independent Implementations. The Specification 

contains proprietary information of Ericsson and may only be used in accordance with the license terms set 

forth herein. For the avoidance of any possible doubts, no right to further distribute the Specification is 

granted by this Agreement. 

1.3 Subject to the reciprocity requirement set forth below, Ericsson hereby grants Licensee a perpetual, 

non-exclusive, worldwide, fully paid-up, royalty free, limited license (without the rights to sublicense) under 

its licensable (i) copyrights in the Specification and (ii) patent claims for which there is no technically feasible 

way of avoiding infringement in the course of implementing the Specification, to create and/or distribute 

Independent Implementations that 

a) fully implement the Specification including all its required interfaces and functionality; 

b) do not modify, subset, superset or otherwise extend the Reserved Name Space, or 

include any public or protected packages, classes, Java interfaces, fields or methods 

within the Reserved Name Space other than those required/authorized by the 

Specification; and 

c) pass the Technology Compatibility Kit (including satisfying the requirements of the 

applicable TCK Users Guide) for the Specification. 

1.4 Licensee needs not to include limitations (a)-(c) from Section 1.3 above or any other particular “pass 

through” requirements in any license Licensee grants concerning the use of Licensee’s Independent 

Implementation or products derived from it. However, except with respect to implementations of the 

Specification (and products derived from them) by Licensee’s licensee that satisfy limitations of Section 1.3 

(a)-(c) above, Licensee may neither: (i) grant or otherwise pass through to Licensee’s licensees any 

licenses under intellectual property rights licensable by Ericsson; nor (ii) authorize Licensee’s licensees to 

make any claims concerning their implementation’s compliance with the Specification. 

1.5 Other than the limited license granted in this Agreement, Licensee acquire no right, license, title or interest 

in or to the Specification or any other intellectual property rights of Ericsson or its licensors. 


1.6 The licenses granted by Ericsson in Sections 1.2 and 1.3 of this Agreement are subject to a reciprocity 

requirement and therefore conditional upon Licensee committing to offer to any party seeking a license from 

Licensee, under Licensee’s patent rights, which are or would be infringed by all technically feasible 

implementations of the Specification, on the following terms: 

(i) 

(ii) 

(iii) 

(iv) 

(v) 

the license grant shall be under each patent claim that Licensee own, will own or have the 

authority to license, and 

the license shall be granted on fair, reasonable and non-discriminatory terms, and 

the license shall be perpetual, non-exclusive, non-transferable and worldwide within the 

scope of the licenses granted above by Ericsson, and 

the license shall permit the development, distribution and use of an Independent 

Implementation that satisfies the requirements set forth in 1.3(a) – (c) above, and the use 

of a licensed Reference Implementation, in whole or in part, as a part of such Independent 

Implementation, and 

the license shall permit the use of the TCK. 

1.7 Nothwithstanding Section 1.6 above, Licensee shall not be required to grant a license: 

(i) 

(ii) 

(iii) 

to a licensee not willing to grant a reciprocal license under its patent rights to Licensee 

and to any other party seeking such license with respect to the enforcement of such 

licensee’s patent claims where there is no technically feasible alternative that would avoid 

the infringement of such claims (with respect to Licensee’s exercise of the rights 

described in subparagraphs (iv) – (v) immediately above); or 

with respect to any portion of any product and any combinations thereof the sole purpose 

and function of which is not required in order to be fully compliant with the Specification: 

with respect to technology that is not required for at least one of the following: using the 

Reference Implementation, using the TCK, or developing, distributing or using an 

Independent Implementation. 

1.8 Licensee’s licenses to Ericsson’s own patent rights granted under this Agreement shall be considered null 

and void should Licensee initiate a claim that Ericsson has, in the course of performing its duties as 

Ericsson, induced any entity to infringe Licensee’s patent rights. 

1.9 For the purposes of Sections 1.6-1.8 above, Licensee shall mean “Licensee” and any party for which 

Licensee are authorized to act with respect to the Java Specification Participation Agreement applicable to 

the Specification. 

1.10 This Agreement will terminate immediately without notice from Ericsson if Licensee fails to comply with any 

material provision of this Agreement or act outside the scope of the licenses granted above. 

2 TRADEMARKS 

2.1 Licensee’s access to this Specification shall not be construed as granting, any license or right to use any 

marks appearing in the Specification without the prior written consent of Ericssonand or Ericsson’s 

licensors. 

2.2 Licensee shall not be allowed to remove any of the copyright statements or disclaimers or other proprietary 

notices contained in the Specification and Licensee are obliged to include the copyright statement and the 

disclaimers, if any, in any copies of the Specification Licensee makes. 

3 DISCLAIMER OF WARRANTIES 

3.1 SUBJECT TO ANY STATUTORY WARRANTIES OR CONDITIONS WHICH CANNOT BE EXCLUDED, 

THE SPECIFICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OR CONDITION OF ANY KIND 

EITHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED 

WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE 

AND NON-INFRINGEMENT. ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, AND 

STATUTORY ARE HEREBY DISCLAIMED. THE ENTIRE RISK ARISING OUT OF OR RELATING TO THE 

USE OR PERFORMANCE OF THE SPECIFICATION REMAINS WITH LICENSEE. 


3.2 THE SPECIFICATION MAY INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. 

CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE 

INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. ERICSSON MAY MAKE 

IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED 

IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by 

the then-current license for the applicable version of the Specification. 

4 LIMITATION OF LIABILITY 

4.1 TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL ERICSSON OR ITS SUPPLIERS 

BE LIABLE FOR ANY LOST PROFITS, LOST SAVINGS, LOST REVENUE, LOST DATA, 

PROCUREMENT OF SUBSTITUTE GOODS, OR FOR ANY DIRECT, INDIRECT, INCIDENTIAL, 

SPECIAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, EVEN IF THE SPECIFICATION LEAD OR ITS 

SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. IN 

ADDITION ERICSSON AND ITS SUPPLIERS WILL NOT BE LIABLE FOR ANY DAMAGES CLAIMED BY 

LICENSEE BASED ON ANY THIRD PARTY CLAIM. 

4.2 Some jurisdictions do not allow the exclusion of implied warranties, or the limitation for consequential 

damages, so Section 4.1 may not apply to Licensee in whole, but in such case Section 4.1 will apply to 

Licensee to the maximum extent permitted by applicable law. 

4.3 Licensee will indemnify, hold harmless, and defend Ericsson and its licensors from any claims arising or 

resulting from: (i) Licensee’s use of the Specification; (ii) the use or distribution of Licensee’s Java 

application, applet and/or Independent Implementation; and/or (iii) any claims that later versions or 

releases of any Specification furnished to Licensee are incompatible with the Specification provided to 

Licensee under this license. 

5 FEEDBACK 

5.1 The following paragraph applies to Licensee only if Licensee is not (i) a member of Java Community 

Process, or (ii) bound by obligations of the Java Specification participation Agreement or Individual Expert 

Participation Agreement applicable for the Specification. 

5.2 Licensee may wish to report any observations, ambiquities, inconsistencies or inaccuracies Licensee may 

find in connection with Licensee’s use and implementation of the Specification (“Feedback”). To the extent 

that Licensee provides Ericsson with any Feedback, Licensee hereby: (i) agree that such Feedback is 

provided on a non-proprietary and non-confidential basis, and (ii) grants to Ericsson a perpetual, 

non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple 

levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose 

related to the Specification and future versions, implementations, and test suites thereof. 

6 EXPORT CONTROL 

6.1 Licensee shall follow all export control laws and regulations relating to Specification. 

7 RESTRICTED RIGHTS LEGEND 

7.1 Note to U.S. Government Users. The Specification is a “Commercial Items”, as that term is defined at 48 

C.F.R. 2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software 

Documentation”, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R.227.7202, as applicable. 

Consistent with 48 C.F.R.12.212 or 48 C.F.R.227.7202-1 through 227.7202-4, as applicable, the 

Commercial Computer Software Documentation are being licensed to U.S. Government end users a) only 

as Commercial Items and b) with only those rights as are granted to all other end users pursuant to the 

terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. 

8 GOVERNING LAW AND ARBITRATION 

8.1 This agreement shall be governed by and construed in accordance with the laws of Sweden, without regard 

to its conflict of law rules. 

8.2 The English language shall be used in all documents and correspondence related to this agreement. 


8.3 The Parties shall use their best efforts to settle by amicable negotiations any differences, which may occur 

between them in connection with this agreement. If the Parties fail to reach such an amicable settlement 

within thirty (30) days from the commencement of such amicable negotiations, either party may refer such 

differences to arbitration as provided below. 

8.4 All disputes, differences or questions arising out of or in connection with this agreement shall be finally 

settled under the Rules of Arbitration of the International Chamber of Commerce by three (3) arbitrators 

appointed in accordance with the said rules. The arbitral proceedings shall be conducted in the English 

language and shall take place in Stockholm, Sweden. All awards shall be final and binding and may if 

necessary be enforced by any court having jurisdiction in the same manner as a judgement in such court. 

8.5 The Parties undertake and agree that all arbitral proceedings conducted under this section 8 shall be kept 

strictly confidential, and all information, documentation, materials in whatever form disclosed in the course of 

such arbitral proceeding shall be used solely for the purpose of those proceedings. 

8.6 Notwithstanding the aforesaid, nothing in this Section 8 shall prevent the Parties from seeking any interim or 

final injunctive or equitable relief by a court of competent jurisdiction. 

9 GENERAL 

9.1 The legality of any part of this Agreement shall not affect the legality of any other part. If any provision of this 

Agreement shall be held by a court of competent jurisdiction to be invalid, illegal or unenforceable, the 

validity, legality and enforceability of the remaining provisions shall in no way be affected or impaired 

thereby and the invalid illegal or unenforceable 

9.2 If a court or agency of competent jurisdiction holds any term of this Agreement invalid, illegal, or 

unenforceable for any reason, the remainder of this Agreement shall be valid and enforceable and the 

Parties shall negotiate in good faith a substitute, valid, enforceable provision which most nearly effects the 

parties intent in entering into this Agreement. 


Contents 

JSR 281 IMS Services API..........................................................................................................................................1 

Preface .........................................................................................................................................................................7 

Package javax.microedition.ims .............................................................................................................................24 

Class Configuration.................................................................................................................................................32 

Class ConnectionState............................................................................................................................................36 

Interface ConnectionStateListener..........................................................................................................................38 

Class ImsException.................................................................................................................................................40 

Interface ReasonInfo...............................................................................................................................................41 

Interface Service .....................................................................................................................................................43 

Class ServiceClosedException ...............................................................................................................................45 

Package javax.microedition.ims.core.....................................................................................................................46 

Interface Capabilities...............................................................................................................................................48 

Interface CapabilitiesListener..................................................................................................................................51 

Interface CoreService .............................................................................................................................................52 

Class CoreServiceException...................................................................................................................................58 

Interface CoreServiceListener.................................................................................................................................59 

Class ImscoreProtocolPermission ..........................................................................................................................61 

Interface Message...................................................................................................................................................64 

Interface MessageBodyPart....................................................................................................................................70 

Interface PageMessage ..........................................................................................................................................72 

Interface PageMessageListener .............................................................................................................................76 

Interface Publication................................................................................................................................................77 

Interface PublicationListener...................................................................................................................................81 

Interface Reference.................................................................................................................................................83 

Interface ReferenceListener....................................................................................................................................91 

Interface ServiceMethod .........................................................................................................................................93 

Interface Session.....................................................................................................................................................98 

Interface SessionDescriptor ..................................................................................................................................111 

Interface SessionListener......................................................................................................................................115 

Interface Subscription ...........................................................................................................................................118 

Interface SubscriptionListener...............................................................................................................................122 

Package javax.microedition.ims.core.media .......................................................................................................124 

Interface BasicReliableMedia................................................................................................................................126 

Interface BasicReliableMediaListener...................................................................................................................129 

Interface BasicUnreliableMedia ............................................................................................................................130 

Interface BasicUnreliableMediaListener ...............................................................................................................133 

Interface FramedMedia .........................................................................................................................................134 

Interface FramedMediaListener ............................................................................................................................140 

Interface Media......................................................................................................................................................143 

Interface MediaDescriptor .....................................................................................................................................152 

Interface MediaListener.........................................................................................................................................156 

Class MediaPermission.........................................................................................................................................157 

Interface StreamMedia..........................................................................................................................................160 

Appendix A: Implementation guidelines ..............................................................................................................166 

Appendix B: MIDP 2.0 PushRegistry for JSR 281 ...............................................................................................195 


Preface 

This document defines the IMS Services API (IMSAPI), a Java API for the IP Multimedia Subsystem (IMS) on 

mobile devices. The IMSAPI is an optional package for the Java ME platform. The API provides a toolbox of IMS 

building blocks which the developer can use to create IMS applications. IMS is an effort driven by the telecom world 

to build multimedia rich highly networked services and applications for the new high capacity IP based 

telecommunication networks. Java can play an important role in the deployment and adoption of IMS at large, 

because of the volume of installed Java profiles on mobile devices. The IMSAPI is designed accordingly. 

The API features a high level of abstraction, hiding the technology and protocol details, but can still prove to be 

useful and powerful enough for non-experts in IMS to create new IMS applications. Therefore, the IMSAPI is useful 

for the entire Java ME developer community. The knowledge required to create simple IMS applications is how to 

use a telephone for ordinary voice calls, and some programming experience on the MIDP2.0 platform. Creating an 

IMS-aware application is only just a few steps away. It allows the developer to concentrate on the logic of the 

application. To satisfy Java developers who know IMS, the API provides limited access to the underlying protocols 

using low level APIs in a controlled way. 

If a developer has an idea for an application that includes a component for sharing multi-media content with others, 

then the IMSAPI is a JSR to consider. 

Revision History 

Date Version Description 

10-February-2006 IMS Specification First draft provided by the Specification Lead 

18-July-2006 

Draft version 0.2 Changes and clarifications 

25-July-2006 Draft version 0.3 Changes as a consequence of F2F meeting Kista 06/06 

27-September-2006 EDR version 0.4 Proposal for Early Draft Review 

31-October-2006 

EDR version 0.5 Early Draft Review 

7-September-2007 PDR version 0.9 Proposal for Public Draft 

29-February-2008 

PFD version 0.95 Proposed Final Draft 

13-June-2008 FR version 1.0 Final Release 

08-April-2009 MR version 1.1 Maintenance Release 

Who Should Use This Specification 

This document is targeted at the following audiences: 

• The Java Community Process (JCP) expert group defining this optional package. 

• Implementers of IMSAPI. 

• Developers writing applications using the IMSAPI. 

• Network operators deploying infrastructure to support IMSAPI enabled devices. 

How This Specification Is Organized 

The document is composed of the Preface part, JavaDoc documentation of the IMSAPI packages, and an appendix. 

It is intentional that it is sufficient for an application developer to have to look only at the JavaDoc parts. The 

appendix is used as a guide for implementers of the specification. 

References 

This reference list is informational. 


• [JSR75] JSR 75 FileConnection API 

• [JSR118] JSR 118 MIDP2.1 

• [JSR135] JSR 135 Mobile Media API 

• [JSR139] JSR 139 CLDC 1.1 

• [JSR307] JSR 307 Network Mobility and Mobile Data API 

• [23.003] 3GPP TS 23.003 Numbering, addressing and identification. Release 6 

• [22.228] 3GPP TS 22.228 Service requirements for the Internet Protocol (IP) Multimedia Core Network 

Subsystem; Stage 1, Release 6 

• [23.228] 3GPP TS 23.228 IP Multimedia Subsystem (IMS). Stage 2, Release 6 

• [24.229] 3GPP TS 24.229 IP Multimedia Call Control Protocol based on Session Initiation Protocol (SIP) 

and Session Description Protocol (SDP). Stage 3, Release 6 

• [26.114] 3GPP TS 26.114 Multimedia Telephony; Media handling and interaction. Release 7. 

• [26.235] 3GPP TS 26.235 Packet switched conversational multimedia applications; Default codecs 

• [26.244] 3GPP TS 26.244 3GPP file format (3GP). Release 6 

• [RFC2045] RFC 2045 Multipurpose Internet Mail Extensions (MIME) Part One 

• [RFC2046] RFC 2046 Multipurpose Internet Mail Extensions (MIME) Part Two 

• [RFC2119] RFC 2119 Key words for use in RFCs to Indicate Requirement Levels 

• [RFC2215] RFC 2215 General Characterization Parameters for Integrated Service Network Elements 

• [RFC2396] RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax 

• [RFC3261] RFC 3261 SIP Session Initiation Protocol 

• [RFC3515] RFC 3515 The Session Initiation Protocol (SIP) Refer Method 

• [RFC3840] RFC 3840 Indicating User Agent Capabilities in the Session Initiation Protocol (SIP) 

• [RFC3841] RFC 3841 Caller Preferences for the Session Initiation Protocol (SIP) 

• [RFC3966] RFC 3966 The tel URI for Telephone Numbers 

• [RFC4145] RFC 4145 TCP-Based Media Transport in the Session Description Protocol 

• [RFC4488] RFC 4488 Suppression of Session Initiation Protocol (SIP) REFER method Implicit Subscription 

• [RFC4566] RFC 4566 SDP Session Description Protocol 

• [RFC4975] RFC 4975 The Message Session Relay Protocol 

• [RFC5322] RFC 5322 Internet Message Format 

• [draft-ietf-simple-msrp-acm-00] IETF Internet Draft draft-ietf-simple-msrp-acm-00.txt 

Terms and Abbreviations 

Terms and abbreviations used in the document: 

• 3GPP: Third Generation Partnership Project. Standardizes mobile communication. 

• AMS: Application Management System. 

• Application Capability: Name for composed non-standard capability. This capability includes 

application-specific IMS logic. 

• Access Network: The network used to access the IMS network. 

• Application Capability: A capability attributed to an IMS application. 

• AppId: IMSAPI Application Identifier. 

• Basic capability: A built-in capability of the IMSAPI, and is either a media type or an event package. 

• BasicMedia: Collective name for BasicUnreliableMedia and BasicReliableMedia media types. 

• canRead: A media mode property that if set to true, enable reading data from the media flow. 

• canWrite: A media mode property that if set to true, enable writing data to the media flow. 

• Capability: The ability of a device to process a particular kind of content. 

• Composed capability: A capability that has been built up of other capabilities. (See Basic capability). 

• exists: a media mode property that if true, means that the data flow is created. 

• Feature: Describes an aspect of a device or resource. 

• Feature Tag: The syntax of a feature. 

• Flowspec: Flow specification. 

• GCF: Generic Connection Framework. 

• IARI: IMS Application Reference Identifier. 

• ICSI: IMS Communication Service Identifier. 

• IETF: Internet Engineering Task Force. Standardizes Internet communication in the form of RFCs. 

• IMS: IP Multimedia Subsystem. 

• IMSAPI: Java JSR 281 IP Multimedia Subsystem API. 

• IMS Application: A realization of a number of IMS capabilities for a well-defined end user purpose. 


• imscore: connector string: A string specification used as input to create a core service object 

• [media] mode property: one of exists, canRead and canWrite: a boolean property that describes the state 

of a media data flow 

• MSRP: Message Session Relay Protocol. A protocol for transmitting a series of related instant messages in 

the context of a session. 

• Originating endpoint: The endpoint that is initiating an IMS communication. 

• PoC: Push-to-talk Over Cellular. 

• PSI: Public Service Identifier. 

• QoS: Quality of Service. 

• RFC: Request For Comment. Documents delivered by IETF. 

• Service: When used as a technical term in the IMSAPI, it represents a context of service methods. 

• Service Method: A common name for end-to-end forms of communication in the IMSAPI: Session, 

Capability, Publication, Subscription, PageMessage and Reference. 

• SDP: Session Description Protocol. 

• SIP: Session Initiation Protocol. 

• Terminating endpoint: The endpoint that is receiving an IMS communication. 

• User Identity: An IMS Public User Identity. 

• URI: Uniform Resource Identifier. 

• URN: Uniform Resource Name. A type of URI. 

JSR 281 Expert Group 

The following companies, listed in alphabetical order, were members of the JSR 281 Expert Group: 

• China Mobile Communications Co. Ltd 

• Ericsson AB 

• Esmertec AG 

• IBM 

• Infineon Technologies AG 

• LG Electronics Inc. 

• Lucent Technologies 

• Motorola 

• NEC Corporation 

• NMS Communications 

• Nokia Corporation 

• Orange France SA 

• Qisda Corporation 

• Research In Motion, LTD (RIM) 

• Samsung Electronics Corporation 

• SBC 

• Siemens AG 

• Sirf Technology Holdings, Inc 

• Sony Ericsson Mobile Communications AB 

• Sprint 

• Sun Microsystems, Inc. 

• T-Mobile Austria GmbH 

• Telecom Italia 

• Vodafone Group Services Limited 

Document Conventions 

This document uses definitions based upon those specified in [RFC2119]. 

Term 

MUST 

MUST 

NOT 

Definition 

The associated definition is an absolute requirement of this specification. 

The definition is an absolute prohibition of this specification. 


SHOULD 

SHOULD 

NOT 

MAY 

Indicates a recommended practice. There may exist valid reasons in particular circumstances to ignore 

this recommendation, but the full implications must be understood and carefully weighed before 

choosing a different course. 

Indicates a non-recommended practice. There may exist valid reasons in particular circumstances 

when the particular behavior is acceptable or even useful, but the full implications should be 

understood and the case carefully weighed before implementing any behavior described with this label. 

Indicates that an item is truly optional. 

Formatting Conventions 

This specification uses the following formatting conventions. 

Convention Description 

Courier New Used in all Java code including keywords, data types, constants, method names, variables, class 

names, and interface names. 

Italic Used for emphasis and to signify the first use of a term. 

Report and Contact 

Your comments on this specification are welcome and appreciated. Please send your comments to: 

jsr-281-comments@ericsson.com 

Overview 

IP Multimedia Subsystem 

The IP Multimedia Subsystem (IMS) can be seen as an evolution of the traditional voice telephone systems, taking 

advantage of high speed data networking, multimedia, and increased processing power in end user devices. 

However, many old principles are still preserved. An operator runs a network, allowing subscribers (e.g. Alice and 

Bob) to attach their devices to network endpoints. Alice and Bob get unique identities on the network. Alice can call 

Bob using his identity. The network creates a path between Alice's and Bob's devices for the call and they can start 

their exchange. The exchange part is where the most obvious difference is; going from the single media of voice in 

telephony to multimedia in IMS. 

Single- and Multimedia 

The media is the part that has changed most. For ordinary telephony, it was a single media format of voice 

between Alice and Bob. In IMS, Alice and Bob can handle media in multiple formats that can be any combination of 

the following: Video and audio streaming (including voice), instant messaging (as in a chat), exchange of any 

application-specific data (as in gaming). This degree of freedom in media formats has major implications for the 

functionality of Alice's and Bob's devices (described below). 

IMS Call 

Making an IMS call follows the traditional telephony pattern. Suppose Alice wants to call Bob. Then Alice is the 

originating endpoint, and Bob is the terminating endpoint. At Alice's device, the following procedure applies: 

1. Start the calling application on the device. 

2. Identify Bob's identity (possibly with the help of the phone book). 

3. Wait for answer. 

4. At answer, communication begins. 

5. Later, the communication ends by hanging up. 

Procedure at Bob's device: 

1. Phone is ringing, and the called application is shown on the device screen. 

2. Bob decides to take the call. 

3. Communication takes place. 


4. Hang up. 

If Alice wants to call a service (that is, where the remote end is not a subscriber), she does it the same way but 

uses its service identity instead of a subscriber. 

Even though IMS is (here) seen as an evolution of telephony, there are important contributions from data 

communication seen in many places of IMS. An IMS enabled device can in general handle several IMS calls to 

many subscribers and network services at the same time. It is similar to how a computer can handle multiple 

network connections to one or several other computers. The precise behavior is application-specific, but it should 

be remembered that just because one IMS call is active, it does not imply that other calls cannot be handled. 

User identification in IMS 

IMS users are reachable on the IMS networks with their Public User Identities, that takes the form of an Uniform 

Resource Identifier (URI). Two types of URI are supported: 

• A SIP URI (as defined in RFC3261), like sip:alice@ims.example.com. Such URIs are suitable for use from 

the Internet. 

• A TEL URI (as defined in RFC3966), like tel:+4680123456. This format enables an IMS terminal to be 

reachable in traditional telephone networks. 

The operator allocates one or more public user identities for use within a subscription. 

When the device is switched on and connects to the IMS network, the device and the network engage in a process 

called IMS registration to make the user reachable under some of the identities. 

It is possible to be reachable using several public user identities at the same time. For example, if a SIP identity 

works on the Internet, and the TEL identity on the telephone network, it makes sense to have them both registered 

at the same time to be equally reachable from both worlds. The operator usually makes sure that in such case, if 

the user wants to be reachable on one of them, it implies also being reachable from the other. 

Service Identification in IMS 

Services in traditional telephony, like conferencing or supplementary service self administration, are accessed 

using special phone numbers. A similar situation holds in IMS where a service is accessed using a Public Service 

Identity. If Alice wants to take part in a conference, she dials into the conference using its public service identity. 

The conference server arranges for her participation. The identity is formatted as a SIP URI. 

User and Service Addressing 

In the IMSAPI, the user can influence registration by indicating the public user identity the user would like to be 

reachable under on the terminal via the call to Connector.open. 

To establish communications to remote endpoints on the IMS network, the JSR provides a set of interfaces called 

Service methods. To create a Service method, an address to the remote is given in the to argument in the form of 

a SIP or TEL URI. Examples: 

sip:alice@atlanta.com 

sip:bob@biloxi.com 

tel:+358-555-1234567 

tel:863-1234;phone-context=+1-914-555 

tel:7197999;phone-context=ims.mnc015.mcc235.3gppnetworks.org 

The URI can be a public user identity or a public service identity as explained above, but does not have to. The 

argument accepts an optional display name, and in that case the URI is surrounded with angle brackets. For 

example: 

Bob 

Alice Smith 

The URI can be a public user identity or a public service identity. 


The From argument accepts an URI with optional display name, that indicates the originator of the request. The 

argument is the identity to be presented as when the request reaches the remote. If the argument is null then it is 

by default set to the preferred public user identity. If it includes an URI with the domain anonymous.invalid then 

the request will be anonymized. 

The format of SIP URI is described in [RFC3261], TEL URI in [RFC3966], and display names in general in 

[RFC5322]. 

IMS and JSR 281 

The transition from single-media in voice telephony, to multi-media formats in IMS, means that the subscriber 

devices need the capability to handle such media. This is made possible since the phone has evolved from being a 

single-purpose device into a multi-purpose device. The devices can now also differ in their capabilities. 

Single-media handling capability in voice telephony 

In a network connecting only single purpose devices like traditional voice, it is assumed that all devices share that 

voice capability, regardless of their model and manufacturer. The network operator decides the standard to use 

such that all devices handle voice the same. If they don't they will not operate together. All devices are equivalent in 

terms of voice interoperability, and they have been developed for that purpose. When Alice calls Bob, she does not 

care about Bob's phone model, the brand or other particular characteristics; only that she can talk to him. For Alice 

to call Bob, their devices need to be the same in this respect. It creates symmetry of equivalence in capabilities 

between the endpoints in the context of the call made. Before IMS, the equivalence could be assumed to hold for 

voice and was trivial, but with IMS it is a problem that needs to be solved. 

Multiple-media handling capabilities in IMS 

The devices on the IMS vary in the multi-media capabilities and data formats they are capable of handling. For 

example, suppose a mobile phone and a PDA can do instant messaging. Then they are equivalent because they 

have that particular capability in common. Suppose further that the phone can do high quality voice communication, 

or that the PDA can stream live video from its high resolution built-in camera. If these capabilities are not met, there 

is no equivalence and it is meaningless to try to set up the calls. 

A shared symmetrical view of IMS devices cannot be assumed from just their presence on the network. It is crucial 

to decide whether they are equivalent when making an IMS call so that the multimedia exchange can work between 

the endpoints in the way intended. Internet and IMS standards use a notation that allows an IMS device to be 

marked as having certain capabilities. The set of common markers for a pair of devices describes the shared 

capabilities. If an IMS call requires a certain capability and its marker is in the common set, then there is 

equivalence. Advantages with this approach are that it will work regardless of device characteristics, and that new 

markers can be added for devices with new capabilities. A marker in a common set shows that capability can be 

used regardless of its semantics. 

The scheme of computing capabilities works not only for devices with a fixed set of built-in capabilities. It can also 

work for devices with a changeable set as well. Hardware related capabilities can change with plug-in accessories. 

Software related capabilities can change with downloadable applications. This latter approach is made possible 

with the IMS application model that the JSR 281 assumes. 

Capabilities of a JSR 281 IMS Application 

When writing an IMS application in JSR 281, it is fundamental to indicate its complete set of capabilities, the 

application capabilities, in the correct way. This is necessary for an IMS call to be routed through the IMS network 

to the right IMS application on the right device of the called subscriber. 

The application capabilities follow from the application program and are known at development time. When writing 

the application, the developer records the capabilities to be installed together with the application onto the end user 

device. 

The capabilities are of two types, basic and composed, described next. 

Basic Capabilities 


Basic capabilities are known in the IMSAPI. The IMS application gets them as a result of interacting with certain 

interfaces to IMS functionalities. Basic capabilities are of two subtypes: 

• Media capabilities, caused from using media interfaces. 

• Event capabilities, caused from using Subscription and Publication interfaces with event packages. 

The notation of capabilities, in relation to the Registry description, are described further below. 

Composed Capabilities 

Composed capabilities are capabilities that originate in the application, and are unknown to the IMSAPI. They can 

be composed of basic capabilities and other functionality. 

ICSI and IARI according to 3GPP standards 

3GPP has defined a framework to cover capabilities used in standardized network-based services. If a device 

implements a client for such a service, the capability is indicated in an IMS Communication Service Identifier (ICSI). 

The ICSI is defined in the service standard. The following is an example of an ICSI that may be defined by 3GPP 

for use in Multimedia Telephony standard: 

• urn:urn-xxx:3gpp-service.ims.icsi.mmtel 

The network operator manages the services, and an end user is allowed access to the service according to the 

subscription. Examples of services that can be coded as ICSIs are instant messaging, conferencing, Push-to-Talk 

Over Cellular (PoC). 

One of the strengths of IMS, and a prime purpose of the JSR 281, is to allow developers to write new IMS based 

applications, and have end users download and install them into their devices. These IMS applications have not 

undergone a standardization process, and have new capabilities not seen on the network before. This can for 

example be peer-to-peer games, or a new application of an existing network service, or some combination. To 

indicate such altogether new application capabilities, the IMS Application Reference Identifier (IARI) is used. The 

chess game could have an IARI that looks something like: 

• urn:IMSAPI:com.myCompany.chess 

Usage of ICSI and IARI 

An IMS application can support several ICSIs and IARIs at any given time. This section discusses the effect of 

using various combinations. 

Having multiple ICSIs has a straightforward use case where the IMS application is a client towards several 

standardized network communication services. 

An application that realizes several IARIs, might seem less logical considering the explanation above, but is useful 

in the following scenario. Suppose two IMS applications are developed, and are given IARI1 and IARI2, 

respectively. The applications become successful and well known. Then a third application is developed that adds 

a new functionality, while still supports both old applications. The third application gets, in addition to its IARI3, 

IARI1 and IARI2 as well. This enables backward compatibility. 

An IMS application can have any combination of ICSI and IARI. If it has no ICSI and no IARI, it means that no 

particular network services are used and the application adds no extra capability in itself. Such an application builds 

only on standardized media capabilities, or on standardized capabilities for a service not part of the ICSI/IARI 

framework. Examples are a streaming media player, a peer-to-peer chat application, or an application building on a 

standard outside the 3GPP application reference. If it has ICSI and no IARI, the application realizes a client for the 

service according to the standard, a default application. If it has no ICSI but an IARI, the application realizes its new 

logic without using any particular network service. Many peer-to-peer applications, like games, would be in this 

category. If it has both ICSI and IARI, the application makes use of standardized network service to create a new 

capability. 

Note on the format of ICSI and IARI 


ICSI and IARI are represented as Universal Resources Names (URN). URNs consists of a name space, and a 

name space specific string. The owner of the name space has control over allowed URNs. For ICSI, the 

standardisation organization is the name space owner and it has defined the ICSI URN. For IARI, the URNs are 

issued from any valid name space owner. The process of how to allocate an IARI is outside the scope of this 

specification. 

ICSI and IARI Recommendations in JSR 281 

When developing IMS applications in the IMSAPI, it is normal practice to assign them IARIs for the necessary 

network and device routing. The IMSAPI implementation makes sure the application has an appropriate network 

behavior. The developer has the responsibility to create the appropriate IARI according to the procedure of the 

name space owner, and tag it to the application for distribution. 

If an IMS application includes a communication service, the recommended procedure is to use an enabler API for 

that service if available, and the ICSI is handled according to the definition of that enabler API. No such enablers 

are part of JSR 281, but may be in other complementary JSRs. Nonetheless, JSR 281 offers the possibility for an 

application to implement a client for a communication service on top of the IMSAPI where the developer explicitly 

tags the IMS application with an ICSI, and possibly also with the "explicit" and "require" parameters (see 

[RFC3841]). This is an advanced functionality, and should be used with caution because JSR 281 cannot enforce 

that the application is according to the standard specification. 

Feature Tags 

There are IMS related standards that can be implemented as an IMS application, that have their own set of feature 

tags, including the "explicit" and "require" parameters (see [RFC3841]), that are not part of the 3GPP ICSI and IARI 

framework. These feature tags should be considered as alternatives to ICSI and are indicated with the application. 

The same recommendations apply as for the ICSI case. There can be several feature tags, and can be combined 

with ICSI and IARI. 

Application Control of Capability Usage 

When the IMS application makes an IMS call, a set of capabilities is included such that the IMS network and the 

remote device can route the call correctly. 

For many IMS applications, that set contains all application capabilities. Hence, all IMS calls are handled the same 

way. Other applications are required to handle certain calls differently based on the semantics of the capabilities. 

The JSR 281 supports creating named subsets of the composed capability set, and then making IMS calls based 

on those sets. This way, an improved granularity and diversification of IMS calls is achieved. 

IMS Applications 

The general JSR 281 IMS application model defines an IMS application as: 

• A realization of one or more IMS capabilities for some well defined end user purpose. 

The definition is useful because any arbitrary set of capabilities, or markers, does not make sense unless they are 

part of a function. It enables a simpler view of interoperability. If a pair of devices has an equivalent IMS application, 

they can communicate. Note that the concept of an IMS application is independent of programming language, APIs, 

and devices. Even though the model is employed in JSR 281, it is independent of its particular interfaces and Java. 

It is important to keep IMS application and Java application as distinct concepts, even though they are related in 

the IMSAPI. 

An IMS application can be implemented on some device, perhaps using special hardware and software interfaces. 

All possible implementations can be seen as portings, some can be based on the JSR 281. On a particular device, 

there can be several coexisting implementations of the same IMS application, differing in any non-interoperability 

related aspect, for example, look and feel. 

On the IMS network, any device with a particular IMS application implementation is a potential target for a 

successful IMS call. 


An IMS application, like many other applications, has a life cycle. It can be installed to, executed on, and 

uninstalled from, a device. How this works for JSR 281 is explained further below. 

The relation an IMS application has towards the IMS device is similar in many respects (but not all) to the relation 

an IMS device has to its network. The network is responsible for routing an IMS call to the appropriate device; the 

device routes an incoming call to the right IMS application. An IMS device can be on or off the network; an IMS 

application can be installed or uninstalled. The IMS device exposes its capabilities on the network; an IMS 

application exposes its capabilities to the device. 

myChess: An example IMS-based game 

An example IMS application that may be suitable to implement using the IMSAPI, is a networked chess application 

called myChess. The application allows the user (Alice) to initiate an IMS call to a peer (Bob) with an invitation to 

play chess. If Bob accepts, the call is established and a new game begins, or a saved one resumes. When one of 

the players makes a move, it is sent over a media stream to the other endpoint which updates its game state. To 

further increase the gaming experience, the IMS application polls the presence of potential players and displays it 

to the user on demand. The game allows the players to chat. 

In addition, myChess can manage several chess game sessions at the same time. 

The chess application will be used in this specification to illustrate various aspects of the IMSAPI. 

Summary 

This completes the description of the IMSAPI model of IMS applications. A Java application realizes a number of 

IMS applications in its program code. An IMS application is defined as purposefully realizing a number of IMS 

capabilities, Basic and Composed. Basic capabilities are from the IMSAPI, composed capabilities are application 

intrinsic. The application is identified using an internal handle, the application identifier (the AppId). All IMS 

applications have static properties, some of which are capability related. To account for the diversity of capabilities 

with different semantics, the IMSAPI introduces the Core service objects to group capabilities that can be handled 

the same. Core services are the platform which the application then uses to make and receive IMS calls end-to-end, 

that is, sessions with different types of media for different capabilities. 

Further reading of IMS 

The IMSAPI is primarily based on 3GPP IMS Release 6. The Stage 1 Service Requirements Specification [22.228] 

provides an introduction to IMS that is also useful for those who are not experts. The Stage 2 Group Services and 

System Aspects [23.228] and the Stage 3 describe the architecture, technical realization and protocol details of the 

IMS [24.229]. These documents are for the most technically interested reader. 

The concept of IMS applications of the IMSAPI is rooted in the 3GPP explanation of the term in [22.228] 

reproduced here: 

"IP multimedia application: an application that handles one or more media simultaneously such as speech, audio, 

video and data (e.g. chat text, shared whiteboard) in a synchronized way from the user’s point of view. A 

multimedia application may involve multiple parties, multiple connections, and the addition or deletion of resources 

within a single IP multimedia session. A user may invoke concurrent IP multimedia applications in an IP multimedia 

session." - [22.228, section 3.1]. 

The last sentence seems to contradict the definition of IMS applications and IMS session used in the IMSAPI. This 

is however not the case. The 3GPP definition relates to multiple usage of media streams within a session. In the 

IMSAPI, any such functionality can be aggregated within a single IMS application using multiple Core Service 

objects. 

The IMS capabilities play a very central role in the IMSAPI. In the 3GPP specifications, capabilities are less 

emphasized in the texts. This is because JSR 281 describes a framework of IMS applications, which 3GPP leaves 

open in its specifications. For the framework to function correctly for multiple IMS applications, and possible to 

scale, capabilities are absolutely necessary. The support for ICSI and IARI as capabilities is part of 3GPP Release 

7. 


The capabilities framework of the IMSAPI is based on IETF RFCs [RFC3840, RFC3841] for the caller preferences 

framework. 

The IMS uses SIP and SDP as its main signaling protocols. This is described in [RFC3261] and [RFC4566]. 

User and Service Addressing 

In the IMSAPI, the user can influence registration by indicating the public user identity the user would like to be 

reachable under on the terminal via the call to Connector.open. 

To establish communications to remote endpoints on the IMS network, the JSR provides a set of interfaces called 

Service methods. To create a Service method, an address to the remote is given in the to argument in the form of 

a SIP or TEL URI. Examples: 

sip:alice@atlanta.com 

sip:bob@biloxi.com 

tel:+358-555-1234567 

tel:863-1234;phone-context=+1-914-555 

tel:7197999;phone-context=ims.mnc015.mcc235.3gppnetworks.org 

The URI can be a public user identity or a public service identity as explained above, but does not have to. The 

argument accepts an optional display name, and in that case the URI is surrounded with angle brackets. For 

example: 

Bob 

Alice Smith 

The URI can be a public user identity or a public service identity. 

The From argument accepts an URI with optional display name, that indicates the originator of the request. The 

argument is the identity to be presented as when the request reaches the remote. If the argument is null then it is 

by default set to the preferred public user identity. If it includes an URI with the domain anonymous.invalid then 

the request will be anonymized. 

The format of SIP URI is described in [RFC3261], TEL URI in [RFC3966], and display names in general in 

[RFC5322]. 

Overview IMS Applications in IMSAPI 

The IMSAPI is an API for programming IMS applications in Java. The underlying execution environment for the IMS 

applications is called the IMS Engine. The API provides interfaces to allow the IMS applications access to IMS 

functionality. 

An IMS application consists of three parts in the API: 

• IMS application identifier (AppId): A string uniquely identifying the IMS application in the suite. 

• Java program: This is the Java application that realizes the IMS application logic, called the owning Java 

application. 

• The Registry: A set of static properties including the IMS application capabilities. The IMS engine keeps the 

Registry in a data base. 

The IMS engine associates the three parts, such that it is known which Java application that realizes a particular 

IMS application. A Java application can realize one or more IMS applications. Even though the underlying Java VM 

may only be capable of running a single Java application at the moment, multiple IMS applications can be running. 

Java and IMS application suites are related in the sense that the Java suite owns the IMS suite. When the Java 

suite is installed/uninstalled, the IMS suite is installed/uninstalled as well. 

The IMS application developer writes the JSR 281 MIDlets and defines the Registry contents before packaging the 

suite. The jad file or jar manifest file contains properties that defines the AppId, Registry and the owning Java 


MIDlet (in case the profile is MIDP). The jar/jad files are downloaded to the device and installed using the 

mechanisms that applies for the profile. For example, the chess application could include a line in the MIDP jad file: 

MicroEdition-IMS-1-Identity: myChess, com.company.MyChess 

where myChess is the AppId, and com.company.MyChess is the MIDlet class name. The MIDlet will as the first step 

connect the IMS application to the IMS network. JSR 281 makes use of the Generic Connection Framework (GCF) 

of CLDC, and the code looks like: 

cs = (CoreService)Connector.open("imscore://myChess"); 

The call has the following effects: 

• The MIDlet has a handle to the IMS engine to further work with that IMS application. 

• The IMS engine creates a connection to the IMS network where this IMS application becomes visible, 

meaning that it is possible to initiate and receive IMS calls with it according to the capabilities in the users 

IMS subscription with the operator. 

Later in its code, the MIDlet can create IMS calls using the JSR 281 core interfaces: 

session = cs.createSession("Alice ", "Bob "); 

For further information on the jad file properties, Registry and installation aspects, see the package description of 

javax.microedition.ims. For further information on how to use the core apis and create IMS calls, refer to 

javax.microedition.ims.core package. 

The integration to GCF enables two opportunities for the developer. Firstly, a connection in the particular access 

network could be created using some other API (e.g. the JSR 307 [JSR307]) and some desired characteristics, like 

bandwidth and delay constraints. Then that connection can be reused for the imscore: connection. Secondly, the 

owning Java application can be push registered in MIDP2 using the imscore: connector string, for example, 

started based on an incoming IMS call. Basically, a connector string is placed in the MIDlet-push attributes, or used 

in a call to PushRegistry.registerConnection(). The connector string is the same as used in connector.open. 

Push registration of JSR 281 MIDlets are described in Appendix B. 

In the IMS application model, push registration means that the IMS application is started when the Java 

environment is started, while the owning Java application start is delayed until there is an incoming request that 

needs to be handled. 

Security 

IMS Security 

The JSR 281 is transparent and shall be kept independent to the security mechanisms used for IMS of the device. 

This concerns both security for media streams, signalling, and authentication of the user. 

Java Security 

The IMSAPI is an API that can cause considerable network activity on the device. All implementations of IMSAPI 

MUST ensure that only applications that have appropriate permissions can perform protected IMSAPI calls. The 

mechanisms for granting permissions are implementation dependent. However, if the IMSAPI is implemented on a 

platform that supports MIDP, then the security framework of MIDP MUST be used as defined below. If no MIDP 

profile is used then defined permissions MUST be implemented using the mechanisms of the platform. The 

definitions of MIDP security policy terms may be found in the appropriate MIDP Specification. 

To access a protected function, the MIDlet MUST have the appropriate permission, or a SecurityException is 

thrown. Below, follows a list of permission names, the included protected method calls, and the mapping to a 

function group. 

Permission Name (MIDP 2) Permitted Java API Call Function Group 

javax.microedition.io.Connector.imscore Connector.open("imscore://..") Net Access 


javax.microedition.ims.Media.read FramedMedia.sendFile Read User Data Access 

javax.microedition.ims.Media.write FramedMedia.receiveFile Write User Data Access 

Permission classes for MIDP 3 mappings 

The table below shows how the permission names from MIDP 2 corresponds with MIDP 3 permission classes. 

Permission Name (MIDP 2) Permission Class (MIDP 3) 

javax.microedition.io.Connector.imscore javax.microedition.ims.core.ImscoreProtoco 

lPermission("imscore://*") 

javax.microedition.ims.Media.read 

javax.microedition.ims.Media.write 

Identification of the IMSAPI 

javax.microedition.ims.Media.MediaPermissi 

on("", "read") 

javax.microedition.ims.Media.MediaPermissi 

on("", "write") 

To identify the IMSAPI, implementations of this specification MUST include a system property according to the 

table below: 

System Property Key value 

javax.microedition.ims.version 1.1 

If the device implementation supports the requested package, the value that represents the IMSAPI version MUST 

be returned. 

If the implementation does not support the requested package then the key is not defined and null MUST be 

returned. 

Media profiles in JSR 281 

A Media profile in JSR 281 specifies a set of codecs and associated signalling for use in an IMS application. A 

profile builds on a standard, and generally if the device has native support for the standard then that suffices to 

make the media profile available to the IMSAPI. Some functionality of the standard that is not required in the 

IMSAPI may be excluded from a profile, even though the device natively supports that. 

A JSR 281 implementation can support several profiles, depending on the media capabilities of the device. Within 

the realm of some composed capability (ICSI, IARI or Feature Tags), the IMS application can require support for a 

certain media profile. 

This specification defines two media profiles, the basic profile and the MMTel profile. Media profiles are identified in 

the IMSAPI using string identifiers, called short name. 

Basic Profile 

The basic media profile MUST be supported in all JSR 281 implementations that supports streaming media, for 

audio and video, respectively. It provides the smallest set of media codecs shared between JSR 281 

implementations. 

3GPP Default codecs for IMS [26.235] MUST be supported in the device. Below follows a summary of contents of 

the profile based on this specification: 

Audio 

For streaming audio, the following MUST be included in the profile: 

• The narrow-band AMR codec for speech. 


• The AMR wideband codec, if the device supports wideband speech at 16 kHz sampling frequency. 

All other audio codecs and their modes of operation that the device natively supports for IMS SHOULD be 

supported in the Basic profile. This means that the IMS Engine can use them in media negotiation. 

Video 

A device that has a camera and supports streaming video, the following MUST be included in the profile: 

• H.263 profile 0 level 45 

The following SHOULD be supported: 


• MPEG-4 Visual Simple Profile Level 0b. 

• H.264 (AVC) Baseline Profile Level 1b. 

For further details of codec properties and operation, see [26.235]. 

All other video codecs and their modes of operation that the device natively supports for IMS SHOULD be 

supported in the Basic profile. 

Short name 

The short name for the Basic profile is "basic". 

MMTel profile 

A device that complies to [26.114] suffice to enable the MMTel profile. Hence, such a device MUST support this 

profile, else it MUST NOT be supported. 

The purpose of the MMTel profile is to support devices that are capable of supporting conversational-grade speech 

and video comparable to that of traditional circuit-switched services. The profile includes advanced optimization 

and adaptive mechanisms to handle varying network conditions to maintain quality of service. 

For streaming audio, the following MUST be included in the profile, according to [26.114]: 

Audio 

• The narrow-band AMR codec for speech with all modes of operation [26.114]. 

• The AMR wideband codec with all modes of operation [26.114], if the device supports wideband speech at 

16 kHz sampling frequency. 

Encoding of DTMF MUST NOT be supported within the profile. 

All other requirements from [26.114] placed on audio apply. 

Video 

The following video codecs MUST be supported: 


The following SHOULD be supported: 

• MPEG-4 Visual Simple Profile Level 3 

• H.264 (AVC) Baseline Profile Level 1b. 

All other requirements from [26.114] placed on video apply. 

Real-time Text 


If the terminal supports Real-time text, then that MUST NOT be available in the profile. 

Other considerations 

The IMSAPI includes no requirements for interworking with the circuit-switched domain. It is only applicable within 

the packet switched domain. 

Short name 

The short name for the MMTel profile is "mmtel". 

File formats 

The device MUST support the 3GP file format for supported audio and video, as of the 3GP specification [26.244]. 

NAT and Firewall considerations 

A device may be faced with a NAT or firewall placed in the access network towards IMS. While the IMS engine will 

manage the situation for signalling and the media stream in general, there are spome remaining cases for some 

media types where the application MUST be programmed in a certain way for it to work properly. This is 

documented for the media type in the interface documentation. 

If the JSR 281 enabled device has support to work towards a NAT or firewall, then the NAT guidelines found in 

Appendix A MUST be followed. 

Support for alternative connection models for MSRP 

The implementation MUST support the alternative connection model for MSRP as described in 

[draft-ietf-simple-msrp-acm-00]. The implementation MAY support the standard connection model as described in 

[RFC4975]. 

Quality-of-Service management in IMSAPI 

Quality of Service (QoS) is an important requirement in IMS. In the 3GPP service specification [22.228], QoS is 

addressed in four of the eleven requirements. QoS is a broad concept with many interpretations depending on the 

approach. In JSR 281, QoS is rooted in the end user experience. If the user is satisfied about the performance of 

an IMS application, then the QoS is sufficient. If not, the system delivers insufficient QoS. This assumes that the 

end user has an expectation of an appropriate level of quality. It depends on the application, even for the same 

types of media. For example, an IMS telephony application has a different notion of quality than a streaming media 

player application even though they are both based on audio media. 

If there is a QoS problem with an application, then this is because the system is unaware of the expected or 

accepted usage. If it had known, the problem could have been addressed from the start and actions could have 

been taken. In the best case, the user will be happy. In the worst case, the application may not run at all if the 

quality is below any acceptable level. 

QoS is about how the complete system (all parts of the IMS, end to end) meets the expectation of the end user. By 

providing sufficiently detailed information about what an application should be used for to the system, the system 

will return resources in the IMS system as necessary to keep the user happy. 

To address QoS, two parts must be considered: 

1. Problem domain: A description of the need for the quality wanted for the particular service or IMS 

application. 

2. Solutions domain: Means to reserve resources in the complete chain of network links, nodes between and 

including the end user terminals and the particular IMS applications. 

The problem domain is approached in the API in the division of Media into subtypes. Each has its own intended 

usage. 


StreamMedia 

StreamMedia is used to stream audio and video in real-time between end-points. It is handled in the JSR 

implementation by codecs supplied from the device for the data formats. That media is streamed in real-time will 

give indications of delay requirements. The media source also gives clues. If an audio-media is sourced from a 

mobile phone microphone, the codec should be selected accordingly. Some devices are equipped with built-in 

cameras (for video telephony and video camcorder), and the same applies here. If the media is sourced from a file, 

then the file format decides the codec. 

The codecs give the main information on the needed QoS. The application can give a preference for a certain level 

of quality via the setQuality method (Low, Medium and High) and this will affect which codecs the device chooses 

of those supported, for the format. 

BasicMedia 

For basic media, the quality needed depends completely on how the application processes the BasicMedia streams, 

and the quality need must be provided in full to the system. The media flow is characteristized in the Registry at 

installation time. 

BasicMedia flows 

The Java application implements the codecs for the data formats that will cause network activity. The codecs are 

unknown to the system, as they are application specific. Using them creates network activity, and the application 

has the option to specify the quality need explicitly, or use a default best effort approach. If there is a quality need, 

then flow specifications (flowspecs) [RFC2215] are used as input for the system to reserve system resources. The 

Registry lists them by serviceId, MIME content type, and associated flow specs in the send and receive directions. 

Flow specification 

A flow spec includes the following quantities: 

• Average rate - Specifies the permitted rate in bytes per second at which data can be transmitted over the 

life of the media. NOTE: This includes only the data that the application owns, not the overhead created by 

the system. 

• Buffer size - Expected buffer size needed in bytes to accommodate for momentary deviations from the 

average rate. 

• Peak rate - The maximum data rate in bytes per second at any given time. 

• Delay - Maximum acceptable transmission delay of data in milliseconds. 

• DelayVariance - Difference between the maximum and minimum possible transmission delay in 

milliseconds. 

• Maximum chunk size - The maximum size in bytes of transmitted application data chunks. 

• Minimal policed unit - This is the minimum size in bytes of transmitted application data chunks. 

A flowspec represents a contract between the application and the system. If the application processes data 

according to specification, then the system grants transmission within the delay limits. If the application fails, then 

there is no guarantee. 

Flowspecs are set at development time in the Registry Qos property. 

If there is no flow specification, best effort is used. This may be sufficient for applications with modest non-critical 

network demands. 

FramedMedia 

FramedMedia is used for session-based instant messaging, and file transfer. Short textual messages are expected 

to be delivered rather fast, while transfer of large files can take time and has lower precedence to other types of 

streams. This is in itself sufficient information for the system to set QoS. 

Mandatory and optional Parts of the IMSAPI 


Generally, the policy is that all JSR 281 Core API interfaces MUST be implemented according to the specification. 

Details and allowed deviations are described below. 

Core service support 

The device MUST be able to maintain one core service object. 

Service method support 

A JSR 281 enabled device MUST implement all service methods and MUST be able to: 

• Handle at least one Session object through its lifecycle, either sent to a remote or received from it. 

• Handle at least one Capabilities object. The device MUST be able to respond to an incoming OPTIONS. 

• Handle at least one Reference object, sent or received. 

• Handle at least one PageMessage object to send, and handle at least one PageMessage object received. 

• Maintain at least one Subscription object, and be able to receive notifications. 

• Maintain at least one Publication object. 

Session support 

A session MUST be able to: 

• Include least two media objects with flows in an established session 

• Include least one instance of a supported media type in an established session. 

• Handle one Reference inside a session. 

• Handle one Capabilities in a session. 

Streaming Media support 

The StreamMedia interface is conditionally mandatory, meaning that if the device supports streaming then 

StreamMedia MUST be implemented. 

If the device supports streaming audio 

• The streaming audio part of the StreamMedia interface MUST be implemented. 

• Sourcing audio from "capture://audio" MUST be implemented. 

If the device supports streaming video 

• The streaming audio and video parts of the StreamMedia interface MUST be implemented. 

• Sourcing audio from "capture://audio" MUST be implemented. 

• Sourcing video from "capture://video" MUST be implemented. 

The Basic media profile MUST be supported. See further details in the Media profiles section. 

Player Controls 

The following table outlines the JSR 135 Mobile Media API controls that MUST be implemented for the streaming 

media players. 

Controls Implementation Requirements 

VolumeControl Mandatory if streaming audio or video is supported 

VideoControl Mandatory if streaming video is supported 

Requirements on the StreamMedia Player 

Player creation 


The IMSAPI uses the concept of Players, defined in [JSR118] and [JSR135], to capture and render streaming 

media. The Player is created by the IMSAPI implementation and is retrieved by the application by invoking a 

method in the IMSAPI. When the Player is retrieved it is in the Realized state and controls can immediately be 

obtained. 

Player limitations 

The following table outlines the limitations for the Player interface. 

Method 

Implementation Requirements 

Player.setLoopCount Setting the loop count will succeed, but it will have no meaning for the implementation 

Player.setMediaTime Setting media time is not supported 

The following control interfaces are limited: 

Interface Implementation Requirements 

Controlling the playback rate is not supported. 

RateControl 

The control can be added but has no impact 


Package javax.microedition.ims 


This package collects classes and interfaces to install and configure IMS applications. 

See: 

Description 

Interface Summary 

ConnectionStateListener A listener type for receiving notifications about changes to the IMS connection. 38 

ReasonInfo 

Service 

The ReasonInfo interface enables an application to get details on why a 

method call failed. 

Service is the base interface for IMS Services, and follows the Generic 

Connection Framework (GCF). 

Page 

41 

43 

Class Summary 

Configuration 

ConnectionState 

The Configuration class realizes dynamic installation of IMS applications with the pair 

of methods setRegistry and removeRegistry. 

The ConnectionState class is used to monitoring the IMS connection and accessing 

user identities. 

Page 

32 

36 

Exception Summary 

ImsException An ImsException indicates an unexpected error condition in a method. 40 

ServiceClosedException 

A ServiceClosedException indicates that a method is invoked on a Service 

that is closed. 

Package javax.microedition.ims Description 

This package collects classes and interfaces to install and configure IMS applications. There is also functionality to 

monitor the IMS registration status. Below follows information about how to use the IMSAPI and a description of the 

application model. 

Using the IMSAPI 

A JSR 281 IMS application goes through three generic steps: 

1. Access the IMS functionality of the device. 

2. Go online to the IMS network using a selected identity. 

3. Connect a call including media flows with a remote IMS device. 

Access the IMS functionality 

To access the IMS functionality of the device, the IMS application needs to be installed. This can be done in two 

different ways, static and dynamic installation. Static installation is done by adding properties in the jad file. 

Dynamic installation is performed in runtime by invoking Configuration.setRegistry. Both installation methods 

are mentioned below. 

Go online 

The application creates a Service when it is prepared to handle calls. A Service is created by calling 

Connector.open. In order to receive incoming calls, it is recommended that the CoreServiceListener is set as 

soon as the Service is opened. 

Page 

45 



Connect a call 

The final step that needs to be done is to create a Session that will manage the call. The call can be configured by 

adding various media and is then initiated by calling Session.start. 

Example code 

This example code only show the IMS specific java code that needs to be done in order to initiate a call including a 

streaming media. 

myCoreService = (CoreService) Connector.open(“imscore://com.myCompany.CallApp”); 

myCoreService.setListener(this); 

mySession = myCoreService.createSession(null, sip:bob@home.net); 

mySession.setListener(this); 

myMedia = (StreamMedia) mySession.createMedia(“StreamMedia”, Media.DIRECTION_SEND_RECEIVE); 

myMedia.setSource(“capture://audio”); 

mySession.start(); 

The JSR 281 IMS Application Registry 

In this section, the logic and structure of the Registry is described in detail. In the following two sections, the 

notation used at static and dynamic install is specified. 

A Registry consists of the owning Java application class name, the IMS application identifier, and an unordered set 

of properties, which represent aspects of the IMS application. The properties include all capabilities, but there are 

also other types of information as well. This is also described below. 

Owning Java application class name 

The Java application that owns the IMS application, is indicated using fully package qualified string. 

IMS Application Identifier 

The IMS Application Identifier (AppId) is a non-empty string case-insensitive unique within the IMS application suite. 

It is recommended that the AppId is chosen such that the vendor and name of the IMS application is clearly 

specified, for example like a package-qualified Java class. The AppId has relevance in the context of the IMSAPI to 

identify the Registry for an IMS application within the IMS application suite. It is not used in the IMS signalling, and 

has no relevance for interoperability. 

Registry properties 

A property has a type name and zero, one, or more values. The number of values and their format depends 

completely on the type. A Registry contains unique properties, where the uniqueness depends on the property type. 

This specification defines a number of properties that have meaning to the JSR implementation. 

Since an IMS application must realize at least one IMS capability, it follows that a Registry must contain at least 

one of the IMS properties StreamMedia, FramedMedia, BasicMedia, Event, or CoreService. 

StreamMedia property 

Type name: Stream 

Motivation: Declares that the application has the basic capability to stream audio and/or video media types. 

Description: A Registry contains this property if the IMS application uses StreamMedia somewhere in its code. If it 

does not, then the Registry does not include the property. 

Value: A set that contains the types of StreamMedia used. One or both of Audio and Video. 

Uniqueness: There is at most one StreamMedia property in a Registry. 

FramedMedia property 

Type name: Framed 



Motivation: Declares a basic capability of messaging. 

Description: A Registry contains this property if the IMS application uses FramedMedia somewhere in its code. If it 

does not, then the Registry does not include the property. 

Value: The value has two parts. The first part consists of the set of all content types. The second part is optional 

and is the maximum size of any transfer. It is used on the terminating endpoint to generate an answer to the 

originating endpoint sent before session accept. 

Uniqueness: There is at most one FramedMedia property in a Registry. 

BasicMedia property 

Type name: Basic 

Motivation: Declares a basic capability to transfer media content of some MIME content type. 

Description: A Registry contains this property if the IMS application uses BasicUnreliableMedia and/or 

BasicReliableMedia somewhere in its code. If not, then the Registry does not include the property. 

Value: The value is a set of all MIME content types used in the media. This is used on the MT side 

Uniqueness: There can be maximum one BasicMedia property in a Registry. 

Event property 

Type name: Event 

Motivation: Declares a basic capability of handling event packages. 

Description: A Registry contains this property if the IMS application uses event packages somewhere in its code 

(part of Subscription and Publication interfaces). If not, then the Registry does not include the property. 

Value: The value is a set of all event package names. 

Uniqueness: There can be maximum one event property in a Registry. 

CoreService property 

Type name: CoreService 

Motivation: Declare composed capabilities of core services. 

Description: A Registry contains a property for each core service object it creates. It shows which composed 

capability of the IMS application shall be mapped into each service. For any useful IMS application the Registry has 

at least one CoreService property. 

Value: The value has four parts: a serviceId, zero or one IARI, ICSIs, and Feature Tags on standardized formats. 

ICSI and Feature Tags can also have the explicit and require flags. A white space is used as separator if more then 

one ICSI or Feature Tag. The serviceId is an alphanumeric name of any length. An empty name is allowed, and is 

useful for applications with one service. 

Uniqueness: All Core Service properties MUST have a unique serviceId within the scope of the IMS application. 

QosProfile property 

Type name: Qos 

Motivation: Support QoS aware BasicMedia. 

Description: BasicMedia specifies data flows in the send and receive directions to get QoS. The flow specifications 

are tied to a MIME content type for a CoreService property. 

Value: The value consists of four parts: a serviceId, a MIME content type, a sending flow specification (flowspec), 

and a receiving flowspec. serviceId is a serviceId specified in a CoreService property for this IMS application. A 

flowspec consists of the quantities described in the chapter on Quality of Service. If the receive flowspec is empty, 

the send flowspec is also used in the receive direction. 

Uniqueness: A QosProfile property must have a unique combination of MIME content type and serviceId. 

Advanced properties 

These properties are meant for the advanced user and they require specific IMS knowledge and should be used 

with caution. Setting these properties will not only configure the application, but they might have an impact on the 

IMS engine and other applications as well. 

Registration header property 

Type name: Reg 

Motivation: Added headers to SIP registration message. 

Description: The property contains the SIP headers with names and values using standard syntax. 

Value: The value is a list of parts. The first part is a serviceId, and all remaining parts are the headers. 

Uniqueness: There can be maximum one Registration header property per serviceId. 

Write header property 

Type name: Write 



Motivation: Allow the JSR implementation write access in SIP message headers. 

Description: The property contains all names of headers where the IMS application writes values. 

Value: A set of header names. 

Uniqueness: There can be maximum one write header property in a Registry. 

Read header property 

Type name: Read 

Motivation: Allow the JSR implementation read access in SIP message headers. 

Description: The property contains all names of headers where the IMS application reads values. 

Value: A set of header names. 

Uniqueness: There can be maximum one read header property in a Registry. 

Configure capability property 

Type name: Cap 

Motivation: Configures a Capabilities request or response. 

Description: The IMS engine creates a default Session Description Protocol (SDP) for outgoing capability requests 

and responses and this method is used to extend the SDP with application specific properties. 

Value: The value consists of three parts: a sector identifier (sectorId), messageType and the SDP field(s). The 

sectorId indicates where to put the SDP field, as session-level or media-level. The messageType is used to indicate 

if the SDP field should be added to an outgoing capability request, response or both. The last part is the SDP 

field(s) to be added. It is not guaranteed that the properties are added to the actual SDP, for example if there is a 

conflict between application configurations the SDP field(s) might be modified or removed. 

Uniqueness: There can be zero or more capability properties in a Registry. 

Media profile property 

Type name: Mprof 

Motivation: Make IMS application media handling use a media profile. 

Description: The property expresses a dependency from the IMS application to a media profile. As the profile is 

expected to be used in the realm of composed capabilities, the profile is associated to a core service. When the 

application creates a session based on that core service, the media handling follows the media profile definition. An 

IMS application can support several profiles. If no media profile has been specified for the core service, then the 

basic profile is assumed by default. 

Value: The value consists of two parts: a serviceID, and the media profile short name as a string: "basic", "vs", 

"mmtel" or any other short name for a profile defined outside this specification. 

Uniqueness: There can be at most one media profile per ServiceId. 

Connection property 

Type name: Connection 

Motivation: Select the connection model for MSRP protocol used in FramedMedia. 

Description: If the property is present, the MSRP connection model is that of the standard MSRP procedure as 

defined in [RFC4975]. If it is not present, the model follows that of [draft-ietf-simple-msrp-acm-00]. The property 

applies per core service to enable the application to bind it to the capabilities. 

Value: The value is a serviceId. 

Uniqueness: There can be at most one connection property per serviceId. 

Other constraints for Registry 

A Registry MUST have some capability-carrying property defined. 

If a Registry does not comply to the rules above, it is declared inconsistent or corrupt. It is not possible to create a 

core service on a corrupt registry. 

Dynamic Installation 

Dynamic installation uses the method Configuration.setRegistry, that binds an IMS application to a Java 

application, with the Registry contents. In this call, the Registry is represented as an array of properties. A property 

is an array of strings, where the first element is the type. The value, beginning at second element position, is none, 

one, or more string elements following the general pattern: 

• A simple value is represented as a string. 



• A set value is represented as a space-delimited string enumerating the members. No duplicates are 

allowed. 

• A multi-valued property is represented as strings over several element positions in a defined order in the 

string array. If a value can be empty, then the empty string is used as a place holder. Each value may 

define their own internal string syntax. 

The property type names and their possible values, as used in a dynamic installation, are shown below: 

Stream 

Value: One or both of Audio and Video. 

Example: { "Stream", "Audio Video" } 

Framed 

Value: Set of MIME content types. 

Example: { "Framed", "text/plain image/png", "4096" } 

Basic 

Value: Set of MIME content types. 

Example: { "Basic", "application/myChess" } 

Event 

Value: Set of event package names. 

Example: { "Event", "presence" } 

CoreService 

Value: The CoreService property is multi-valued, where the contents of Service definitions are elements in 

the order: serviceId, IARI, ICSIs, and Feature Tags. Individual ICSIs and Feature Tags can be appended 

with ;require and/or ;explicit to flag them for require and explicit processing. A white space is used as 

separator if more then one ICSI or Feature Tag. 

Example of a core service with IARI but no ICSI and Feature Tags: 

{ "CoreService", "myChess", "urn:IMSAPI:com.myCompany.chess", "", "" } 

Example of a core service with an ICSI flagged for both require and explicit processing: 

{ "CoreService", "myChess", "", "urn:URN-3gpp:org.3gpp.icsi;require;explicit", "" } 

Example of a core service with two ICSIs and three feature tags: 

{ "CoreService", "myChess", "", "urn:3gpp:org.3gpp.icsi urn:3gpp:3gpp-service.ims.icsi.mmtel", "Audio 

Video;explicit Duplex;require" } 

Qos 

Value: The Qos profile is multi-valued with complex parts. The property values are given in the following 

order: serviceId, MIME ContentType, send flowspec, receive flowspec. Flowspec strings consist of 

space-separated integers in the form: " 

". 

Example: { "Qos", "myChess", "application/myChess", "1024 5000 1500 0 0 100 10", "" } 

Reg 

Value: The Reg property is multi-valued, where the first value is the serviceId, and the remaining values 

are the SIP headers. 

Example: { "Reg", "myChess", "Require: pref" } 

Write 

Value: Set of SIP header names for write access. 

Example: { "Write", "P-ImageIncluded" } 

Read 

Value: Set of SIP header names for read access. 

Example: { "Read", "P-ImageIncluded" } 

Cap 

Value: The Cap property is multi-valued, where the first value is the sectorId that can be "Session", 

"Framed", "StreamAudio" or "StreamVideo". The second value is a messageType that can be "Req", 

"Resp" or "Req_Resp". The remaining values are one or more SDP fields. 

Example: { "Cap", "Session", "Req_Resp", "a=X-type:videolive" } 

Mprof 

Value: The Mprof property has two values, where the first value is a ServiceId for some CoreService 

property in this Registry, and the second value is a media profile short name. 

Example: { "Mprof", "myChess", "vs" } 

Connection 

Value: The Connection property has a serviceID value for some CoreService property in this Registry. 

Example: { "Connection", "myChess" } 

Whitespace is deleted from the beginning and end of each value string. Any embedded string of whitespace is 

interpreted as a separator. 



An example of the Configuration.setRegistry call expected for the myChess application: 

String[][] registry = new String[][] { 

{ "Basic", "application/myChess" }, 

{ "Framed", "text/plain image/png", "4096" }, 

{ "Event", "Presence" }, 

{ "CoreService", "myChess", "urn:IMSAPI:com.myCompany.iari.myChess", "", "" }, 

{ "Qos", "myChess", "application/myChess", "2 3 2 10 5 2 3", "" }, 

{ "Reg", "myChess", "Require: pref" }, 

{ "Write", "P-ImageIncluded" }, 

{ "Read", "P-ImageIncluded" }, 

{ "Cap", "Framed", "Req_Resp", "a=max-size:4096" }, 

{ "Mprof", "myChess", "vs" }, 

{ "Connection", "myChess" } 

}; 

Configuration.setRegistry("org.jsr281.myChess", "MyChess", registry); 

Static Installation 

IMS applications can be installed at the time of Java application installation. The properties are represented as 

attributes in the manifest file. If the MIDP jad file is used, it must be in accordance with the MIDP 2.0 specification. 

The manifest representation is designed to be close to the form of the registry argument to 

Configuration.setRegistry. One property corresponds to one attribute line (see further below). The value 

consists of a number of comma-separated fields following the pattern: 

• A simple value is represented in its own syntax in one field. 

• A set value is represented as a space-delimited member enumeration in one field. The field MUST NOT 

contain duplicates. 

• The component values of a multi-valued property are represented in their own fields. If a value is empty, 

the field is empty. The values may define their own syntax as long as no ambiguity is introduced on the 

manifest attribute line. 

A manifest attribute name is created based on the property type name. It must be unique within the file. The 

following factors are considered: 

• The scope of the manifest file is the complete Java application suite. To avoid possible name collisions with 

attributes of other packages, all attributes names for the IMSAPI begin with MicroEdition-IMS-. 

• A Java application suite can contain several IMS applications. To properly associate IMS properties to the 

right application, a suite-unique serial number is part of the attribute name. All attributes with the same 

number in their name belong to the same IMS application. If the suite has n IMS applications, the serial 

number ranges from 1 up to n in that order. 

• An IMS application can contain one or more CoreService properties. A serial number is used, and it must 

be unique within the IMS application. If an IMS application has m CoreServices, the serial number ranges 

from 1 up to m in that order. 

• An IMS application can contain zero or more QosProfile properties. A serial number is used here, as for 

CoreService properties. Note that a QosProfile is bound to a CoreService, but the QosProfile attribute 

name does not include the CoreService serial number. As for the dynamic case, the serviceId identifies the 

CoreService. 

More specifically, the attribute names are in accordance with the following list. See Dynamic Installation for values 

that can be set. 

MicroEdition-IMS--Identity 

This is the extra non-property related line used to identify an IMS application. It assigns a serial number i. 

The jad attribute value is the AppId, and the MIDlet class name, as specified in the MIDlet- attribute of 

MIDP: 

MicroEdition-IMS--Identity: , 

MicroEdition-IMS--Stream 

Encodes the Stream property for IMS application i. 

MicroEdition-IMS--Stream: 

MicroEdition-IMS--Framed 



Encodes the Framed property for IMS application i. 

MicroEdition-IMS--Framed: , 

MicroEdition-IMS--Basic 

Encodes the Basic property for IMS application i. 

MicroEdition-IMS--Basic: 

MicroEdition-IMS--Event 

Encodes the Event property for IMS application i. 

MicroEdition-IMS--Event: 

MicroEdition-IMS--CoreService- 

Encodes the j-th CoreService property for IMS application i. 

MicroEdition-IMS--CoreService-: , , ... , ... 

The and may have the flags ;require and/or ;explicit appended. A white 

space is used as separator if more then one ICSI or Feature Tag. 

MicroEdition-IMS--Qos- 

Encodes the j-th QosProfile property for IMS application i. 

MicroEdition-IMS--Qos-: , , , 

 

MicroEdition-IMS--Reg- 

Encodes the j-th Registration header property for IMS application i. 

MicroEdition-IMS--Reg-: , , ..., 

MicroEdition-IMS--Write 

Encodes the Write property for IMS application i. 

MicroEdition-IMS--Write: 

MicroEdition-IMS--Read 

Encodes the Read property for IMS application i. 

MicroEdition-IMS--Read: 

MicroEdition-IMS--Cap- 

Encodes the j-th Configure capabilities property for IMS application i. 

MicroEdition-IMS--Cap-: , , , ..., 

MicroEdition-IMS--Mprof- 

Encodes the j-th Mprof property for IMS application i. 

MicroEdition-IMS--Mprof-: , 

MicroEdition-IMS--Connection- 

Encodes the j-th Connection property for IMS application i. 

MicroEdition-IMS--Connection-: 

Leading and trailing whitespace is deleted from each attribute and field. Any embedded string of whitespace in a 

field is treated as a separator. 

An example of the manifest attributes expected for the myChess application: 

MicroEdition-IMS-1-Identity: org.jsr281.myChess, MyChess 

MicroEdition-IMS-1-Basic: application/myChess 

MicroEdition-IMS-1-Framed: text/plain image/png, 4096 

MicroEdition-IMS-1-Event: Presence 

MicroEdition-IMS-1-CoreService-1: myChess, urn:IMSAPI:com.myCompany.iari.myChess, , 

MicroEdition-IMS-1-Qos-1: myChess, application/myChess, 2 3 2 10 5 2 3, 

MicroEdition-IMS-1-Reg-1: myChess, Require: pref 

MicroEdition-IMS-1-Write: P-ImageIncluded 

MicroEdition-IMS-1-Read: P-ImageIncluded 

MicroEdition-IMS-1-Cap-1: Framed, Req_Resp, a=max-size:4096 

MicroEdition-IMS-1-Mprof-1: myChess, vs 

MicroEdition-IMS-1-Connection-1: myChess 

Executing IMS applications 

An IMS application is said to be started, or executing, whenever it is visible on the IMS network. This happens 

when its capabilities. A JSR 281 IMS application is executing whenever at least one of its Core Services are 

created and active. 

The imscore connector string 



The imscore connector string is supplied as argument to Connector.open to create the core service. A properly 

formatted imscore connector string uniquely identifies a core service of the system. It follows the pattern: 

imscore:;userId=;serviceId= 

The detailed syntax is specified according to the production below: 

Left hand side 

right hand side 

::= "imscore://"[] 

::= 

::= string of alphanumeric characters 

 

 

 

 

 

::= *(| ) 

::= ";serviceId=" | ";serviceId=" 

::= string of alphanumeric characters 

::= ";userId=" | ";userId=" 

::= SIP or TEL URI with optional display name 

While the Core Service object is open, or Push registered, the capabilities are exposed on the network. The IMS 

application is now able to initiate and receive IMS calls with media. It is programmed to handle them according to 

its own logic conformant to the capabilities. See the API documentation. 

To stop execution, the IMS application closes each active service with calling Service.close. 


Class Configuration 


javax.microedition.ims 

java.lang.Object 

javax.microedition.ims.Configuration 

final public class Configuration 

extends Object 

The Configuration class realizes dynamic installation of IMS applications with the pair of methods setRegistry 

and removeRegistry. While an IMS application is installed, it has an associated Registry. The Registry is a small 

data base that stores IMS application properties. See the package documentation and the chapter on the Registry 

and its role in static and dynamic installation. 

Dynamic installation complements the static installation where the installation of IMS application takes place at 

Java application installation. 

Method Summary 

static getConfiguration() 

Configuration 

Returns a Configuration that enables dynamic installation of IMS applications. 

String[] getLocalAppIds() 

Returns all AppIds for the local endpoint. 

String[][] getRegistry(String appId) 

Returns the registry for an IMS application with the specified appId. 

boolean hasRegistry(String appId) 

Returns true if there is a registry for the IMS application with the specified appId, else 

false. 

void removeRegistry(String appId) 

Removes the registry for the IMS application and deletes the binding to the owning 

Java application. 

void setRegistry(String appId, String classname, String[][] registry) 

Sets the registry for an IMS application and binds it to a parent Java application. 

Page 

32 

34 

34 

34 

34 

32 

Method Detail 

getConfiguration 

public static synchronized Configuration getConfiguration() 

Returns a Configuration that enables dynamic installation of IMS applications. 

Returns: 

a Configuration instance that enables dynamic installation of IMS applications. 

setRegistry 

public void setRegistry(String appId, 

String classname, 

String[][] registry) 



Sets the registry for an IMS application and binds it to a parent Java application. Any previous registry and 

binding for that IMS application is deleted (including all properties), this does not affect services that are 

already created. The new registry is defined in the registry argument. 

The classname argument identifies a Java application according to the particular Java runtime environment. 

For a MIDP2-based implementation, the classname must be registered with the Midlet- attribute. 

The registry argument specifies a registry as an unordered array of IMS properties. The general pattern 

of the registry argument is as follows. The property type name is in bold face, the value placeholder is in 

italic. 

{{ "Stream", "Media types" }, 

{ "Framed", "MIME Content types", "max-size" }, 

{ "Basic", "MIME Content types" }, 

{ "Event", "Event package names" }, 

{ "CoreService", "ServiceId", 

"Zero or one IARI", 

"Zero or more ICSIs", 

"Zero or more Feature Tags" }, 

{ "Qos", "ServiceId", 

"MIME Content type", 

"Flowspec send", 

"Flowspec receive" }, 

{ "Reg", "ServiceId", 

"Header 1", 

... , 

"Header n" }, 

{ "Write", "Write access SIP headers" }, 

{ "Read", "Read access SIP headers" }, 

{ "Cap", "sectorId", 

"messageType", 

"SDP field 1", 

... , 

"SDP field n" }, 

{ "Mprof", "ServiceId", "Media profile" }, 

{ "Connection", "ServiceId"} 

} 

String myAppId = "com.myCompany.games.chess"; 

Configuration myConfiguration = Configuration.getConfiguration(); 

String[][] registry = 

new String[][] { 

{"Framed", "text/plain image/png", "4096"}, 

{"Basic", "application/myChess"}, 

{"Event", "presence"}, 

{ 

"CoreService", 

"myChess", 

"urn:IMSAPI:com.myCompany.iari.myChess", 

"urn:3gpp:org.3gpp.icsi;require urn:3gpp:3gpp-service.ims.icsi.mmtel", 

""}, 

{"Qos", "myChess", "application/myChess", "2 3 2 10 5 2 3", ""}, 

{"Reg", "myChess", "Require: pref"}, {"Write", "P-ImageIncluded"}, 

{"Read", "P-ImageIncluded"}, 

{"Cap", "Framed", "Req_Resp", "a=max-size:4096"}, 

{"Mprof", "myChess", "vs"},}; 

myConfiguration.setRegistry(myAppId, classname, registry); 

Parameters: 

appId - the application id 

classname - the classname of the Java application that the IMS application is bound to 

registry - an array of arrays, specifying key and value(s) 

Throws: 

IllegalArgumentException - if the appId or classname argument is null, 

if the registry argument is null or if it has invalid syntax, 

if the classname argument is not specified as a MIDlet- attribute (for MIDP implementations) 



See Also: 

getRegistry(String) 

getRegistry 

public String[][] getRegistry(String appId) 

Returns the registry for an IMS application with the specified appId. 

Parameters: 


Returns: 

the registry for the IMS application specified by the appId argument 

Throws: 

IllegalArgumentException - if appId is not set in the registry 

See Also: 

setRegistry(String, String, String[][]) 

removeRegistry 

public synchronized void removeRegistry(String appId) 

Removes the registry for the IMS application and deletes the binding to the owning Java application. This 

applies to both static and dynamic installations. If this method is invoked, the local endpoint will no longer 

be able to create new services with the application identity specified by the appId argument, this does not 

affect services that are already created. 

Parameters: 


Throws: 

IllegalArgumentException - if appId is not set in the registry 

hasRegistry 

public boolean hasRegistry(String appId) 

Returns true if there is a registry for the IMS application with the specified appId, else false. 

Parameters: 


Returns: 

true if there is a registry for the IMS application specified by the appId argument, else false 

Throws: 

IllegalArgumentException - if the appId argument is null 

See Also: 

setRegistry(String, String, String[][]) 

getLocalAppIds 

public String[] getLocalAppIds() 

Returns all AppIds for the local endpoint. An empty string array will be returned if no AppId could be 

retrieved. 



Returns: 

a string array containing all AppIds for the local endpoint 


Class ConnectionState 




javax.microedition.ims.ConnectionState 

final public class ConnectionState 

extends Object 

The ConnectionState class is used to monitoring the IMS connection and accessing user identities. 

The IMS engine runs autonomously on the device and therefore the application cannot assume that the device is 

connected or disconnected to the IMS network. If the IMS engine is not connected when the application creates a 

service with Connector.open the IMS engine will connect to the IMS network. 

While being connected to the IMS network, an application can retrieve the available network-provisioned user 

identities. 


static getConnectionState() 


Returns a ConnectionState that monitors the connection to the IMS network. 

String[] getUserIdentities() 

Returns network provisioned user identities. 

boolean isBehindNat() 

Determine whether there is a NAT/Firewall placed on the access network connecting 

the local endpoint to the IMS network. 

boolean isConnected() 

This method can be used to determine if the device is connected to the IMS network. 

boolean isSuspended() 

Returns whether the connection is in a suspended state. 

void setListener(ConnectionStateListener listener) 

Sets a listener for this ConnectionState, replacing any previous 

ConnectionStateListener. 

Page 

36 

37 

37 

36 

37 

37 

Method Detail 

getConnectionState 

public static ConnectionState getConnectionState() 

Returns a ConnectionState that monitors the connection to the IMS network. 

Returns: 

a ConnectionState instance that monitors the connection to the IMS network 

isConnected 

public boolean isConnected() 

This method can be used to determine if the device is connected to the IMS network. 



Returns: 

true if the device is connected to the IMS network, false otherwise 

isBehindNat 

public boolean isBehindNat() 

Determine whether there is a NAT/Firewall placed on the access network connecting the local endpoint to 

the IMS network. If this is the case then the application MUST consider how it is maintaining media flows in 

BasicReliableMedia and BasicUnreliableMedia. 

Returns: 

true if the device is behind a NAT/FW, false otherwise 

Throws: 

IllegalStateException - if the device is not connected to the IMS network 

setListener 

public void setListener(ConnectionStateListener listener) 

Sets a listener for this ConnectionState, replacing any previous ConnectionStateListener. A null 

reference is allowed and has the effect of removing any existing listener. 

Parameters: 

listener - the listener to set, or null to remove it 

getUserIdentities 

public String[] getUserIdentities() 

Returns network provisioned user identities. The first item is the network-chosen default user identity. The 

user identities can be used as an argument to creating services. 

The user identities are formatted according to SIP or TEL URI, see [RFC3261] and [RFC3966]. 

Returns: 

the network provisioned user identities, an empty string array will be returned if no user identities 

are available 

isSuspended 

public boolean isSuspended() 

Returns whether the connection is in a suspended state. 

Returns: 

true if the IMS connection is suspended, false otherwise 

Throws: 

IllegalStateException - if the device is not connected to the IMS network 


Interface ConnectionStateListener 



public interface ConnectionStateListener 

A listener type for receiving notifications about changes to the IMS connection. 

See Also: 

ConnectionState.isConnected() 


void connectionResumed() 

Notifies the application when its suspended IMS connection is resumed, meaning the 

connection now allows throughput. 

void connectionSuspended() 

Notifies the application when its current IMS connection is suspended, meaning there is no 

data throughput. 

void imsConnected() 

Notifies the application when the device is connected to the IMS network. 

void imsDisconnected() 

Notifies the application when the device is disconnected from the IMS network. 

Page 

38 

38 

38 

38 

Method Detail 

imsConnected 

void imsConnected() 

Notifies the application when the device is connected to the IMS network. 

imsDisconnected 

void imsDisconnected() 

Notifies the application when the device is disconnected from the IMS network. 

connectionSuspended 

void connectionSuspended() 

Notifies the application when its current IMS connection is suspended, meaning there is no data 

throughput. 

connectionResumed 

void connectionResumed() 



Notifies the application when its suspended IMS connection is resumed, meaning the connection now 

allows throughput. 


Class ImsException 

Class ImsException 



java.lang.Throwable 

java.lang.Exception 

javax.microedition.ims.ImsException 

public class ImsException 

extends Exception 

An ImsException indicates an unexpected error condition in a method. 

Constructor Summary 

ImsException() 

Constructs an ImsException with null as its error detail message. 

ImsException(String reason) 

Constructs an ImsException with the specified detail message. 

Page 

40 

40 

Constructor Detail 

ImsException 

public ImsException() 

Constructs an ImsException with null as its error detail message. 

ImsException 

public ImsException(String reason) 

Constructs an ImsException with the specified detail message. The error message string reason can later 

be retrieved by the Throwable.getMessage() method of class java.lang.Throwable. 

Parameters: 

reason - the detail message 


Interface ReasonInfo 



public interface ReasonInfo 

The ReasonInfo interface enables an application to get details on why a method call failed. 

Field Summary 

int REASONTYPE_INCONSISTENT_REGISTRY 

Identifier for the reason type inconsistent registry. 

int REASONTYPE_LOCAL_TIMEOUT 

Identifier for the reason type local timeout. 

int REASONTYPE_RESPONSE 

Identifier for the reason type response. 

int REASONTYPE_USER_ACTION 

Identifier for the reason type user action. 

Page 

42 

41 

41 

41 


String getReasonPhrase() 

Returns the SIP reason phrase. 

int getReasonType() 

Returns the reason type. 

int getStatusCode() 

Returns the SIP status code. 

Page 

42 

42 

42 

Field Detail 

REASONTYPE_RESPONSE 

public static final int REASONTYPE_RESPONSE 

Identifier for the reason type response. 

REASONTYPE_USER_ACTION 

public static final int REASONTYPE_USER_ACTION 

Identifier for the reason type user action. 

REASONTYPE_LOCAL_TIMEOUT 

public static final int REASONTYPE_LOCAL_TIMEOUT 

Identifier for the reason type local timeout. 



REASONTYPE_INCONSISTENT_REGISTRY 

public static final int REASONTYPE_INCONSISTENT_REGISTRY 

Identifier for the reason type inconsistent registry. 

Method Detail 

getReasonType 

int getReasonType() 

Returns the reason type. 

Returns: 

the reason type 

getReasonPhrase 


throws IllegalStateException 

Returns the SIP reason phrase. 

Returns: 

the reason phrase 

Throws: 

IllegalStateException - if reason type is not REASONTYPE_RESPONSE 

getStatusCode 



Returns the SIP status code. 

Returns: 

the status code 

Throws: 

IllegalStateException - if reason type is not REASONTYPE_RESPONSE 


Interface Service 



All Superinterfaces: 

javax.microedition.io.Connection 

All Known Subinterfaces: 

CoreService 

public interface Service 

extends javax.microedition.io.Connection 

Service is the base interface for IMS Services, and follows the Generic Connection Framework (GCF). 

Creating services using the Generic Connection Framework 

The application creates services using the Connector.open() where the string argument has the general form 

(described in [RFC2396]): 

where: 

• :[] 

• scheme is a supported IMS scheme. In this specification the imscore is defined in the CoreService 

interface 

• target is an AppId. An AppId should follow the form of fully qualified Java class names or any naming 

syntax that provides a natural way to differentiate between vendors. 

• params are optional semi-colon separated parameters particular to the IMS scheme used. If the parameter 

value is set incorrectly an IllegalArgumentException is thrown. 

The returned Service object depends on the used scheme. 

The call to Connector.open() is synchronous, and for some services the call might take several seconds to 

complete. Also observe that the following actions to open a service are equivalent: 

Connector.open("imscore://myAppId;ServiceID=") and Connector.open("imscore://myAppId"). 

Exceptions when opening a service 

The following exceptions can be thrown when calling Connector.Open(). 

• IllegalArgumentException - If a parameter is invalid. 

• ConnectionNotFoundException - If the target of the name cannot be found, or if the requested protocol 

type is not supported. 

• IOException - If some other kind of I/O error occurs. 

• SecurityException - May be thrown if access to the protocol handler is prohibited. 

The following exceptions can be throws due to IMS specific errors. 

• IOException - The IMS profile is missing or corrupt. 

• IOException - The Internet profile is missing or corrupt. 

• IOException - The subscriber failed to authenticate within the IMS network. 

• IOException - The Register request failed to reach the IMS network. 

• IOException - The IMS network responded with a service or server specific error code. 

• ConnectionNotFoundException - The AppId is not an installed IMS Application. 

Closing a service 



The application SHOULD invoke close() on the Service when it is finished using the Service. 

See Also: 

CoreService 


String getAppId() 

Returns the application id string that this Service was created with. 

String getScheme() 

Returns the scheme used for this Service. 

Page 

44 

44 

Methods inherited from interface javax.microedition.io.Connection 

close 

Method Detail 

getAppId 

String getAppId() 

Returns the application id string that this Service was created with. 

Returns: 

the application id of this Service 

getScheme 

String getScheme() 

Returns the scheme used for this Service. 

Returns: 

the scheme used for this Service 


Class ServiceClosedException 

Class ServiceClosedException 





java.io.IOException 

javax.microedition.ims.ServiceClosedException 

public class ServiceClosedException 

extends java.io.IOException 

A ServiceClosedException indicates that a method is invoked on a Service that is closed. 


ServiceClosedException() 

Constructs a ServiceClosedException with null as its error detail message. 

ServiceClosedException(String reason) 

Constructs a ServiceClosedException with the specified detail message. 

Page 

45 

45 



public ServiceClosedException() 

Constructs a ServiceClosedException with null as its error detail message. 


public ServiceClosedException(String reason) 

Constructs a ServiceClosedException with the specified detail message. The error message string 

reason can later be retrieved by the Throwable.getMessage() method of class java.lang.Throwable. 

Parameters: 



Package javax.microedition.ims.core 


This package collects classes and interfaces that enable an application to create IMS services. 

See: 

Description 


Capabilities 

CapabilitiesListener 

CoreService 

CoreServiceListener 

Message 

MessageBodyPart 

PageMessage 

PageMessageListener 

The Capabilities is used to query a remote endpoint whether it has matching 

capabilities matching the local ones. 

This listener type is used to notify the application about responses to capability 

queries. 

The CoreService gives the application the possibility to call remote peers over the 

IMS network. 

A listener type for receiving notifications on remotely initiated core service 

methods. 

The Message interface provides functionality to manipulate headers and body parts 

of SIP messages. 

A MessageBodyPart can contain different kinds of content, for example text, an 

image or an audio clip. 

The PageMessage interface is used for simple instant messages or exchange of 

small amounts of content outside of a session. 

This listener type is used to notify the application about the status of sent page 

messages. 

Publication The Publication is used for publishing event state to a remote endpoint. 77 

PublicationListener 

Reference 

ReferenceListener 

ServiceMethod 

This listener type is used to notify the application of the status of requested 

publications. 

The Reference is used for referring a remote endpoint to a third party user or 

service. 

This listener type is used to notify an application about events regarding a 

Reference. 

The ServiceMethod interface provides methods to manipulate the next outgoing 

request message and to inspect previously sent request and response messages. 

Session The Session is a representation of a media exchange between two IMS endpoints. 98 

SessionDescriptor 

The Session Description Protocol (SDP) [RFC4566] is used to convey information 

about media streams in a session such that the endpoints can connect and 

participate. 

SessionListener A listener type for receiving notification on session events. 115 

Subscription 

SubscriptionListener 

A Subscription is used for subscribing to events of the event package sent from 

the remote server endpoint. 

This listener type is used to notify the application about subscription status and the 

event state of the subscribed event package. 

Page 

48 

51 

52 

59 

64 

70 

72 

76 

81 

83 

91 

93 

111 

118 

122 

Class Summary 

ImscoreProtocolPermission 

This class represents permission to connections using the imscore connector 

string. 

Page 

61 



Exception Summary 

CoreServiceException A CoreServiceException indicates that a CoreService could not be created. 58 

Package javax.microedition.ims.core Description 

This package collects classes and interfaces that enable an application to create IMS services. 

Page 

Static Structure 

Figure 1: Static structure of the package. 


Interface Capabilities 


javax.microedition.ims.core 


ServiceMethod 

public interface Capabilities 

extends ServiceMethod 

The Capabilities is used to query a remote endpoint whether it has matching capabilities matching the local 

ones. 

Example use of Capabilities 

public void checkSupport(CoreService service){ 

try { 

Capabilities caps; 

caps = service.createCapabilities(null, "Alice "); 

caps.setListener(this); 

caps.queryCapabilities(false); 

} catch(Exception e){ 

// handle Exceptions 

} 

} 

public void capabilityQueryDelivered(Capabilities caps){ 

String conn = "imscore://com.myCompany.games.chess"; 

boolean feat = caps.hasCapabilities(conn); 

if (feat) { 

cs = (CoreService)Connector.open(conn); 

... 

} 

See Also: 

CoreService.createCapabilities(String, String) 

Field Summary 

int STATE_ACTIVE 

The capability response is received. 

int STATE_INACTIVE 

The capability request has not been sent. 

int STATE_PENDING 

The capability request is sent and the platform is waiting for a response. 

Page 

49 

49 

49 


String[] getRemoteUserIdentities() 

Returns an array of strings representing valid user identities for the remote endpoint. 

int getState() 

Returns the current state of this Capabilities. 

boolean hasCapabilities(String connection) 

This method returns true if the remote endpoint is believed to be sufficiently capable of 

handling requests from a certain core service on the local endpoint. 

void queryCapabilities(boolean sdpInRequest) 

Sends a capability request to a remote endpoint. 

Page 

49 

50 

50 

49 



void setListener(CapabilitiesListener listener) 

Sets a listener for this Capabilities, replacing any previous CapabilitiesListener. 

50 

Methods inherited from interface javax.microedition.ims.core.ServiceMethod 

getNextRequest, getNextResponse, getPreviousRequest, getPreviousResponses, getRemoteUserId 

Field Detail 

STATE_INACTIVE 

public static final int STATE_INACTIVE 

The capability request has not been sent. 

STATE_PENDING 

public static final int STATE_PENDING 

The capability request is sent and the platform is waiting for a response. 

STATE_ACTIVE 

public static final int STATE_ACTIVE 

The capability response is received. 

Method Detail 

queryCapabilities 

void queryCapabilities(boolean sdpInRequest) 

throws ServiceClosedException 

Sends a capability request to a remote endpoint. 

The Capabilities will transit to STATE_PENDING after calling this method. 

Parameters: 

sdpInRequest - if true, the IMS engine will add a Session Description Protocol (SDP) to the 

capability request 

Throws: 

ServiceClosedException - if the Service is closed 

IllegalStateException - if the Capabilities is not in STATE_INACTIVE 

getRemoteUserIdentities 

String[] getRemoteUserIdentities() 

Returns an array of strings representing valid user identities for the remote endpoint. 



Returns: 

an array of user identities, an empty array will be returned if no user identities could be retrieved 

Throws: 

IllegalStateException - if the Capabilities is not in STATE_ACTIVE 

getState 


Returns the current state of this Capabilities. 

Returns: 

the current state of this Capabilities 

hasCapabilities 

boolean hasCapabilities(String connection) 

This method returns true if the remote endpoint is believed to be sufficiently capable of handling requests 

from a certain core service on the local endpoint. The core service is specified with an imscore connector 

string. 

Note: Even if this method returns true, it is not guaranteed that requests are indeed supported at the 

remote. 

Example: 

String imscore = "imscore://com.myCompany.games.chess"; 

if (caps.hasCapabilities(imscore)) { 

CoreService = (CoreService)Connector.open(imscore); 

... 

} else { 

// No point in trying to create the service. 

} 

Parameters: 

connection - the imscore connector string to check. 

Returns: 

true if the remote endpoint has the capabilities, otherwise false 

Throws: 

IllegalStateException - if the Capabilities is not in STATE_ACTIVE 

IllegalArgumentException - if the connection argument is null, unknown or invalid syntax 

setListener 

void setListener(CapabilitiesListener listener) 

Sets a listener for this Capabilities, replacing any previous CapabilitiesListener. A null reference is 

allowed and has the effect of removing any existing listener. 

Parameters: 

listener - the listener to set, or null 


Interface CapabilitiesListener 

Interface CapabilitiesListener 


public interface CapabilitiesListener 

This listener type is used to notify the application about responses to capability queries. 

See Also: 

Capabilities.setListener(CapabilitiesListener) 


void capabilityQueryDelivered(Capabilities capabilities) 

Notifies the application that the capability query response from the remote endpoint was 

successfully received. 

void capabilityQueryDeliveryFailed(Capabilities capabilities) 

Notifies the application that the capability query response from the remote endpoint was not 

successfully received. 

Page 

51 

51 

Method Detail 

capabilityQueryDelivered 

void capabilityQueryDelivered(Capabilities capabilities) 

Notifies the application that the capability query response from the remote endpoint was successfully 

received. 

The Capabilities has transited to STATE_ACTIVE. 

Parameters: 

capabilities - the concerned Capabilities 

capabilityQueryDeliveryFailed 

void capabilityQueryDeliveryFailed(Capabilities capabilities) 

Notifies the application that the capability query response from the remote endpoint was not successfully 

received. 

The Capabilities has transited to STATE_INACTIVE. 

Parameters: 

capabilities - the concerned Capabilities 


Interface CoreService 




javax.microedition.io.Connection, Service 

public interface CoreService 

extends Service 

The CoreService gives the application the possibility to call remote peers over the IMS network. There is a set of 

basic call types in the CoreService that can be created via factory methods, see ServiceMethod. 

The application can react to incoming IMS calls by implementing the listener interface CoreServiceListener. 

Integration of CoreService to GCF 

Connector.open(String name) 

A CoreService is created with Connector.open, see Service, using an imscore connector string as name: 

• imscore:[] 

where target is the application id, and are the optional semi-colon separated parameters: 

• userId= is the local user identity that the user prefers to be in effect for this core 

service. The preference is used to override the default public user identity of the device. The userId 

parameter accepts a display name together with the URI using standard syntax. 

• serviceId= is set if this CoreService shall support the service alias specified in the 

Registry. If this parameter is unspecified, the service alias defaults to the empty string. 

The javax.microedition.io.Connector class is defined in the CLDC specifications (JSR30, JSR139) and is 

used here to create services. The Open method allows some variation, and it is shown below how this works for the 

imscore: connector string. 

Connector.open(String name, String mode) 

The optional second parameter 'mode' in Connector.open specifies the access mode that can be READ, WRITE, 

READ_WRITE. The mode is not relevant. 

Connector.open(String name, String mode, boolean timeouts) 

The optional third parameter is a boolean flag that indicates if the calling code can handle timeout exceptions when 

creating the service. 

Exceptions when opening a CoreService 

The following exceptions can be throws due to CoreService specific errors, see Service for more exceptions. 

• CoreServiceException - The CoreService could not be created, see javax.microedition.ims.core for 

more information. The reason for not creating the CoreService could be retrieved from the ReasonInfo 

interface. 

... 

} catch (CoreServiceException cse) { 

ReasonInfo info; 

String reasonPhrase; 

int reasonType; 

int statusCode; 



} 

info = cse.getReasonInfo(); 

reasonPhrase = info.getReasonPhrase(); 

reasonType = info.getReasonType(); 

statusCode = info.getStatusCode(); 

... 

CoreService creation rules 

For a given application identity and no service identity, it is possible to create at most one instance of a 

CoreService. For a given application identity and a service identity, it is possible to have at most one 

CoreService. 

Examples 

This code shows how to create a CoreService with the application identity com.myCompany.games.chess. In the 

first example the user identity will be the default user identity provisioned by the IMS network. In the second 

example the application overrides the user identity to use in this CoreService. The third example shows a call 

used to create a CoreService with a service identity specified. 

service = (CoreService) Connector.open("imscore://com.myCompany.games.chess"); 

service = (CoreService) Connector.open("imscore://com.myCompany.games.chess; 

userId=Alice "); 

service = (CoreService) Connector.open("imscore://com.myCompany.games.chess; 

userId=Alice 

serviceId=game"); 

Closing a CoreService 

The application SHOULD invoke close on the CoreService when it is finished using the CoreService. The IMS 

engine may also close the CoreService due to external events. This will trigger a call to serviceClosed on the 

CoreServiceListener interface. 

Creating a service method, example 

Alice invites Bob using their public user identities as addresses: 

coreService.createSession("sip:alice@home.net", "sip:bob@home.net"); 

The sender requests anonymity in this request by using "Anonymous" as display name in the from argument: 

coreService.createSession("Anonymous ", 

"sip:bob@home.net"); 

Alice uses her display name when inviting Bob: 

coreService.createSession("Alice ", "sip:bob@home.net"); 

For more information on the contents of the from and to arguments in service methods, please see section on 

User and Service Addressing in the overview. 

See Also: 

CoreServiceListener 


Capabilities createCapabilities(String from, String to) 

Creates a Capabilities with from as sender, addressed to to. 

Page 

56 



PageMessage createPageMessage(String from, String to) 

Creates a PageMessage with from as sender, addressed to to. 

Publication createPublication(String from, String to, String event) 

Creates a Publication for an event package with from as sender and to as the user 

identity to publish event state on. 

Reference createReference(String from, String to, String referTo, String referMethod) 

Creates a Reference with from as sender, addressed to to and referTo as the URI to 

refer to. 

Session createSession(String from, String to) 

Creates a Session with from as sender, with to as recipient. 

Subscription createSubscription(String from, String to, String event) 

Creates a Subscription for an event package with from as sender and to as the user 

identity to subscribe event state on. 

String getLocalUserId() 

Returns the display name and public user identity for the CoreService. 

void setListener(CoreServiceListener listener) 

Sets a listener for this CoreService, replacing any previous CoreServiceListener. 

54 

55 

57 

56 

55 

54 

57 

Methods inherited from interface javax.microedition.ims.Service 

getAppId, getScheme 

Methods inherited from interface javax.microedition.io.Connection 

close 

Method Detail 

getLocalUserId 

String getLocalUserId() 

Returns the display name and public user identity for the CoreService. This is either the value of the 

userId= parameter of the imscore: locator used to create the core service, or default value of the device. 

Returns: 

a public user identity, possibly with a display name 

createPageMessage 

PageMessage createPageMessage(String from, 

String to) 

throws ServiceClosedException, 

ImsException 

Creates a PageMessage with from as sender, addressed to to. 

Parameters: 

from - the sender SIP or TEL URI with an optional display name. If null, from is assumed to be 

the local user identity of the Service 

to - the recipient SIP or TEL URI with an optional display name to send a PageMessage to 

Returns: 

a new PageMessage 



Throws: 


ImsException - if the PageMessage could not be created 

IllegalArgumentException - if the to argument is null, 

if the syntax of the from or to argument is invalid 

createPublication 

Publication createPublication(String from, 

String to, 

String event) 


ImsException 

Creates a Publication for an event package with from as sender and to as the user identity to publish 

event state on. 

The event package must be defined as a JAD file property or set with the setRegistry method in the 

Configuration class. 

Parameters: 



to - the recipient SIP or TEL URI with an optional display name to publish event state information 

on. If null, to is assumed to be the local user of the Service 

event - the event package to publish event state information on 

Returns: 

a new Publication 

Throws: 


ImsException - if the Publication could not be created 

IllegalArgumentException - if the syntax of the from or to argument is invalid, 

if the event argument is not a defined event package 

createSubscription 

Subscription createSubscription(String from, 

String to, 

String event) 


ImsException 

Creates a Subscription for an event package with from as sender and to as the user identity to 

subscribe event state on. 

The event package must be defined as a JAD file property or set with the setRegistry method in the 

Configuration class. 

Parameters: 



to - the recipient SIP or TEL URI with an optional display name to subscribe state information on. If 

null, to is assumed is assumed to be the local user of the Service 

event - the event package to subscribe state information on 

Returns: 

a new Subscription 



Throws: 


ImsException - if the Subscription could not be created 

IllegalArgumentException - if the syntax of the from or to argument is invalid, 

if the event argument is not a defined event package 

createCapabilities 

Capabilities createCapabilities(String from, 

String to) 


ImsException 

Creates a Capabilities with from as sender, addressed to to. 

Parameters: 



to - the recipient SIP or TEL URI with an optional display name. 

Returns: 

a new Capabilities 

Throws: 


ImsException - if the Capabilities could not be created 



createSession 

Session createSession(String from, 

String to) 


ImsException 

Creates a Session with from as sender, with to as recipient. 

Parameters: 

from - the sender SIP or TEL URI with an optional display name. If the argument is null then it is 

by default set to the preferred public user identity from this core service. If it has a domain name of 

anonymous.invalid then the originator will be kept anonymous according to [RFC3323] and 

[RFC3325]. 

The format of SIP URI is described in [RFC3261], TEL URI in [RFC3966], and display names in 

general in [RFC5322]. 

to - the recipient SIP or TEL URI with an optional display name. 

Returns: 

a new Session 

Throws: 


ImsException - if the Session could not be created 





createReference 

Reference createReference(String from, 

String to, 

String referTo, 

String referMethod) 


ImsException 

Creates a Reference with from as sender, addressed to to and referTo as the URI to refer to. 

Parameters: 

from - the sender SIP or TEL URI with an optional display name. If null, it is assumed to be the 

local user identity of the Service 

to - the recipient SIP or TEL URI with an optional display name 

referTo - any URI, not just a user id 

referMethod - the reference method to be used by the reference request, e.g. "INVITE", "BYE" or 

null 

Returns: 

a new Reference 

Throws: 


ImsException - if the Reference could not be created 

IllegalArgumentException - if the to or referTo argument is null, 

if the syntax of the from, to is invalid, or if referTo argument is null, 

if the syntax of the referMethod argument is invalid 

setListener 

void setListener(CoreServiceListener listener) 

Sets a listener for this CoreService, replacing any previous CoreServiceListener. A null removes any 

existing listener. 

Parameters: 



Class CoreServiceException 

Class CoreServiceException 





java.io.IOException 

javax.microedition.ims.core.CoreServiceException 

public class CoreServiceException 

extends java.io.IOException 

A CoreServiceException indicates that a CoreService could not be created. 


CoreServiceException(ReasonInfo reason) 

Constructs a CoreServiceException with the specified detail message. 

Page 

58 


ReasonInfo getReasonInfo() 

Returns a ReasonInfo that indicates why the CoreService was closed. 

Page 

58 


CoreServiceException 

public CoreServiceException(ReasonInfo reason) 

Constructs a CoreServiceException with the specified detail message. The error message string reason 

can later be retrieved by the Throwable.getMessage() method of class java.lang.Throwable. 

Parameters: 


Method Detail 

getReasonInfo 

public ReasonInfo getReasonInfo() 

Returns a ReasonInfo that indicates why the CoreService was closed. 

Returns: 

a ReasonInfo 


Interface CoreServiceListener 



public interface CoreServiceListener 

A listener type for receiving notifications on remotely initiated core service methods. 

See Also: 

CoreService.setListener(CoreServiceListener) 


void pageMessageReceived(CoreService service, PageMessage message) 

Notifies the application when a page message is received from a remote endpoint. 

void referenceReceived(CoreService service, Reference reference) 

Notifies the application when a reference request is received from a remote endpoint. 

void serviceClosed(CoreService service, ReasonInfo reason) 

Notifies the application when a CoreService is closed. 

void sessionInvitationReceived(CoreService service, Session session) 

Notifies the application when a session invitation is received from a remote endpoint. 

void unsolicitedNotifyReceived(CoreService service, Message notify) 

Notifies the application when an unsolicited notify is received. 

Page 

59 

60 

60 

59 

60 

Method Detail 

pageMessageReceived 

void pageMessageReceived(CoreService service, 

PageMessage message) 

Notifies the application when a page message is received from a remote endpoint. 

Parameters: 

service - the concerned Service 

message - the received PageMessage 

sessionInvitationReceived 

void sessionInvitationReceived(CoreService service, 

Session session) 

Notifies the application when a session invitation is received from a remote endpoint. 

Parameters: 


session - the received session invitation 

See Also: 

Session.accept(), Session.reject() 



referenceReceived 

void referenceReceived(CoreService service, 

Reference reference) 

Notifies the application when a reference request is received from a remote endpoint. 

Only references that are created outside of a session are notified in this method. 

Parameters: 


reference - the received reference 

unsolicitedNotifyReceived 

void unsolicitedNotifyReceived(CoreService service, 

Message notify) 

Notifies the application when an unsolicited notify is received. This notify request is received outside any 

existing subscription. 

Parameters: 


notify - the received notify 

serviceClosed 

void serviceClosed(CoreService service, 

ReasonInfo reason) 

Notifies the application when a CoreService is closed. 

Parameters: 


reason - a ReasonInfo to indicate why the CoreService was closed 


Class ImscoreProtocolPermission 




java.security.Permission 

javax.microedition.io.GCFPermission 

javax.microedition.ims.core.ImscoreProtocolPermission 

public class ImscoreProtocolPermission 

extends javax.microedition.io.GCFPermission 

This class represents permission to connections using the imscore connector string. There is no action list defined 

for the class. 

The syntax of the imscore connector string is defined in javax.microedition.imscore package. 


ImscoreProtocolPermission(String imscore) 

Creates a new ImscorePermission with the specified imscore connector string as its name. 

Page 

61 


boolean equals(Object obj) 

Checks two ImscorePermission objects for equality. 

String getActions() 

Returns the canonical string representation of the actions, which currently is the empty string 

"", since there are no actions defined for ImscoreProtocolPermission. 

int hashCode() 

Returns the hash code value for this object. 

boolean implies(java.security.Permission p) 

Checks if this ImscoreProtocolPermission object "implies" the specified permission. 

Page 

62 

62 

62 

62 

Methods inherited from class javax.microedition.io.GCFPermission 

getProtocol, getURI 

Methods inherited from class java.security.Permission 

getName, newPermissionCollection, toString 


ImscoreProtocolPermission 

public ImscoreProtocolPermission(String imscore) 

Creates a new ImscorePermission with the specified imscore connector string as its name. The string 

must either conform to the specification of the imscore connector string identifying a core service, or be 

"imscore://*" meaning that the permission applies to any imscore connector string in the IMS application 

suite. 

Parameters: 

imscore - the imscore URI connector string 



Throws: 

IllegalArgumentException - if imscore is null or otherwise malformed 

Method Detail 

equals 

public boolean equals(Object obj) 

Checks two ImscorePermission objects for equality. 

Overrides: 

equals in class java.security.Permission 

Parameters: 

obj - the object we are testing for equality with this object. 

Returns: 

true if obj is a ImscoreProtocolPermission and has the same connector string as this 

ImscoreProtocolPermission object 

getActions 

public String getActions() 

Returns the canonical string representation of the actions, which currently is the empty string "", since there 

are no actions defined for ImscoreProtocolPermission. 

Overrides: 

getActions in class java.security.Permission 

Returns: 

the empty string "" 

See Also: 

java.security.Permission.getActions() 

hashCode 

public int hashCode() 


Overrides: 

hashCode in class java.security.Permission 

Returns: 

a hash code value for this object. 

implies 

public boolean implies(java.security.Permission p) 

Checks if this ImscoreProtocolPermission object "implies" the specified permission. This is always 

false, since there are no permissions implied for ImscoreProtocolPermission. 

Overrides: 

implies in class java.security.Permission 



Parameters: 

p - the permission to check against. 

Returns: 

false 


Interface Message 



public interface Message 

The Message interface provides functionality to manipulate headers and body parts of SIP messages. 

This is an interface for use in advanced applications. 

A Message can be retrieved by calling ServiceMethod.getNextRequest, ServiceMethod.getPreviousRequest, 

ServiceMethod.getNextResponse or ServiceMethod.getPreviousResponses. 

Modifying headers 

The IMSAPI allows the application to read and write to SIP message headers. A header with no predefined 

meaning or standard can be read and written without restriction. If the header is covered in a standard, then any 

modification to the header must be in accordance to the standard. 

Modifying the 'Content-Type' header 

The 'Content-Type' header can only be set on messages with more than one bodypart, and only to 'multipart/*'. See 

also section below on Modifying message bodies. 

Read-only headers 

These headers can only be read, an ImsException should be thrown if the application tries to modify them: 

Accept-Contact, Call-ID, Contact, Content-Length, CSeq, Event, From, P-Access-Network-Info, 

P-Asserted-Identity, P-Associated-URI, P-Preferred-Identity, RAck, Refer-To, Referred-By, Replaces, 

RSeq, To, WWW-Authenticate 

Inaccessible headers 

These headers can not be read or modified, an ImsException should be thrown if the application tries to read or 

modify them: 

Authentication-Info, Authorization, Max-Forwards, Min-Expires, Proxy-Authenticate, 

Proxy-Authorization, Record-Route, Security-Client, Security-Server, Security-Verify, 

Service-Route, Via 

Modifying message bodies 

The interface allows the application to create non-recursive multi-part SIP messages bodies. The following shows 

how the object structure is mapped to the SIP message structure. For the sending side: 

• If a Message has one MessageBodyPart then the Message will have the body content and content type set 

to the MessageBodyPart content and content type. 

• If a Message has several MessageBodyParts, then each MessageBodyPart ( recursive MessageBodyPart 

are not possible) is mapped to a part in the SIP message body (content and headers, including the content 

type). The message body content type is by default set to multipart/mixed, but can be overridden by the 

application to be of another subtype to multipart. 

NOTE: For the case where the IMS engine has an SDP attached to the SIP message, then that is handled 

as if it were a MessageBodyPart not accessible to the application. 

For the receiving side: 

• A SIP message with a body where content type is not multipart is handled as a Message with one 

MessageBodyPart and that content type. 



• A multipart message (of any subtype) is parsed and each part on the top level is mapped to a 

MessageBodyPart (nested multi-part messages cannot be mapped to recursive MessageBodyParts). 

Note: Any SDP part discovered here shall not be mapped to a MessageBodyPart accessible to the 

application, unless it is part of an OPTIONS response. 

See [RFC3261] for more information about headers and body parts in a request messages. 

See Also: 

ServiceMethod 

Field Summary 

int CAPABILITIES_QUERY 

Identifier for the queryCapabilities method on the Capabilities interface. 

int PAGEMESSAGE_SEND 

Identifier for the send method on the PageMessage interface. 

int PUBLICATION_PUBLISH 

Identifier for the publish method on the Publication interface. 

int PUBLICATION_UNPUBLISH 

Identifier for the unpublish method on the Publication interface. 

int REFERENCE_REFER 

Identifier for the refer method on the Reference interface. 

int SESSION_START 

Identifier for the start method on the Session interface. 

int SESSION_TERMINATE 

Identifier for the terminate method on the Session interface. 

int SESSION_UPDATE 

Identifier for the update method on the Session interface. 

int STATE_RECEIVED 

This state specifies that this Message was received from a remote endpoint. 

int STATE_SENT 

This state specifies that the Message is sent from the local endpoint. 

int STATE_UNSENT 

This state specifies that the Message is unsent. 

int SUBSCRIPTION_POLL 

Identifier for the poll method on the Subscription interface. 

int SUBSCRIPTION_SUBSCRIBE 

Identifier for the subscribe method on the Subscription interface. 

int SUBSCRIPTION_UNSUBSCRIBE 

Identifier for the unsubscribe method on the Subscription interface. 

Page 

66 

66 

66 

66 

66 

66 

67 

67 

67 

67 

67 

67 

67 

67 


void addHeader(String key, String value) 

Adds a header value, either on a new header or appending a new value to an 

already existing header. 

MessageBodyPart createBodyPart() 

Creates a new MessageBodyPart and adds it to the message. 

MessageBodyPart[] getBodyParts() 

Returns all body parts that are added to the message. 

String[] getHeaders(String key) 

Returns the value(s) of a header in this message. 

Page 

68 

68 

68 

68 



String getMethod() 

Returns the SIP method for this Message. 


Returns the reason phrase of the response. 


Returns the current state of this Message. 


Returns the status code of the response. 

69 

69 

69 

69 

Field Detail 

CAPABILITIES_QUERY 

public static final int CAPABILITIES_QUERY 

Identifier for the queryCapabilities method on the Capabilities interface. 

PAGEMESSAGE_SEND 

public static final int PAGEMESSAGE_SEND 

Identifier for the send method on the PageMessage interface. 

PUBLICATION_PUBLISH 

public static final int PUBLICATION_PUBLISH 

Identifier for the publish method on the Publication interface. 

PUBLICATION_UNPUBLISH 

public static final int PUBLICATION_UNPUBLISH 

Identifier for the unpublish method on the Publication interface. 

REFERENCE_REFER 

public static final int REFERENCE_REFER 

Identifier for the refer method on the Reference interface. 

SESSION_START 

public static final int SESSION_START 

Identifier for the start method on the Session interface. 



SESSION_UPDATE 

public static final int SESSION_UPDATE 

Identifier for the update method on the Session interface. 

SESSION_TERMINATE 

public static final int SESSION_TERMINATE 

Identifier for the terminate method on the Session interface. 

SUBSCRIPTION_SUBSCRIBE 

public static final int SUBSCRIPTION_SUBSCRIBE 

Identifier for the subscribe method on the Subscription interface. 

SUBSCRIPTION_UNSUBSCRIBE 

public static final int SUBSCRIPTION_UNSUBSCRIBE 

Identifier for the unsubscribe method on the Subscription interface. 

SUBSCRIPTION_POLL 

public static final int SUBSCRIPTION_POLL 

Identifier for the poll method on the Subscription interface. 

STATE_UNSENT 

public static final int STATE_UNSENT 

This state specifies that the Message is unsent. 

STATE_SENT 

public static final int STATE_SENT 

This state specifies that the Message is sent from the local endpoint. 

STATE_RECEIVED 

public static final int STATE_RECEIVED 

This state specifies that this Message was received from a remote endpoint. 



Method Detail 

createBodyPart 

MessageBodyPart createBodyPart() 

throws ImsException 

Creates a new MessageBodyPart and adds it to the message. 

Returns: 

a MessageBodyPart 

Throws: 

ImsException - if the body part could not be created 

IllegalStateException - if the Message is not in STATE_UNSENT 

getBodyParts 

MessageBodyPart[] getBodyParts() 

Returns all body parts that are added to the message. 

Note: If the body part is a Session Description Protocol (SDP) it is only returned if the Message is a 

response to a capability request. 

Returns: 

a copy of all MessageBodyParts in the message body, an empty array will be returned if there are 

no body parts in the Message 

addHeader 

void addHeader(String key, 

String value) 


Adds a header value, either on a new header or appending a new value to an already existing header. 

The header(s) that can be added must be defined in the Write property of the JAD file or set with the 

setRegistry method in the Configuration class. 

Parameters: 

key - the header name, in full form (see RFC3261) 

value - the header value 

Throws: 

ImsException - if the key is not a defined header or a restricted header 

IllegalArgumentException - if the key is null or invalid, 

if the value is null or invalid 


getHeaders 

String[] getHeaders(String key) 




Returns the value(s) of a header in this message. The header must be defined in the Read property of the 

JAD file or set with the setRegistry method in the Configuration class. 

Parameters: 


Returns: 

an array of all value(s) of the header, an empty array is returned if the header does not exist 

Throws: 

ImsException - if the key is not a defined header or a restricted header 

getMethod 

String getMethod() 

Returns the SIP method for this Message. 

Returns: 

SIP method name, INVITE, UPDATE, BYE, etc. or null if the method is not available 

getState 


Returns the current state of this Message. 

Returns: 

the current state of this Message 

getStatusCode 


Returns the status code of the response. This method can only be used for response messages as request 

messages do not have a status code. 

See [RFC3261] (chapter 7.2 Responses) for more detailed information. 

Returns: 

the status code, returns 0 if the status code is not available 

getReasonPhrase 


Returns the reason phrase of the response. This method can only be used for response messages as 

request messages do not have a reason phrase. 

Returns: 

the reason phrase or null if the reason phrase is not available 


Interface MessageBodyPart 



public interface MessageBodyPart 

A MessageBodyPart can contain different kinds of content, for example text, an image or an audio clip. 

There are two main uses for a MessageBodyPart: 

• A MessageBodyPart can be created and attached to the next outgoing request Message by calling 

createBodyPart on a Message. 

• A MessageBodyPart can be extracted from a previously sent or received Message by calling getBodyParts 

on a Message. 

See [RFC2045, 2046] for more information about body parts. [RFC2045] also describes some possible headers to 

set with the setHeader method. 

See Also: 

ServiceMethod, Message 


String getHeader(String key) 

Returns the value of a header in this MessageBodyPart. 

java.io.InputStream openContentInputStream() 

Opens an InputStream to read the content of the MessageBodyPart. 

java.io.OutputStream openContentOutputStream() 

Opens an OutputStream to write the content of the MessageBodyPart. 

void setHeader(String key, String value) 

Sets a header to the MessageBodyPart. 

Page 

71 

70 

70 

71 

Method Detail 

openContentInputStream 

java.io.InputStream openContentInputStream() 

throws java.io.IOException 

Opens an InputStream to read the content of the MessageBodyPart. 

Returns: 

an InputStream to read the content of the MessageBodyPart 

Throws: 

java.io.IOException - if the InputStream could not be opened 

See Also: 

openContentOutputStream() 

openContentOutputStream 

java.io.OutputStream openContentOutputStream() 




Opens an OutputStream to write the content of the MessageBodyPart. If the OutputStream is not closed, it 

will be closed by the ServiceMethod that invoked a transmission of the Message. 

Returns: 

an OutputStream to write the content of the MessageBodyPart 

Throws: 

java.io.IOException - if the OutputStream could not be opened or if the OutputStream already 

has been opened 


See Also: 

openContentInputStream() 

setHeader 

void setHeader(String key, 

String value) 

Sets a header to the MessageBodyPart. If the header key already exists the value will be replaced. 

Only headers with the prefix "Content-" are allowed to set with this method. 

Parameters: 


value - the header value 

Throws: 

IllegalArgumentException - if the key is null or invalid, 

if the value is null or invalid 


See Also: 

getHeader(String) 

getHeader 

String getHeader(String key) 

Returns the value of a header in this MessageBodyPart. 

Only headers with the prefix "Content-" are allowed to be retrieved with this method. 

Parameters: 


Returns: 

a string containing the header value or null if the header does not exist 

Throws: 

IllegalArgumentException - if the key is null or invalid 

See Also: 

setHeader(String, String) 


Interface PageMessage 




ServiceMethod 

public interface PageMessage 


The PageMessage interface is used for simple instant messages or exchange of small amounts of content outside 

of a session. 

The life cycle consist of three states, STATE_UNSENT, STATE_SENT and STATE_RECEIVED. 

A PageMessage created with the factory method createPageMessage in the CoreService interface will reside in 

STATE_UNSENT. When the message is sent with the send method the state will transit to STATE_SENT and further 

send requests cannot be made on the same PageMessage. 

An incoming PageMessage will always reside in STATE_RECEIVED. 

Example of sending a simple PageMessage 

try { 

PageMessage pageMessage; 

pageMessage = service.createPageMessage(null, "sip:baloo@lalaa.net"); 

pageMessage.setListener(this); 

pageMessage.send("Hi, I'm Alice!".getBytes(),"text/plain"); 

} catch (Exception e) { 

//handle Exceptions 

} 

Example of sending a multipart PageMessage 

try { 

PageMessage pageMessage; 

pageMessage = service.createPageMessage(null, "sip:baloo@lalaa.net"); 

pageMessage.setListener(this); 

Message message = pageMessage.getNextRequest(); 

// add first body part 

MessageBodyPart part1 = message.createBodyPart(); 

part1.setHeader("Content-Type", "text/plain"); 

OutputStream os = part1.openContentOutputStream(); 

os.write(...); 

os.close(); 

// add following body parts 


... 

// when all body parts has been added 

pageMessage.send(null, null); 

} catch (Exception e) { 


} 

Example of receiving a PageMessage 

The callback method pageMessageReceived is found in the CoreServiceListener interface. 

public void pageMessageReceived(CoreService service, 

PageMessage pageMessage) { 

pageMessage.getContent(); 

... // process content 

} 



See Also: 

CoreService.createPageMessage(String, String), 

CoreServiceListener.pageMessageReceived(CoreService, PageMessage) 

Field Summary 

int STATE_RECEIVED 

This state specifies that this PageMessage was received from a remote endpoint. 

int STATE_SENT 

This state specifies that the PageMessage is sent. 

int STATE_UNSENT 

This state specifies that the PageMessage is unsent. 

Page 

73 

73 

73 


byte[] getContent() 

String getContentType() 

Returns the content from this PageMessage. 

Returns the content MIME type of this PageMessage. 


Returns the current state of this PageMessage. 

void send(byte[] content, String contentType) 

Sends the PageMessage. 

void setListener(PageMessageListener listener) 

Sets a listener for this PageMessage, replacing any previous PageMessageListener. 

Page 

74 

74 

75 

74 

74 



Field Detail 

STATE_UNSENT 

public static final int STATE_UNSENT 

This state specifies that the PageMessage is unsent. 

STATE_SENT 

public static final int STATE_SENT 

This state specifies that the PageMessage is sent. 

STATE_RECEIVED 

public static final int STATE_RECEIVED 

This state specifies that this PageMessage was received from a remote endpoint. 



Method Detail 

send 

void send(byte[] content, 

String contentType) 


Sends the PageMessage. 

This method can be invoked send(null, null) if the application uses the Message interface to fill the 

content. In the case that the application uses both the Message interface and send(content, 

contentType), the content will be added as the last body part. 

The PageMessage will transit to STATE_SENT after calling this method. See example above. 

Parameters: 

content - a byte array containing the content to be sent 

contentType - the content MIME type 

Throws: 


IllegalStateException - if the PageMessage is not in STATE_UNSENT 

IllegalArgumentException - if the syntax of the contentType argument is invalid or if one of the 

arguments is null 

setListener 

void setListener(PageMessageListener listener) 

Sets a listener for this PageMessage, replacing any previous PageMessageListener. A null reference is 


Parameters: 


getContent 

byte[] getContent() 

Returns the content from this PageMessage. This method will return the content from the first body part if 

there are more than one. 

Returns: 

an array containing the content 

Throws: 

IllegalStateException - if the PageMessage is not in STATE_RECEIVED 

getContentType 


Returns the content MIME type of this PageMessage. This method will return the content MIME type from 

the first body part if there are more than one. 



Returns: 

the content MIME type 

Throws: 

IllegalStateException - if the PageMessage is not in STATE_RECEIVED 

getState 


Returns the current state of this PageMessage. 

Returns: 

the current state of this PageMessage 


Interface PageMessageListener 

Interface PageMessageListener 


public interface PageMessageListener 

This listener type is used to notify the application about the status of sent page messages. 

See Also: 

PageMessage.setListener(PageMessageListener) 


void pageMessageDelivered(PageMessage pageMessage) 

Notifies the application that the PageMessage was successfully delivered. 

void pageMessageDeliveryFailed(PageMessage pageMessage) 

Notifies the application that the PageMessage was not successfully delivered. 

Page 

76 

76 

Method Detail 

pageMessageDelivered 

void pageMessageDelivered(PageMessage pageMessage) 

Notifies the application that the PageMessage was successfully delivered. 

Parameters: 

pageMessage - the concerned PageMessage 

pageMessageDeliveryFailed 

void pageMessageDeliveryFailed(PageMessage pageMessage) 

Notifies the application that the PageMessage was not successfully delivered. 

Parameters: 

pageMessage - the concerned PageMessage 


Interface Publication 




ServiceMethod 

public interface Publication 


The Publication is used for publishing event state to a remote endpoint. When a publication is created, an event 

package must be specified which identifies the type of content that is about to be published. A typical event 

package is 'presence' that can be used to publish online information. Other endpoints can then subscribe to that 

event package and get callbacks when the subscribed user identity changes online status. 

The published event state will be refreshed periodically until unpublish is called. Updates of the published event 

state may be achieved by calling the publish method again with modified event state. 

The life cycle consist of three states, STATE_INACTIVE, STATE_PENDING and STATE_ACTIVE. 

A new Publication starts in STATE_INACTIVE and when publish is called the state transits to STATE_PENDING 

and remains there until a response arrives from the remote endpoint. 

In STATE_ACTIVE, unpublish can be called to cancel the publication and the state will then transit to 

STATE_PENDING and remain there until a response arrives from the remote endpoint. 

Example of a simple Publication 

try { 

pub = service.createPublication(null, "sip:alice@home.net", "presence"); 

pub.setListener(this); 

pub.publish(onlineStatus, "application/pidf+xml"); 



} 

public void publicationDelivered(Publication pub){ 

//if the publish was successfull 

} 

Example of a multipart Publication 

try { 

pub = service.createPublication(null, "sip:alice@home.net", "presence"); 

pub.setListener(this); 

Message message = pub.getNextRequest(); 

// add first body part 


part1.setHeader("Content-Type", "application/pidf+xml"); 

OutputStream os = part1.openContentOutputStream(); 

os.write(...); 

os.close(); 

// add following body parts 


... 

// when all body parts have been added 

pub.publish(null, null); 



} 

public void publicationDelivered(Publication pub){ 

// if the publish was successful 



} 

See Also: 

CoreService.createPublication(String, String, String), Subscription 

Field Summary 


The Publication is active and event state is available for subscription. 


The Publication is not active, event state is not published. 


A Publication request is sent and the platform is waiting for a response. 

Page 

78 

78 

78 


String getEvent() 

Returns the event package corresponding to this Publication. 


Returns the current state of the state machine of this Publication. 

void publish(byte[] state, String contentType) 

Sends a publication request with an event state to the remote endpoint. 

void setListener(PublicationListener listener) 

Sets a listener for this Publication, replacing any previous PublicationListener. 

void unpublish() 

Terminates this publication. 

Page 

79 

80 

79 

79 

79 



Field Detail 



The Publication is not active, event state is not published. 

STATE_PENDING 


A Publication request is sent and the platform is waiting for a response. 

STATE_ACTIVE 


The Publication is active and event state is available for subscription. 



Method Detail 

publish 

void publish(byte[] state, 

String contentType) 


Sends a publication request with an event state to the remote endpoint. 

This method can be invoked publish(null, null) if the application uses the Message interface to fill the 

event state. In the case that the application uses both the Message interface and publish(state, 

contentType), the event state will be added as the last body part. 

The Publication will transit to STATE_PENDING after calling this method. See example above. 

Parameters: 

state - event state to publish 


Throws: 


IllegalStateException - if the Publication is in STATE_PENDING 

IllegalArgumentException - if the syntax of the contentType argument is invalid or if one of the 

arguments is null 

unpublish 

void unpublish() 


Terminates this publication. 

The Publication will transit to STATE_PENDING after calling this method. 

Throws: 


IllegalStateException - if the Publication is not in STATE_ACTIVE 

setListener 

void setListener(PublicationListener listener) 

Sets a listener for this Publication, replacing any previous PublicationListener. A null reference is 


Parameters: 


getEvent 


Returns the event package corresponding to this Publication. 



Returns: 

the event package 

getState 


Returns the current state of the state machine of this Publication. 

Returns: 

the current state 


Interface PublicationListener 



public interface PublicationListener 

This listener type is used to notify the application of the status of requested publications. 

See Also: 

Publication.setListener(PublicationListener) 


void publicationDelivered(Publication publication) 

Notifies the application that the publication request was successfully delivered. 

void publicationDeliveryFailed(Publication publication) 

Notifies the application that the publication request was not successfully delivered. 

void publicationTerminated(Publication publication) 

Notifies the application that the publication was terminated. 

Page 

81 

81 

81 

Method Detail 

publicationDelivered 

void publicationDelivered(Publication publication) 

Notifies the application that the publication request was successfully delivered. 

The Publication has transited to STATE_ACTIVE. 

Parameters: 

publication - the concerned Publication 

publicationDeliveryFailed 

void publicationDeliveryFailed(Publication publication) 

Notifies the application that the publication request was not successfully delivered. 

The Publication has transited to either STATE_ACTIVE or STATE_INACTIVE. 

Parameters: 


publicationTerminated 

void publicationTerminated(Publication publication) 

Notifies the application that the publication was terminated. 

The Publication has transited to STATE_INACTIVE. 



Parameters: 



Interface Reference 




ServiceMethod 

public interface Reference 


The Reference is used for referring a remote endpoint to a third party user or service. The Reference can be 

created and received both inside and outside of a session. 

Figure 1: The left figure shows the states for the local endpoint, the right figure shows the states for the remote 

endpoint. 

A Reference has four states: STATE_INITIATED, STATE_PROCEEDING, STATE_REFERRING and STATE_TERMINATED. 

Reference States 

This section describes the semantics for each of the Reference states at the local and remote endpoint. 

Local endpoint 

STATE_INITIATED 



When a Reference is created it will enter STATE_INITIATED. 

A Reference transits to: 

• STATE_PROCEEDING when refer is called on the Reference. 

STATE_PROCEEDING 

When refer is called the Reference enters STATE_PROCEEDING. Once this state is entered the communication with 

the remote endpoint starts and a reference is sent to the remote endpoint. 


• STATE_REFERRING if the remote endpoint received the reference. The referenceDelivered method will be 

invoked. 

• STATE_TERMINATED if the remote endpoint did not receive the reference. The referenceDeliveryFailed 

method will be invoked. If the reference was sent with the implicitSubscription argument set to false, the 

referenceDelivered method will be invoked. 

STATE_REFERRING 

In this state the Reference has been received but not necessarily accepted by the remote endpoint. The status of 

the reference can be monitored by inspecting the message body in notifications that are received in the 

referenceNotify callback on the ReferenceListener. 


• STATE_TERMINATED if the reference is considered as terminated. The referenceTerminated method will 

be invoked. 

STATE_TERMINATED 

In this state the Reference has been rejected or terminated and any further actions on the Reference object are 

invalid. 

Remote endpoint 


An incoming reference request always starts in STATE_PROCEEDING. 


• STATE_REFERRING if accept is called on the reference. 

• STATE_TERMINATED if reject is called on the reference. 


The remote endpoint has accepted the reference and is now responsible to contact the third party with the 

reference method provided with the getReferMethod. The remote endpoint should also connect the reference to 

the IMS engine so that notifications can be sent to the endpoint that issued the reference. 


• STATE_TERMINATED if the remote endpoint contacted the third party or if the reference has failed. The 

referenceTerminated method will be invoked 


The Reference is considered as terminated and any further actions on the Reference object are invalid. 



Example usage of Reference 

The scenario below illustrates how Reference can be used to make a reference to a third party user, in this case 

Charlotte. Figure 2 shows the interaction between Alice, Bob and Charlotte. Alice's application is an IMS 

Application running on her device, for instance a mobile phone. 

Create a Reference 

In this example code, Alice sends an INVITE refer method to Bob referring to Charlotte, and requests that Bob 

sends reference notifications in return. 

try { 

Reference ref = service.createReference("sip:alice@home.net", 

"sip:bob@home.net", 

"sip:charlotte@home.net", 

"INVITE"); 

ref.setListener(this) 

ref.refer(true); 



} 

public void referenceDelivered(Reference reference) { 

// if the reference was delivered 

} 

public void referenceDeliveryFailed(Reference reference) { 

// if the reference was not delivered 

} 

public void referenceNotify(Reference reference, Message notify){ 

// check progress of the reference 

} 

public void referenceTerminated(Reference reference) { 

// the reference is terminated 

} 

Accept a Reference 

Bob receives a reference request and decides to accept it. 

public void referenceReceived(CoreService service, Reference reference) { 

String referToUserId = reference.getReferToUserId(); 

String referMethod = reference.getReferMethod(); 

// notify the application of the reference 

... 

reference.accept(); 

// assume referMethod == "INVITE" 

mySession = service.createSession(null, referToUserId); 

// Interpret the INVITE refer method as a request to initiate 

// a session with the third party 

reference.connectReferMethod((ServiceMethod)mySession); 

// start the reference with the third party 


} 

In the call below, the referTo URI is a local TEL URI: 

try { 

Reference ref = 

service.createReference("Alice ", 

"Bob ", 

"Carol ", 

"INVITE"); 




The referTo URI is a http URI: 

try { 



"Bob ", 

"http://example.com", 

null); 


The referTo URI is a cid:. This is for example used in multiple-refer [RFC5368] to conference servers. 

try { 



"Bob ", 

"", 

null); 

// Make sure that the remote can process multiple refer 

ref.getNextRequest().addHeader("require", "multiple-refer"); 

// No notifications wanted 

ref.refer(false); 

Figure 2: A simplified picture of the interaction between Alice, Bob and Charlotte with reference.refer(true). 

referenceNotify listener is not invoked if refer argument is set to false. 

See Also: 

CoreService.createReference(String, String, String, String), Session.createReference(String, 

String), CoreServiceListener, ReferenceListener 



Field Summary 

int STATE_INITIATED 

This state specifies that the Reference is created but not started. 

int STATE_PROCEEDING 

This state specifies that the Reference has been started. 

int STATE_REFERRING 

This state specifies that the Reference has been accepted and that the remote endpoint is 

referring to the third party. 

int STATE_TERMINATED 

This state specifies that the Reference has been rejected or terminated. 

Page 

87 

87 

88 

88 


void accept() 

Accepts an incoming reference request. 

void connectReferMethod(ServiceMethod serviceMethod) 

This method connects a service method with this reference and allows the IMS engine to 

send notifications regarding this reference to the endpoint that initiated this reference. 

String getReferMethod() 

Returns the reference method to be used. 

String getReferToUserId() 

Returns the URI to refer to, optionally with a display name. 

String getReplaces() 

Returns the value of the replaces parameter of the Refer-To header. 


Returns the current state of this Reference. 

void refer(boolean implicitSubscription) 

Sends the reference request to the remote endpoint. 

void reject() 

Rejects an incoming reference request. 

void setListener(ReferenceListener listener) 

Sets a listener for this Reference, replacing any previous ReferenceListener. 

void setReplaces(String sessionId) 

Sets the replaces parameter of the Refer-To header to the given identity. 

Page 

89 

90 

89 

88 

89 

90 

88 

90 

90 

89 



Field Detail 


public static final int STATE_INITIATED 

This state specifies that the Reference is created but not started. 


public static final int STATE_PROCEEDING 



This state specifies that the Reference has been started. 


public static final int STATE_REFERRING 

This state specifies that the Reference has been accepted and that the remote endpoint is referring to the 

third party. 


public static final int STATE_TERMINATED 

This state specifies that the Reference has been rejected or terminated. 

Method Detail 

refer 

void refer(boolean implicitSubscription) 


Sends the reference request to the remote endpoint. 

The Reference will transit to STATE_PROCEEDING after calling this method. 

The implicitSubscription argument indicates if this request should generate a implicit subscription. If 

true the Reference transits to STATE_REFERRING and the sender gets reports on the progress of the 

reference processing at the remote. If false, the sender will only know if the request was received. The 

Reference transits to STATE_TERMINATED when the delivery report is received. 

Parameters: 

implicitSubscription - true if this Reference should generate an implicit subscription, false 

otherwise 

Throws: 


IllegalStateException - if the Reference is not in STATE_INITIATED 

See Also: 

ReferenceListener.referenceDelivered(Reference) 

getReferToUserId 

String getReferToUserId() 

Returns the URI to refer to, optionally with a display name. 

Returns: 

the URI, optionally with a display name. 



getReferMethod 

String getReferMethod() 

Returns the reference method to be used. 

Returns: 

the reference method 

setReplaces 

void setReplaces(String sessionId) 

Sets the replaces parameter of the Refer-To header to the given identity. The application shall use the 

value of SessionDescriptor.getSessionId() 

Parameters: 

sessionId - the identity of the Session to replace 

Throws: 

IllegalStateException - if the Reference is not in STATE_INITIATED 

IllegalArgumentException - if the sessionId argument does not designate an established 

session, is null or an empty string 

See Also: 

getReplaces(), SessionDescriptor.getSessionId() 

getReplaces 

String getReplaces() 

Returns the value of the replaces parameter of the Refer-To header. 

Returns: 

the value or null the value is not available 

See Also: 

setReplaces(String) 

accept 

void accept() 


Accepts an incoming reference request. 

The Reference will transit to STATE_REFERRING after calling this method. 

Note: After calling this method the application has the responsibility to establish a connection to the third 

party depending on the refer method. 

Throws: 


IllegalStateException - if the Reference is not in STATE_PROCEEDING 



reject 

void reject() 


Rejects an incoming reference request. 

The Reference will transit to STATE_TERMINATED after calling this method. 

Throws: 


IllegalStateException - if the Reference is not in STATE_PROCEEDING 

connectReferMethod 

void connectReferMethod(ServiceMethod serviceMethod) 

This method connects a service method with this reference and allows the IMS engine to send notifications 

regarding this reference to the endpoint that initiated this reference. 

Parameters: 

serviceMethod - the ServiceMethod to connect 

Throws: 

IllegalStateException - if the Reference is not in STATE_REFERRING 

IllegalArgumentException - if the serviceMethod argument is null 

getState 


Returns the current state of this Reference. 

Returns: 

the current state of this Reference 

setListener 

void setListener(ReferenceListener listener) 

Sets a listener for this Reference, replacing any previous ReferenceListener. A null value is allowed 

and has the effect of removing any existing listener. 

Parameters: 



Interface ReferenceListener 



public interface ReferenceListener 

This listener type is used to notify an application about events regarding a Reference. 

See Also: 

Reference.setListener(ReferenceListener) 


void referenceDelivered(Reference reference) 

Notifies the application that the reference was successfully delivered. 

void referenceDeliveryFailed(Reference reference) 

Notifies the application that the reference was not successfully delivered. 

void referenceNotify(Reference reference, Message notify) 

Notifies the application with status reports regarding the Reference. 

void referenceTerminated(Reference reference) 

Notifies the application that a reference has been terminated. 

Page 

91 

91 

92 

92 

Method Detail 

referenceDelivered 

void referenceDelivered(Reference reference) 

Notifies the application that the reference was successfully delivered. 

This method is invoked at the endpoint that sent the reference request. 

The Reference has transited to STATE_REFERRING or STATE_TERMINATED depending on if an implicit 

subscription was requested or not. 

Parameters: 

reference - the concerned Reference 

See Also: 

Reference.refer(boolean) 

referenceDeliveryFailed 

void referenceDeliveryFailed(Reference reference) 

Notifies the application that the reference was not successfully delivered. 


The Reference has transited to STATE_TERMINATED. 

Parameters: 




referenceTerminated 

void referenceTerminated(Reference reference) 

Notifies the application that a reference has been terminated. 

This method is invoked at the endpoint that sent the reference request and at the endpoint that received 

the reference request. 

The Reference has transited to STATE_TERMINATED. 

Parameters: 


referenceNotify 

void referenceNotify(Reference reference, 


Notifies the application with status reports regarding the Reference. 


Parameters: 


notify - a status report regarding the Reference 


Interface ServiceMethod 




Capabilities, PageMessage, Publication, Reference, Session, Subscription 

public interface ServiceMethod 

The ServiceMethod interface provides methods to manipulate the next outgoing request message and to inspect 

previously sent request and response messages. The headers and body parts that are set will be transmitted in the 

next message that is triggered by an interface method, see code example below: 

Session mySession; 

Message myMessage; 

mySession = coreService.createSession(null, "sip:bob@home.net"); 

myMessage = mySession.getNextRequest(); 

myMessage.addHeader("P-ImageIncluded", "yes"); 


In this code example, mySession.start is the triggering interface method that sends a session invitation with a 

header "P-ImageIncluded" that is set to "yes". 

The latest transaction is saved for each interface method that triggers messages to be sent, see Message interface 

for available message identifiers. 

Service Methods 

Instances of service methods can be created by using factory methods in the CoreService interface. To learn 

more about using the different service methods please refer to the related interfaces, see list below: 

• Capabilities 

• PageMessage 

• Publication 

• Session 

• Subscription 

• Reference 

In general the methods in the subinterfaces should supply all the functionality an application needs for each 

respective method. Should this not be enough this superinterface gives some additional and powerful control such 

as manipulating headers and body. 

Service Method Transactions 

The simplest form of communication in the IMS consists of two messages, an initial request sent to a remote 

endpoint and then an answer message or response. This interaction is commonly known as a transaction. Figure 1, 

shows an example transaction. 



Figure 1: A simple transaction. 

The communication can grow in complexity and include several transactions. An example could be the session 

invitation procedure with resource reservations, see figure 2 below. 

Figure 2: The session invite procedure. 

A transaction is defined by one request and its related responses. There can be more than one response for each 

request and there can be transactions with no responses at all. All messages in the figure above are given a 

number to clarify which transaction the different messages belong to. 

Example of how to access headers and body parts 

In this example, an image is attached as a separate body part and it is indicated by setting a "P-ImageIncluded" 

header in the initial INVITE method on the originating side. 

On the terminating side, the application retrieves the image and confirms this by setting the header in the 200 Ok 

response message. 

Originating endpoint 

Session mySession = myService.createSession(...); 

... 

Message myMessage = mySession.getNextRequest(); 

myMessage.addHeader("P-ImageIncluded", "yes"); 

MessageBodyPart messagePart = myMessage.createBodyPart(); 



messagePart.setHeader("Content-Type", "image/jpeg"); 

OutputStream os = messagePart.openContentOutputStream(); 

os.write(imageData); 

os.flush(); 

os.close(); 


Terminating endpoint 

public void sessionInvitationReceived(CoreService service, Session session) { 

} 

Message request = session.getPreviousRequest(Message.SESSION_START); 

Message resp; 

if ("yes".equals(mess.getHeaders("P-ImageIncluded")[0])) { 

MessageBodyPart[] parts = mess.getBodyParts(); 

for (int i = 0; i < parts.length; i++) { 

if ("image/jpeg".equals(parts[i].getHeader("Content-Type"))) { 

InputStream is = parts[i].openContentInputStream(); 

byte[] data = new byte[1024]; 

// read content 

while ((is.read(data)) != -1) { 

... 

} 

} 

} 

} 

// Add header to accept response to session invitation 

resp = session.getNextResponse(); 

resp.addHeader("P-ImageIncluded", "yes"); 

session.accept(); 


Message getNextRequest() 

This method returns a handle to the next outgoing request Message within this 

ServiceMethod to be manipulated by the local endpoint. 

Message getNextResponse() 

This method returns a handle to the next outgoing response Message within this 

ServiceMethod. 

Message getPreviousRequest(int method) 

This method enables the user to inspect a previously sent or received request message. 

Message[] getPreviousResponses(int method) 

This method enables the user to inspect previously sent or received response messages. 

String[] getRemoteUserId() 

Returns the remote user identities of this ServiceMethod. 

Page 

96 

96 

96 

96 

95 

Method Detail 

getRemoteUserId 

String[] getRemoteUserId() 

Returns the remote user identities of this ServiceMethod. 

Returns: 

the remote user identity or null if the remote user identity could not be retrieved 



getNextRequest 

Message getNextRequest() 

This method returns a handle to the next outgoing request Message within this ServiceMethod to be 

manipulated by the local endpoint. 

Returns: 

the next outgoing request Message created for this ServiceMethod 

getPreviousRequest 

Message getPreviousRequest(int method) 

This method enables the user to inspect a previously sent or received request message. It is only possible 

to inspect the last request of each interface method identifier. This method will return null if the interface 

method identifier has not been sent/received. 

See Message for valid interface method identifiers to retrieve. 

Parameters: 

method - the interface method identifier 

Returns: 

the request Message 

Throws: 

IllegalArgumentException - if the method argument is not a valid identifier 

getPreviousResponses 

Message[] getPreviousResponses(int method) 

This method enables the user to inspect previously sent or received response messages. It is only possible 

to inspect the response(s) for the last request of each interface method identifier. This method will return 

null if the interface method identifier has not been sent/received. 

See Message for valid interface method identifiers to retrieve. 

Parameters: 

method - the interface method identifier 

Returns: 

an array containing all responses associated to the method 

Throws: 

IllegalArgumentException - if the method argument is not a valid identifier 

getNextResponse 

Message getNextResponse() 

This method returns a handle to the next outgoing response Message within this ServiceMethod. It is only 

possible to manipulate the responses that are due to an application triggering action. This happens when 

the application takes an action in response to a callback: Session.accept and Session.reject from a 

session invitation or update. Otherwise null will be returned. 



Returns: 

the next outgoing response Message created for this ServiceMethod or null 


Interface Session 




ServiceMethod 

public interface Session 


The Session is a representation of a media exchange between two IMS endpoints. A Session can be created 

either locally through calling CoreService.createSession, or by a remote user, in which case the session will be 

passed as a parameter to CoreServiceListener.sessionInvitationReceived. 

A Session is able to carry media of the type Media. Media objects represent a media connection and not the 

media/content itself. Note that to be able to start a Session it MUST include at least one Media component, or an 

ImsException will be thrown. 

The IMS media connections are negotiated through an offer/answer model. The first offer/answer negotiation may 

take place during session establishment. However, new offers may be sent by any of the session's parties at any 

time. This is shown below in the session renegotiation procedure. 

Session Life Cycle 

A Session has eight states: STATE_INITIATED, STATE_NEGOTIATING, STATE_ESTABLISHING, STATE_ESTABLISHED, 

STATE_RENEGOTIATING, STATE_REESTABLISHING, STATE_TERMINATING and STATE_TERMINATED. The purpose of 

the life cycle states is to ensure that the handling of the session is kept synchronized between the local endpoint 

and the remote endpoint. The session life cycle also determines which actions are valid and which information is 

accessible in certain states. 

Below follows a description of two different scenarios: Session Establishment and Session Renegotiation. The 

scenarios are explained from two perspectives: the Mobile Originated-perspective which represents the initiator of 

an action. The counterpart is the Mobile Terminated-perspective representing the remote side of the session which 

will receive events of the initiators actions. In general terms an action at one side will generate a call to a listener 

method on the remote side of the session. 

Session Establishment 

This section describes how a session invitation is sent to a remote endpoint and the actions needed to respond to 

an invitation. 

Mobile Originated Session Establishment 



Figure 1: The mobile originated session establishment states 


When a Session is created through a call to CoreService.createSession, it will enter STATE_INITIATED. After 

the Session is created, media can be added by calling Session.createMedia 

A Session transits to: 

• STATE_NEGOTIATING when start is called on the Session. 

• STATE_TERMINATING when terminate is called on the Session. 

STATE_NEGOTIATING 

Once this state is entered the communication with the remote endpoint starts and a session invitation with the first 

media offer is sent. 

Within STATE_NEGOTIATING the listener method sessionAlerting will be called when the remote endpoint has 

received the session invitation. 




• STATE_ESTABLISHED if the remote endpoint accepts the session invitation. The sessionStarted callback 

will then be invoked. 

• STATE_TERMINATING if the local endpoint invokes terminate. 

• STATE_TERMINATED if the remote endpoint rejects the session invitation. The sessionStartFailed 

callback will then be invoked. 

Mobile Terminated Session Establishment 

Figure 2: The mobile terminated session establishment states 




STATE_INITIATED is irrelevant to a receiving terminal because as soon as it is notified of an invitation the session 

is already in STATE_NEGOTIATING. 


When a session invitation reaches the terminating application it will be notified by a call to 

sessionInvitationReceived and the Session will reside in STATE_NEGOTIATING. 


• STATE_ESTABLISHING if accept is called on the Session. 

• STATE_TERMINATED if reject is called on the Session or when the callback sessionStartFailed is 

invoked. 

• STATE_TERMINATING if terminate is called on the session. 

STATE_ESTABLISHING 

In this state accept has been called and the Session is about to be established at both endpoints. A Session 

transits to: 

• STATE_ESTABLISHED when the callback sessionStarted is invoked. 

• STATE_TERMINATED when the callback sessionStartFailed is invoked. 


Session Renegotiation 

This section describes how a session renegotiation is handled by the local and remote endpoints. A renegotiation 

of the session may include modifications and removal of current media as well as adding new media. The 

renegotiation can be initiated by either endpoint. In Figure 1 and Figure 2 the session update is initiated by the 

same endpoint that initiated the session. 

Mobile Originated Session Renegotiation 

STATE_ESTABLISHED 

In this state the endpoint can modify the session as well as adding new media. An incoming update from the 

remote endpoint will discard all changes that the local endpoint has made to the session. 

• STATE_RENEGOTIATING when the callback sessionUpdateRecieved is invoked. 

• STATE_TERMINATED when the callback sessionTerminated is invoked. 


STATE_RENEGOTIATING 

A Session assumes STATE_RENEGOTIATING through a call to update. Incoming session updates from the remote 

endpoint will be discarded in this state. 

A Session transits back to STATE_ESTABLISHED when the listener method: 

• sessionUpdated is called, meaning that the remote endpoint accepted the new session offer. 

• sessionUpdateFailed is called, but here meaning that the remote endpoint rejected the update and the 

session keeps its previous settings. 

Mobile Terminated Session Renegotiation 


If the remote endpoint has offered changes to the session, the state will transit to STATE_RENEGOTIATING and the 

session will be notified with a call to the sessionUpdateReceived in the SessionListener interface. 




• STATE_REESTABLISHING if the accept method of the Session is called, thus the media offer is accepted. 

• STATE_ESTABLISHED if the reject method is called but in this case the session will keep its old settings. 



STATE_REESTABLISHING 

In this state accept has been called and the Session is about to be updated at both endpoints. A Session transits 

to: 

• STATE_ESTABLISHED when the callback sessionUpdated is invoked. 



Session Termination 

The terminate method can be called from both endpoints on the Session and thereby cancel the ongoing session 

establishment or terminate a Session in progress. 

STATE_TERMINATING 

A Session enters STATE_TERMINATING when the terminate method has been called on a Session. 


• STATE_TERMINATED when the remote endpoint has acknowledged the terminate request. The 

sessionTerminated callback will then be invoked. 

An incoming terminate request from the remote endpoint is notified with the sessionTerminated callback. 

Field Summary 

int STATE_ESTABLISHED 

This state specifies that the Session is established. 

int STATE_ESTABLISHING 

This state specifies that the Session is accepted by the mobile terminated endpoint. 

int STATE_INITIATED 

This state specifies that the Session is created but not started. 

int STATE_NEGOTIATING 

This state specifies that the Session establishment has been started. 

int STATE_REESTABLISHING 

This state specifies that the Session update is accepted by the mobile terminated 

endpoint. 

int STATE_RENEGOTIATING 

This state specifies that the Session is negotiating updates to the session. 

int STATE_TERMINATED 

This state specifies that the Session has been terminated. 

int STATE_TERMINATING 

This state specifies that an established Session is being terminated by the local endpoint. 

int STATUSCODE_433_ANONYMITY_DISALLOWED 

Identifier for the SIP status code "433 - Anonymity Disallowed". 

Page 

104 

104 

104 

104 

104 

104 

105 

105 

105 



int STATUSCODE_480_TEMPORARILY_UNAVAILABLE 

Identifier for the SIP status code "480 - Temporarily Unavailable". 

int STATUSCODE_486_BUSY_HERE 

Identifier for the SIP status code "486 - Busy Here". 

int STATUSCODE_488_NOT_ACCEPTABLE_HERE 

Identifier for the SIP status code "488 - Not Acceptable Here". 

int STATUSCODE_600_BUSY_EVERYWHERE 

Identifier for the SIP status code "600 - Busy Everywhere". 

int STATUSCODE_603_DECLINE 

Identifier for the SIP status code "603 - Decline". 

105 

105 

105 

105 

105 


void accept() 

This method can be used to accept a session invitation or a session update 

depending on the context. 

Capabilities createCapabilities() 

Creates a Capabilities with the remote endpoint. 

Media createMedia(String type, int direction) 

Creates a Media object with a media type name and adds it to the Session. 

Reference createReference(String referTo, String referMethod) 

This method is used for referring the remote endpoint to a third party user or 

service. 

Media[] getMedia() 

Returns the Media that are part of this Session . 

SessionDescriptor getSessionDescriptor() 

Returns the session descriptor associated with this Session. 


Returns the current state of this Session. 

boolean hasPendingUpdate() 

This method checks if there are changes in this Session that have not been 

negotiated. 

void reject() 

This method can be used to reject a session invitation or a session update 

depending on the context. 

void reject(int statusCode) 

This method can be used to reject a session invitation or a session update 

depending on the context with a specific SIP status code. 

void rejectWithDiversion(String alternativeUserAddress) 

This method can be used to reject a session invitation with the SIP status code "302 

- Moved Temporarily", along with an alternative contact user address. 

void removeMedia(Media media) 

void restore() 

Removes a Media from the Session. 

This method removes all updates that have been made to this Session and to 

medias that are part of this Session that have not been negotiated. 

void setListener(SessionListener listener) 

Sets a listener for this Session, replacing any previous SessionListener. 

void start() 

Starts a session. 

void terminate() 

Terminate or cancel a session. 

Page 

108 

108 

107 

108 

108 

110 

107 

110 

109 

109 

109 

107 

110 

106 

106 

106 



void update() 

Synchronizes the session modifications that an application has done with the 

remote endpoint. 

106 



Field Detail 


public static final int STATE_INITIATED 

This state specifies that the Session is created but not started. 


public static final int STATE_NEGOTIATING 

This state specifies that the Session establishment has been started. 

STATE_ESTABLISHING 

public static final int STATE_ESTABLISHING 

This state specifies that the Session is accepted by the mobile terminated endpoint. 

STATE_ESTABLISHED 

public static final int STATE_ESTABLISHED 

This state specifies that the Session is established. 


public static final int STATE_RENEGOTIATING 

This state specifies that the Session is negotiating updates to the session. 

STATE_REESTABLISHING 

public static final int STATE_REESTABLISHING 

This state specifies that the Session update is accepted by the mobile terminated endpoint. 



STATE_TERMINATING 

public static final int STATE_TERMINATING 

This state specifies that an established Session is being terminated by the local endpoint. 


public static final int STATE_TERMINATED 

This state specifies that the Session has been terminated. 

STATUSCODE_433_ANONYMITY_DISALLOWED 

public static final int STATUSCODE_433_ANONYMITY_DISALLOWED 

Identifier for the SIP status code "433 - Anonymity Disallowed". 

STATUSCODE_480_TEMPORARILY_UNAVAILABLE 

public static final int STATUSCODE_480_TEMPORARILY_UNAVAILABLE 

Identifier for the SIP status code "480 - Temporarily Unavailable". 

STATUSCODE_486_BUSY_HERE 

public static final int STATUSCODE_486_BUSY_HERE 

Identifier for the SIP status code "486 - Busy Here". 

STATUSCODE_488_NOT_ACCEPTABLE_HERE 

public static final int STATUSCODE_488_NOT_ACCEPTABLE_HERE 

Identifier for the SIP status code "488 - Not Acceptable Here". 

STATUSCODE_600_BUSY_EVERYWHERE 

public static final int STATUSCODE_600_BUSY_EVERYWHERE 

Identifier for the SIP status code "600 - Busy Everywhere". 

STATUSCODE_603_DECLINE 

public static final int STATUSCODE_603_DECLINE 

Identifier for the SIP status code "603 - Decline". 



Method Detail 

setListener 

void setListener(SessionListener listener) 

Sets a listener for this Session, replacing any previous SessionListener. A null reference is allowed and 

has the effect of removing any existing listener. 

Parameters: 

listener - the listener to set 

update 

void update() 


Synchronizes the session modifications that an application has done with the remote endpoint. 

Modifications include adding of media, removal of media, and change of existing media (e.g. directionality). 

The Session will transit to STATE_RENEGOTIATING after calling this method. 

Throws: 

ImsException - if a Media in the Session is not initiated correctly or if there are no Media in the 

Session 

IllegalStateException - if the hasPendingUpdate method returns false, meaning that there are 

no updates to be made to the session, 

if the Session is not in STATE_ESTABLISHED 

start 

void start() 


Starts a session. When this method is called the remote endpoint is invited to the session. All media MUST 

be initialized (see rules for the respective media type) for the session to start. 

The Session will transit to STATE_NEGOTIATING after calling this method. 

Throws: 

ImsException - if a Media in the Session is not initialized correctly or if there are no Media in the 

Session 

IllegalStateException - if the Session is not in STATE_INITIATED 

terminate 

void terminate() 

Terminate or cancel a session. A session that has been started should always be terminated using this 

method. 

The Session will transit to STATE_TERMINATING. 

If the Session is STATE_TERMINATING or STATE_TERMINATED this method will not do anything. 



If the Session is STATE_INITIATED the Session will transit directly to STATE_TERMINATED, the 

sessionTerminated callback will not be invoked. 

getState 


Returns the current state of this Session. 

Returns: 

the current state of this Session 

createMedia 

Media createMedia(String type, 

int direction) 


Creates a Media object with a media type name and adds it to the Session. The following type names are 

recognized in this specification: BasicUnreliableMedia, BasicReliableMedia, FramedMedia and 

StreamMedia. 

If a Media is added to an established Session, the application has the responsibility to call update on the 

Session. 

Parameters: 

type - a Media type name 

direction - the direction of the Media flow 

Returns: 

a new Media implementing the type name interface 

Throws: 

ImsException - if the type could not be created 

IllegalArgumentException - if the direction argument is invalid 

IllegalStateException - if the Session is not in STATE_ESTABLISHED, STATE_INITIATED 

See Also: 

Media 

removeMedia 

void removeMedia(Media media) 

Removes a Media from the Session. 

If a Media is removed from an established Session, the application has the responsibility to call update on 

the Session. 

Parameters: 

media - the Media to remove from the Session 

Throws: 

IllegalArgumentException - if the Media does not exist in the Session or null 

IllegalStateException - if the Session is not in STATE_ESTABLISHED, STATE_INITIATED 



getMedia 

Media[] getMedia() 

Returns the Media that are part of this Session . An empty array will be returned if there are no Media in 

the Session. 

Returns: 

an array of all Media in the Session 

Throws: 

IllegalStateException - if the Session is in STATE_TERMINATED 

accept 

void accept() 

This method can be used to accept a session invitation or a session update depending on the context. 

• It can be used to accept a session invitation in STATE_NEGOTIATING if the remote endpoint has 

initiated the session. The Session will transit to STATE_ESTABLISHING. 

• It can be used to accept a session update in STATE_RENEGOTIATING if the remote endpoint has 

initiated the session update. The Session will transit to STATE_REESTABLISHING. 

Throws: 

IllegalStateException - if the Session is not in STATE_NEGOTIATING or STATE_RENEGOTIATING 

createCapabilities 

Capabilities createCapabilities() 

Creates a Capabilities with the remote endpoint. 

Returns: 

a new Capabilities 

Throws: 

ImsException - if the Capabilities could not be created 

IllegalStateException - if the Session is not in STATE_ESTABLISHED 

createReference 

Reference createReference(String referTo, 

String referMethod) 

This method is used for referring the remote endpoint to a third party user or service. 

Parameters: 

referTo - the URI with an optional display name to refer to. It can be any URI, not just a user id 

referMethod - the reference method to be used by the reference request, e.g. "INVITE", "BYE" or 

null for an unspecified refer method. 

Returns: 

a new Reference 

Throws: 

IllegalArgumentException - if the referTo argument is null, 

if the referMethod argument is not recognized by the device 



ImsException - if the Reference could not be created 


reject 

void reject() 

This method can be used to reject a session invitation or a session update depending on the context. 

When calling this method the IMS Engine will respond with an appropriate SIP status code. 

• It can be used to reject a session invitation in STATE_NEGOTIATING if the remote endpoint has 

initiated the session. The Session will transit to STATE_TERMINATED . 

• It can be used to reject a session update in STATE_RENEGOTIATING if the remote endpoint has 

initiated the session update. The Session will transit to STATE_ESTABLISHED and the update is 

discarded. 

Throws: 

IllegalStateException - if the Session is not in STATE_NEGOTIATING or STATE_RENEGOTIATING 

reject 

void reject(int statusCode) 

This method can be used to reject a session invitation or a session update depending on the context with a 

specific SIP status code. 

The following status codes are valid: 

STATUSCODE_433_ANONYMITY_DISALLOWED, STATUSCODE_480_TEMPORARILY_UNAVAILABLE, 

STATUSCODE_488_NOT_ACCEPABLE_HERE, STATUSCODE_600_BUSY_EVERYWHERE and 

STATUSCODE_603_DECLINE. 

• It can be used to reject a session invitation in STATE_NEGOTIATING if the remote endpoint 

has initiated the session. The Session will transit to STATE_TERMINATED . 

Parameters: 

statusCode - the status code 

Throws: 

IllegalArgumentException - if the statusCode argument is not valid identifier 

IllegalStateException - if the Session is not in STATE_NEGOTIATING 

rejectWithDiversion 

void rejectWithDiversion(String alternativeUserAddress) 

This method can be used to reject a session invitation with the SIP status code "302 - Moved Temporarily", 

along with an alternative contact user address. 

• It can be used to reject a session invitation in STATE_NEGOTIATING if the remote endpoint has 

initiated the session. The Session will transit to STATE_TERMINATED . 

Parameters: 

alternativeUserAddress - the alternative SIP or TEL URI were the user wants to be contacted 

Throws: 

IllegalStateException - if the Session is not in STATE_NEGOTIATING 

IllegalArgumentException - if the syntax of the alternativeUserAddress argument is invalid 



getSessionDescriptor 

SessionDescriptor getSessionDescriptor() 

Returns the session descriptor associated with this Session. 

Returns: 

the session descriptor 

hasPendingUpdate 

boolean hasPendingUpdate() 

This method checks if there are changes in this Session that have not been negotiated. 

Returns: 

true if there is a pending update, false otherwise 

restore 

void restore() 

This method removes all updates that have been made to this Session and to medias that are part of this 

Session that have not been negotiated. 

Throws: 



Interface SessionDescriptor 



public interface SessionDescriptor 

The Session Description Protocol (SDP) [RFC4566] is used to convey information about media streams in a 

session such that the endpoints can connect and participate. SDP standardizes a textual format for such 

information in the application/sdp media type. A content of that type is generally referred to as "an SDP", or "the 

SDP" when the reference to the particular content is unambiguous. 

The endpoints in a session, exchange SDPs according to the SDP Offer/Answer model [RFC3264] in the SIP 

signalling. The IMS Engine manages this process at all times. For a session at a particular state, and at an 

endpoint, there is a pair of SDPs: an "incoming SDP", part of a SIP message received from the remote, and an 

"outgoing SDP", that is to be put in a SIP message to be sent to the remote. Note that not all SIP messages carry 

SDP bodies. 

The SessionDescriptor is an interface to the session-level part of this SDP pair (for the media-level part, see 

MediaDescriptor). The getters read from the last incoming SDP. The setters apply to all outgoing SDPs in the 

current session, beginning with the one to be sent next. Note that using the interface setters does not in itself 

trigger the IMS engine to send the SDP in a SIP message. If there is a point in the session lifetime where the 

modifications should cease, the application is responsible to use the setters again, and make sure the SDP is sent. 

On the originating endpoint, it is most useful for the application to use the setters when the session is in the initiated 

state. The changes will then be in effect from the start of the session. It is not possible to use the getters since 

there is no incoming SDP at the first state. In an established session, the originating endpoint for a session update 

may read and change the SDP before applying the update. 

On the terminating endpoint, the application can read the incoming SDP but not set an outgoing SDP in the 

CoreService.SessionInvitationReceived callback. The reason is that all SDP carrying messages have already 

been exchanged at the time of callback. If the terminating side wants to add attributes it has to do so when the 

session is established, and trigger a session update. 

There are several places in the call flow at session setup and session update where the application have no 

opportunity to influence the negotiation, for example right after receiving the INVITE at the terminating endpoint. In 

this case, the IMS engine copies all application-defined SDP attributes from the offer into the answer, and from the 

answer into subsequent offers until the session is established or updated. 

To use the interface in a meaningful way, a thorough understanding of the SDP protocol and its use in IMS and SIP 

is assumed. 

For a session with a streaming media object of audio and video type, there could be an SDP that looks something 

like: 

v=0 

o=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com 

s= 

c=IN IP4 host.atlanta.example.com 

t=0 0 

m=audio 49170 RTP/AVP 0 8 97 

a=rtpmap:0 PCMU/8000 

a=rtpmap:8 PCMA/8000 

a=rtpmap:97 iLBC/8000 

m=video 51372 RTP/AVP 31 32 

a=rtpmap:31 H261/90000 

a=rtpmap:32 MPV/90000 

The session-level part includes the bold lines. The application can get, and set some SDP lines that are not 

reserved for the IMS engine. Attributes can be get, set and removed freely except reserved. The following attributes 

are classified as reserved and can not be modified using the SessionDescriptor interface: charset, 

charset:iso8895-1, group, maxprate, ice-lite, ice-mismatch, ice-options, ice-pwd, ice-ufrag, inactive, sendonly, 

recvonly, sendrecv, csup, creq, acap and tcap. 



See Also: 

MediaDescriptor 


void addAttribute(String attribute) 

Adds an attribute (a=) to the Session. 

String[] getAttributes() 

Returns all attributes (the a= lines) for the session. 

String getProtocolVersion() 

Returns the version (v=) of the SDP. 

String getSessionId() 

Returns a unique identifier (o=) for the session. 

String getSessionInfo() 

Returns textual information (i=) about the session. 

String getSessionName() 

Returns the textual session name (s=). 

void removeAttribute(String attribute) 

Removes an attribute (a=) from the session. 

void setSessionInfo(String info) 

Sets the textual information (i=) about the session. 

void setSessionName(String name) 

Sets the name of the session (s=). 

Page 

114 

114 

112 

112 

113 

113 

114 

113 

113 

Method Detail 

getProtocolVersion 

String getProtocolVersion() 

Returns the version (v=) of the SDP. 

See [RFC4566], chapter 5.1. for more information. 

Returns: 

the protocol version or null if the protocol version could not be retrieved 

getSessionId 

String getSessionId() 

Returns a unique identifier (o=) for the session. 


Returns: 

the Session identifier or null if the session identifier could not be retrieved 



getSessionName 

String getSessionName() 

Returns the textual session name (s=). 


Returns: 

the Session name or null if the session name is not set 

See Also: 

setSessionName(String) 

setSessionName 

void setSessionName(String name) 

Sets the name of the session (s=). 

Parameters: 

name - the session name 

Throws: 


IllegalArgumentException - if the name argument is null 

See Also: 

getSessionName() 

getSessionInfo 

String getSessionInfo() 

Returns textual information (i=) about the session. 


Returns: 

session information or null if the session information is not set 

See Also: 

setSessionInfo(String) 

setSessionInfo 

void setSessionInfo(String info) 

Sets the textual information (i=) about the session. 

Parameters: 

info - session information 

Throws: 


IllegalArgumentException - if the info argument is null 

See Also: 

getSessionInfo() 



removeAttribute 


Removes an attribute (a=) from the session. 

The example below removes the "synced" attribute: 

SessionDescriptor desc = session.getSessionDescriptor(); 

desc.removeAttribute("synced"); 

Parameters: 

attribute - the attribute to remove 

Throws: 

IllegalArgumentException - if the attribute argument is null, 

if the attribute does not exist in the Session, 

if the attribute is reserved for the IMS engine 

IllegalStateException - if the Session is not in STATE_INITIATED or STATE_ESTABLISHED state 

addAttribute 


Adds an attribute (a=) to the Session. Adding attributes that the IMS engine has reserved, such as 

"sendonly", "recvonly", "sendrecv", leads to IllegalArgumentException. 

Example: 

SessionDescriptor desc = session.getSessionDescriptor(); 

desc.addAttribute("synced"); 

The resulting attribute line will be: 

a=synced 

Parameters: 

attribute - the attribute to add 

Throws: 

IllegalArgumentException - if the attribute argument is null or if the syntax of the attribute 

argument is invalid, 

if the attribute already exists in the Session, 

if the attribute is reserved for the IMS engine 

IllegalStateException - if the Session is not in STATE_INITIATED or STATE_ESTABLISHED state 

getAttributes 


Returns all attributes (the a= lines) for the session. If there are no attributes, an empty string array will be 

returned. 

Returns: 

a string array containing the attributes 


Interface SessionListener 



public interface SessionListener 

A listener type for receiving notification on session events. When an event is generated for a Session the 

application is notified by having one of the methods called on the SessionListener. 

See Also: 

Session.setListener(SessionListener) 


void sessionAlerting(Session session) 

Notifies the application that the remote part's terminal is alerting the user of this session 

invitation. 

void sessionReferenceReceived(Session session, Reference reference) 

Notifies the application that a reference request has been received from a remote endpoint. 

void sessionStarted(Session session) 

Notifies the application that the session has been established. 

void sessionStartFailed(Session session) 

Notifies the application that the session could not be established. 

void sessionTerminated(Session session) 

Notifies the application that the session has been terminated or that the session could no 

longer stay established. 

void sessionUpdated(Session session) 

Notifies the application that the session has been updated. 

void sessionUpdateFailed(Session session) 

Notifies the application that the session update has been rejected. 

void sessionUpdateReceived(Session session) 

Notifies the application that the remote endpoint adds more media components to an 

established session and the local endpoint is now expected to accept or reject the update. 

Page 

116 

117 

117 

117 

115 

116 

116 

116 

Method Detail 

sessionTerminated 

void sessionTerminated(Session session) 

Notifies the application that the session has been terminated or that the session could no longer stay 

established. 

This callback can be invoked by the IMS engine if the access network is unavailable. 

This method is invoked at both involved endpoints. 

The Session has transited to STATE_TERMINATED. 

Parameters: 

session - the concerned Session 



sessionUpdateReceived 

void sessionUpdateReceived(Session session) 

Notifies the application that the remote endpoint adds more media components to an established session 

and the local endpoint is now expected to accept or reject the update. 

If the remote removed a media component, changed media directions, or updated application-specific 

SDP-attributes then this method is not called. 

The Session has transited to STATE_RENEGOTIATING. 

Parameters: 


sessionUpdated 

void sessionUpdated(Session session) 

Notifies the application that the session has been updated. 

This callback is invoked at both involved endpoints. 

The Session has transited to STATE_ESTABLISHED. 

Parameters: 


sessionUpdateFailed 

void sessionUpdateFailed(Session session) 

Notifies the application that the session update has been rejected. 



Parameters: 


sessionAlerting 

void sessionAlerting(Session session) 

Notifies the application that the remote part's terminal is alerting the user of this session invitation. 

Parameters: 




sessionStarted 

void sessionStarted(Session session) 

Notifies the application that the session has been established. 



Parameters: 


sessionStartFailed 

void sessionStartFailed(Session session) 

Notifies the application that the session could not be established. 


The Session has transited to STATE_TERMINATED. 

Parameters: 


sessionReferenceReceived 

void sessionReferenceReceived(Session session, 

Reference reference) 

Notifies the application that a reference request has been received from a remote endpoint. 

Only references that are created in a session are notified in this method. 

Parameters: 


reference - the Reference representing the request 


Interface Subscription 




ServiceMethod 

public interface Subscription 


A Subscription is used for subscribing to events of the event package sent from the remote server endpoint. The 

application receives event notifications via callbacks to SubscriptionListener.subscriptionNotify method 

while being subscribed. There are two types of a subscription: A durative subscription start with a call to subscribe 

and ends with a call to unsubscribe. An instant subscription starts with a call to poll and ends when the first 

notification is received. 

The Subscription life cycle consist of three states, STATE_INACTIVE, STATE_PENDING and STATE_ACTIVE. A 

durative subscription can be updated with a call to subscribe while in STATE_ACTIVE. 

Figure 1:The subscription states 

Client subscription example 

To establish a subscription, a Subscription has to be created. The event package to subscribe to must be set, 

and the subscription is started by calling subscribe. If the remote endpoint accepts the request, a notification will 

immediately be sent with the current event state that corresponds to the subscribed event package. 



try { 

sub = service.createSubscription(null, "sip:bob@home.net", "presence"); 

sub.setListener(this); 

sub.subscribe(); 


// handle Exceptions 

} 

public void subscriptionStarted(Subscription sub){ 

// if the subscription was successfull 

} 

public void subscriptionNotify(Subscription sub, Message notify){ 

// check the subscribed event state 

} 

. 

. 

See Also: 

CoreService.createSubscription(String, String, String), Publication 

Field Summary 


The Subscription is active. 


The Subscription is not active. 


A Subscription request is sent and the IMS engine is waiting for a response. 

Page 

120 

119 

120 



Returns the event package corresponding to this Subscription. 


Returns the current state of the state machine of the Subscription. 

void poll() 

Makes an instant subscription. 

void setListener(SubscriptionListener listener) 

Sets a listener for this Subscription, replacing any previous SubscriptionListener. 

void subscribe() 

Starts or updates a durative subscription. 

void unsubscribe() 

Terminates this durative subscription. 

Page 

121 

121 

120 

121 

120 

120 



Field Detail 



The Subscription is not active. 



STATE_PENDING 


A Subscription request is sent and the IMS engine is waiting for a response. 

STATE_ACTIVE 


The Subscription is active. 

Method Detail 

subscribe 

void subscribe() 


Starts or updates a durative subscription. 

In STATE_INACTIVE or STATE_ACTIVE the Subscription transits to STATE_PENDING after calling this 

method. 

Throws: 


IllegalStateException - if the Subscription is not in STATE_INACTIVE or STATE_ACTIVE 

poll 

void poll() 


Makes an instant subscription. 

The Subscription will transit to STATE_PENDING after calling this method. 

Throws: 


IllegalStateException - if the Subscription is not in STATE_INACTIVE 

unsubscribe 

void unsubscribe() 


Terminates this durative subscription. 

The Subscription will transit to STATE_PENDING after calling this method. 

Throws: 




IllegalStateException - if the Subscription is not in STATE_ACTIVE 

setListener 

void setListener(SubscriptionListener listener) 

Sets a listener for this Subscription, replacing any previous SubscriptionListener. A null reference is 


Parameters: 


getEvent 


Returns the event package corresponding to this Subscription. 

Returns: 

the event package 

getState 


Returns the current state of the state machine of the Subscription. 

Returns: 



Interface SubscriptionListener 



public interface SubscriptionListener 

This listener type is used to notify the application about subscription status and the event state of the subscribed 

event package. 

See Also: 

Subscription.setListener(SubscriptionListener) 


void subscriptionNotify(Subscription subscription, Message notify) 

Event notification received. 

void subscriptionStarted(Subscription subscription) 

Notifies the application that the durative subscription was successfully started or updated. 

void subscriptionStartFailed(Subscription subscription) 

Notifies the application that the durative subscription failed to start or update. 

void subscriptionTerminated(Subscription subscription) 

Notifies the application that the subscription was terminated. 

Page 

123 

122 

122 

122 

Method Detail 

subscriptionStarted 

void subscriptionStarted(Subscription subscription) 

Notifies the application that the durative subscription was successfully started or updated. 

The Subscription has transited to STATE_ACTIVE. 

Parameters: 

subscription - the concerned Subscription 

subscriptionStartFailed 

void subscriptionStartFailed(Subscription subscription) 

Notifies the application that the durative subscription failed to start or update. 

The Subscription has transited to STATE_INACTIVE. 

Parameters: 


subscriptionTerminated 

void subscriptionTerminated(Subscription subscription) 



Notifies the application that the subscription was terminated. 

The Subscription has transited to STATE_INACTIVE. 

Parameters: 


subscriptionNotify 

void subscriptionNotify(Subscription subscription, 


Event notification received. If the subscription is durative, the state remains at STATE_ACTIVE otherwise the 

state will transit to STATE_INACTIVE. 

Parameters: 


notify - event state of the subscribed event package 


Package javax.microedition.ims.core.media 


The package contains entities used to create media flows for IMS. 

See: 

Description 


BasicReliableMedia 

BasicReliableMediaListener 

BasicUnreliableMedia 

BasicUnreliableMediaListener 

FramedMedia 

FramedMediaListener 

The BasicReliableMedia represents a session media component that 

uses the reliable connection-oriented protocol of TCP to transport the 

content. 

A listener type for receiving notification of when a connection error has 

occurred on the stream(s). 

The BasicUnreliableMedia represents a media connection with 

application content transported over UDP. 

A listener type for receiving notification of when BasicUnreliableMedia 

content is available. 

The FramedMedia represents a media connection on which content is 

delivered in packets. 

A listener type for receiving notification of when FramedMedia content is 

transferred. 

Media The Media interface represents a generic media object of a session. 143 

MediaDescriptor MediaDescriptor is an interface towards the media parts of the SDP. 152 

MediaListener 

StreamMedia 

A listener type for receiving notification of when some mode property has 

changed on the media flow. 

The StreamMedia represents a standardized application-independent 

streaming media that can be rendered in real-time. 

Page 

126 

129 

130 

133 

134 

140 

156 

160 

Class Summary 

MediaPermission This class represents permissions to send or receive files in the IMSAPI. 157 

Package javax.microedition.ims.core.media Description 

The package contains entities used to create media flows for IMS. 

Page 

Static Structure 



Figure 1: Static structure of the package. 


Interface BasicReliableMedia 


javax.microedition.ims.core.media 


Media 

public interface BasicReliableMedia 

extends Media 

The BasicReliableMedia represents a session media component that uses the reliable connection-oriented 

protocol of TCP to transport the content. The connection is established when the media has been negotiated and 

accepted in the session according to [RFC4145]. The media flow is accessed as streams, one in each direction. 

Initializing the media 

The application MUST call the following method before calling Session.start or Session.update: 

• setContentType 

If not, an ImsException is thrown. 

Sending application specific content 

myMedia = (BasicReliableMedia)mySession.createMedia("BasicReliableMedia", 

Media.DIRECTION_SEND); 

myMedia.setContentType("application/myChess"); 


OutputStream os = myMedia.getOutputStream(); 

... 

if (myMedia.canWrite()) { 

os.write(myGameData.getBytes()); 

} 

Streams 

A stream pair is used to access the data flow from the media object. The IMS engine creates and manages the 

streams, and the application gets them by calling getInputStream and getOutputStream. The streams are 

created once and are singleton. If the streams are closed, the application can no longer access the data flow. 

read and write on the streams is possible as long as Media.canRead and Media.canWrite returns true. 

If Media.canRead returns false while the application is in a call to InputStream.read waiting for input to become 

available, IOException is thrown telling that read is no longer allowed. 

Receiving application specific content 

The input stream is opened and the read method will return when there is content available on the connection. 

myMedia = 

(BasicReliableMedia)mySession.createMedia("BasicReliableMedia", 

Media.DIRECTION_RECEIVE); 



InputStream is = myMedia.getInputStream(); 

int num; 

byte[] buf = new byte[1024]; 

while (myMedia.canRead() && ((num = is.read(buf)) != -1)) { 

// Consume the read content 

} 



NAT and firewall considerations 

BasicReliableMedia is affected by NATs and firewalls. To avoid losing the connection if behind a NAT, the 

application MUST keep transmitting data on the connection, even during periods of inactive use. 

To determine whether the device is behind a NAT or firewall, the isBehindNat method in the ConnectionState 

class can be used. 

Fields inherited from interface javax.microedition.ims.core.media.Media 

DIRECTION_INACTIVE, DIRECTION_RECEIVE, DIRECTION_SEND, DIRECTION_SEND_RECEIVE, STATE_ACTIVE, 

STATE_DELETED, STATE_INACTIVE, STATE_PENDING, STATE_PROPOSAL, UPDATE_MODIFIED, UPDATE_REMOVED, 

UPDATE_UNCHANGED 



Returns the content type of this Media. 

java.io.InputStream getInputStream() 

Returns an InputStream where incoming content can be read. 

java.io.OutputStream getOutputStream() 

Returns an OutputStream where outgoing content can be written. 

void setContentType(String contentType) 

Sets the content type of this Media. 

void setListener(BasicReliableMediaListener listener) 

Sets a listener for this BasicReliableMedia, replacing any previous 

BasicReliableMediaListener. 

Page 

128 

127 

127 

128 

128 

Methods inherited from interface javax.microedition.ims.core.media.Media 

canRead, canWrite, exists, getDirection, getMediaDescriptors, getProposal, getState, 

getUpdateState, setDirection, setMediaListener 

Method Detail 

getInputStream 

java.io.InputStream getInputStream() 


Returns an InputStream where incoming content can be read. If the Media.exists method returns false 

after calling this method, then the stream is closed. 

Returns: 

an InputStream to read incoming content from 

Throws: 

java.io.IOException - if Media.exists returns false, or if an I/O error occurs 

getOutputStream 

java.io.OutputStream getOutputStream() 




Returns an OutputStream where outgoing content can be written. If the Media.exists method returns 

false after calling this method, then the stream is closed. 

Returns: 

an OutputStream to write outgoing content to 

Throws: 

java.io.IOException - if Media.exists returns false, or if an I/O error occurs 

setContentType 



See Media for valid content types. 

Parameters: 

contentType - the content type 

Throws: 

IllegalStateException - if the Media is not in STATE_INACTIVE 

IllegalArgumentException - if the contentType argument is not a valid media type 

See Also: 

getContentType() 




Returns: 

the content type or null if the content type has not been set 

See Also: 

setContentType(String) 

setListener 

void setListener(BasicReliableMediaListener listener) 

Sets a listener for this BasicReliableMedia, replacing any previous BasicReliableMediaListener. A 

null reference is allowed and has the effect of removing any existing listener. 

Parameters: 



Interface BasicReliableMediaListener 

Interface BasicReliableMediaListener 


public interface BasicReliableMediaListener 

A listener type for receiving notification of when a connection error has occurred on the stream(s). 

See Also: 



void connectionError(BasicReliableMedia media) 

Notifies the application if the connection could not be established. 

Page 

129 

Method Detail 

connectionError 

void connectionError(BasicReliableMedia media) 

Notifies the application if the connection could not be established. 

Parameters: 

media - the concerned BasicReliableMedia 


Interface BasicUnreliableMedia 




Media 

public interface BasicUnreliableMedia 

extends Media 

The BasicUnreliableMedia represents a media connection with application content transported over UDP. 


To properly initialize the BasicUnrealibleMedia, use the following setter, or an ImsException will be thrown in 

Session.start or Session.update. 

• setContentType 

Sending and receiving content 

The application should make sure that Media.canRead and Media.canWrite return true before calling send and 

receive. 

Sending application specific content 

myMedia = (BasicUnreliableMedia)mySession.createMedia("BasicUnreliableMedia", 

Media.DIRECTION_SEND); 


myMedia.setListener(this); 


... 

byte[] myChessMove = getChessMove(); 

myMedia.send(myChessMove); 

Receiving application specific content 

The content is received and the application is notified through the method contentReceived on the 

BasicUnreliableMediaListener interface. The content can be retrieved by calling the receive method. 

public void contentReceived(BasicUnreliableMedia media) { 

try { 

byte[] hisChessMove = media.receive(); 

} catch (ImsException e) { 

... 

} 

} 

NAT and firewall considerations 

BasicUnreliableMedia is affected by NATs and firewalls. To avoid losing NAT binding, the application MUST 

keep sending periodic keep alive messages during periods of inactivity. 

To determine whether the device is behind a NAT or firewall, the method isBehindNat in the ConnectionState 

class can be used. 










byte[] receive() 

Receives the payload from the remote endpoint (note that the payload could be empty). 

void send(byte[] content) 

Sends content to the remote endpoint. 



void setListener(BasicUnreliableMediaListener listener) 

Sets a listener for this BasicUnreliableMedia, replacing any previous 

BasicUnreliableMediaListener. 

Page 

132 

131 

131 

131 

132 




Method Detail 

receive 

byte[] receive() 

throws java.io.IOException, 

ImsException 

Receives the payload from the remote endpoint (note that the payload could be empty). The received 

content can only be retrieved once. 

Returns: 

a byte array with the received content 

Throws: 

java.io.IOException - if canRead returns false or an I/O error occurs 

ImsException - if no payload is received 

send 

void send(byte[] content) 


Sends content to the remote endpoint. 

Parameters: 

content - a byte array for the content payload to be sent 

Throws: 

java.io.IOException - if canWrite returns false or an I/O error occurs 

IllegalArgumentException - if the content argument size is greater than 1500 bytes or is null 

setContentType 






Parameters: 

contentType - the content type 

Throws: 


IllegalArgumentException - if the contentType argument is not a valid media type 

See Also: 

getContentType() 




Returns: 

the content type or null if the content type has not been set 

See Also: 

setContentType(String) 

setListener 

void setListener(BasicUnreliableMediaListener listener) 

Sets a listener for this BasicUnreliableMedia, replacing any previous BasicUnreliableMediaListener. 

A null reference is allowed and has the effect of removing any existing listener. 

Parameters: 



Interface BasicUnreliableMediaListener 

Interface BasicUnreliableMediaListener 


public interface BasicUnreliableMediaListener 

A listener type for receiving notification of when BasicUnreliableMedia content is available. 

See Also: 

Media 


void contentReceived(BasicUnreliableMedia media) 

Notifies the application when new content is available. 

Page 

133 

Method Detail 

contentReceived 

void contentReceived(BasicUnreliableMedia media) 

Notifies the application when new content is available. The content can be retrieved by calling receive on 

the BasicUnreliableMedia. 

Parameters: 

media - the concerned BasicUnreliableMedia 


Interface FramedMedia 




Media 

public interface FramedMedia 

extends Media 

The FramedMedia represents a media connection on which content is delivered in packets. It can be used for 

instant messages, serialized data objects or files. The media is transported with the Message Session Relay 

Protocol (MSRP), according to [RFC4975]. There are two different ways to access the send and receive methods: 

with content as byte arrays or as files. 

Large contents may be divided into multiple transactions. The different parts will be merged together in the remote 

terminal. It is possible to send and receive multiple messages simultaneous using the same FramedMedia. 

FramedMedia formats the locator string according to JSR 75 in sendFile and receiveFile (see [JSR75]). The 

following code can be used to send a file on a file system, where CFCard is a valid existing file system root name 

for a given implementation: 

framedMedia.sendFile("file:///CFCard/images/bob.png", "image/png", headers); 

Headers that can be set in sendFile, sendBytes and retrieved in getHeader are 'Success-Report', 'Failure-Report' 

and those defined in the BNF for 'Other-Mime-header' according to [RFC4975]. 


FramedMedia requires no extra initialization before session.start or session.update. However, the developer 

should consider calling FramedMedia.setAcceptedContentTypes to restrict the set of content types. 

Media flows in FramedMedia 

If Media.canRead and Media.canWrite returns true the application may call receiveBytes or receiveFile, and 

sendBytes or sendFile. If they return false, IOException is thrown instead. 

Sending small instant messages 

String[] acceptedTypes = new String[] {"text/plain"}; 

myMedia = (FramedMedia)mySession.createMedia("FramedMedia", 

Media.DIRECTION_SEND_RECEIVE); 

myMedia.setAcceptedContentTypes(acceptedTypes); 


... 


messageId = myMedia.sendBytes("You move like a queen, Alice :-)".getBytes(), 

"text/plain", null); 

Sending images as files 

String[] acceptedTypes = new String[] {"image/png"}; 

myMedia = (FramedMedia)mySession.createMedia("FramedMedia", 


myMedia.setAcceptedContentTypes(acceptedTypes); 


... 


headers = new String[][] {{"Content-Description", 

"a picture of a pawn"}}; 



messageId = myMedia.sendFile("file:///CFCard/images/pawn.png", 

"image/png", headers); 

Receiving images and instant messages 

The application is notified through the callback contentReceived on the FramedMediaListener interface when 

new content is received. When the content has been retrieved it will be removed from the IMS engine and further 

retrieval for the same messageId will not be possible. Content can be retrieved with the receiveBytes or 

receiveFile method, regardless on how it was sent. 

public void contentReceived(FramedMedia media, 

String messageId, 

int size, 

String fileName) { 

} 

String contentType = media.getContentType(messageId); 

if (contentType.equals("text/plain")) { 

byte[] content = media.receiveBytes(messageId); 

... 

// do something with content 

} else if (contentType.equals("image/png")) { 

try { 

media.receiveFile(messageId, "" + fileName); 

} catch (IOException e) { 

... 

} 

} 






void cancel(String messageId) 

Cancels the ongoing transfer. 

String[] getAcceptedContentTypes() 

Returns the accepted content type(s) of this media. 

String getContentType(String messageId) 

Returns the content type of the content that is identified by the messageId parameter. 

String getHeader(String messageId, String key) 

Returns the header value from the content that is identified by the messageId parameter. 

byte[] receiveBytes(String messageId) 

Receives content from the remote endpoint. 

void receiveFile(String messageId, String locator) 

Receives a file from the remote endpoint. 

String sendBytes(byte[] content, String contentType, String[][] headers) 

Sends the content to the remote endpoint over a reliable connection. 

String sendFile(String locator, String contentType, String[][] headers) 

Sends a file to the remote endpoint over a reliable connection. 

void setAcceptedContentTypes(String[] acceptedContentTypes) 

Sets the accepted content type(s) of this media. 

Page 

138 

137 

137 

137 

138 

138 

136 

136 

137 



void setListener(FramedMediaListener listener) 

Sets a listener for this FramedMedia, replacing any previous FramedMediaListener. 

139 




Method Detail 

sendBytes 

String sendBytes(byte[] content, 

String contentType, 

String[][] headers) 


Sends the content to the remote endpoint over a reliable connection. This method is asynchronous. 

Parameters: 

content - a byte array containing the content to be sent 


headers - an array of arrays, specifying key and value, null can be used to indicate that no extra 

headers are desired 

Returns: 

an identifier for the content sent 

Throws: 

java.io.IOException - if canWrite returns false, or if an I/O error occurs 

IllegalArgumentException - if the content argument is null, 

if the syntax of the contentType or headers argument is invalid, 

if the contentType is not part of the accepted content types 

sendFile 

String sendFile(String locator, 

String contentType, 

String[][] headers) 


Sends a file to the remote endpoint over a reliable connection. This method is asynchronous. 

Parameters: 

locator - the location of the file to send 


headers - an array of arrays, specifying key and value, null can be used to indicate that no extra 

headers are desired 

Returns: 

an identifier for the content sent 

Throws: 

java.io.IOException - if canWrite returns false, or if an I/O error occurs when operating with 

the file or that the file could not be opened 

IllegalArgumentException - if the syntax of the contentType or headers argument is invalid, 

if the contentType is not part of the accepted content types 

SecurityException - if sending a file is not permitted 




String getContentType(String messageId) 

Returns the content type of the content that is identified by the messageId parameter. 

Parameters: 

messageId - an identifier for the content 

Returns: 

the content type 

Throws: 

IllegalArgumentException - if the messageId is not found 

setAcceptedContentTypes 

void setAcceptedContentTypes(String[] acceptedContentTypes) 

Sets the accepted content type(s) of this media. 

If the accepted content type(s) has not been set, it will default to "*" and indicate that any content type may 

be transferred. 


Parameters: 

acceptedContentTypes - an array of content types accepted in this media 

Throws: 


IllegalArgumentException - if the syntax of the acceptedContentTypes argument is invalid 

See Also: 

getAcceptedContentTypes() 

getAcceptedContentTypes 

String[] getAcceptedContentTypes() 

Returns the accepted content type(s) of this media. 

If the accepted content type(s) has not been set, it will default to "*" and indicate that any content type may 

be transferred. 

Returns: 

the accepted content type(s) of this media 

See Also: 

setAcceptedContentTypes(String[]) 

getHeader 

String getHeader(String messageId, 

String key) 

Returns the header value from the content that is identified by the messageId parameter. 

Parameters: 

messageId - an identifier for the content 



key - the header name 

Returns: 

a string containing the header value or null if the header does not exist 

Throws: 

IllegalArgumentException - if the messageId is not found, 

if the key is null 

receiveBytes 

byte[] receiveBytes(String messageId) 


Receives content from the remote endpoint. 

Parameters: 

messageId - identifies which content to receive 

Returns: 

a byte array containing the received content 

Throws: 

java.io.IOException - if canRead returns false, or if an I/O error occurs 

IllegalArgumentException - if the messageId is not found or if there is no completely 

downloaded content corresponding to the messageId 

receiveFile 

void receiveFile(String messageId, 

String locator) 


Receives a file from the remote endpoint. This method will create a new file at the specified location. If the 

file already exists, it will be overwritten. 

Parameters: 

messageId - identifies which file to receive 

locator - sets the location where the file will be stored 

Throws: 

java.io.IOException - if canRead returns false, or if an I/O error occurs when operating with the 

file or the file could not be opened 

IllegalArgumentException - if the messageId is not found or if there is no completely 

downloaded content corresponding to the messageId 

SecurityException - if receiving a file is not permitted 

cancel 

void cancel(String messageId) 

Cancels the ongoing transfer. This method can be called for outgoing and incoming content. If no matching 

messageId is found or if the content is already transferred, this method will not do anything. 

Parameters: 

messageId - the identifier corresponding to the content to be canceled 



setListener 

void setListener(FramedMediaListener listener) 

Sets a listener for this FramedMedia, replacing any previous FramedMediaListener. A null reference is 


Parameters: 



Interface FramedMediaListener 



public interface FramedMediaListener 

A listener type for receiving notification of when FramedMedia content is transferred. When content becomes 

available the application is notified by a call to the contentReceived method. The application can then retrieve the 

content by either using the receiveBytes or receiveFile method on the FramedMedia interface. 

See Also: 

FramedMedia 


void connectionError(FramedMedia media) 

Notifies the application when an I/O error has occurred. 

void contentReceived(FramedMedia media, String messageId, int size, String fileName) 

Notifies the application when the content is completely received. 

void contentReceiveFailed(FramedMedia media, String messageId) 

Notifies the application that the content could not be received or that the content has been 

canceled by the sending endpoint. 

void deliveryFailure(FramedMedia media, String messageId, int statusCode, String 

reasonPhrase) 

Notifies the application when the content corresponding to the messageId has not been 

successfully delivered to the remote endpoint. 

void deliverySuccess(FramedMedia media, String messageId) 

Notifies the application when the content corresponding to the messageId has been 

successfully delivered to the remote endpoint. 

void transferProgress(FramedMedia media, String messageId, int bytesTransferred, int 

bytesTotal) 

Notifies the application when there is progress to be reported. 

Page 

142 

140 

141 

141 

141 

141 

Method Detail 

contentReceived 

void contentReceived(FramedMedia media, 


int size, 

String fileName) 

Notifies the application when the content is completely received. The content can now be retrieved by 

calling receiveBytes or receiveFile with the corresponding messageId on the FramedMedia object. 

Parameters: 

media - the FramedMedia that received the content 

messageId - identifies the content that is ready for retrieval 

size - the size of the content in bytes 

fileName - the file name or null if a file name is not associated with the messageId 



contentReceiveFailed 

void contentReceiveFailed(FramedMedia media, 

String messageId) 

Notifies the application that the content could not be received or that the content has been canceled by the 

sending endpoint. The messageId is considered invalid after this callback and further use of this messageId 

is not possible. 

Parameters: 

media - the FramedMedia that could not receive the content 

messageId - identifies the content that could not be received 

transferProgress 

void transferProgress(FramedMedia media, 


int bytesTransferred, 

int bytesTotal) 

Notifies the application when there is progress to be reported. This will be invoked for both outgoing and 

incoming content. 

Parameters: 

media - the FramedMedia that received/sent the content 

messageId - identifies the content that is being transferred 

bytesTransferred - the number of bytes that is transferred 

bytesTotal - the number of total bytes in the content, this parameter is -1 if the size is not known 

deliverySuccess 

void deliverySuccess(FramedMedia media, 

String messageId) 

Notifies the application when the content corresponding to the messageId has been successfully delivered 

to the remote endpoint. The messageId is considered invalid after this callback and further use of this 

messageId is not possible. 

This method is invoked at the endpoint that sent the content. 

Parameters: 

media - the FramedMedia that sent the content 

messageId - identifies the content that has been transferred 

deliveryFailure 

void deliveryFailure(FramedMedia media, 


int statusCode, 

String reasonPhrase) 

Notifies the application when the content corresponding to the messageId has not been successfully 

delivered to the remote endpoint. The messageId is considered invalid after this callback and further use of 

this messageId is not possible. 



This method is invoked at the endpoint that sent the content. 

See [RFC4975] for valid status codes. 

Parameters: 

media - the FramedMedia that sent the content 

messageId - identifies the content that could not be transferred 

statusCode - the status code why the transaction failed 

reasonPhrase - the reason phrase 

connectionError 

void connectionError(FramedMedia media) 

Notifies the application when an I/O error has occurred. 

Parameters: 

media - the concerned FramedMedia 


Interface Media 




BasicReliableMedia, BasicUnreliableMedia, FramedMedia, StreamMedia 

public interface Media 

The Media interface represents a generic media object of a session. Methods are provided common for all media 

types. 

Media objects 

When a calling terminal creates a session, a number of media objects can be added. When the session is started, 

the IMS engine creates a media offer based on the properties of the included media, and sends it to the remote 

endpoint. If the session is accepted, the remote endpoint has a sufficient amount of information to allow it to create 

the corresponding media objects. In this way, both endpoints get the same view of the media transfer. A common 

and useful scenario for IMS applications is to stream video and audio to render in real-time. To support efficient 

implementations here, an application can pass the stream to a platform-supplied standard Player that supports an 

appropriate common codec to do the rendering. 

The Media interface is used to represent the generic concept of a media in an IMS session. Methods are available 

that address the signalling plane of the media, while other methods supports the media plane. 

Media objects from a media plane perspective 

A media object has an associated media flow. The media flow refers to the actual realtime streaming of media 

content between the local and remote endpoints over the IMS network. An important function of the IMSAPI is to 

enable an IMS application to read and write data on the flow, for example to exchange chat messages, audio and 

video or gaming data with the remote. This is the essential part of end-to-end communication of the IMS. 

While Media is a generic media flow-independent interface, the four media types interfaces extend Media according 

to the transport protocol. StreamMedia uses RTP/AVP for the basic profile, and RTP/AVPF also in the MMTel 

profile, FramedMedia uses TCP/MSRP, BasicUnreliableMedia uses UDP, and BasicReliableMedia is based on 

TCP. A media object part of a session implements one of the four media type interfaces. Because of this mapping, 

each media type has its specific uses. For further information on each media type, see their interfaces. 

Media flow and mode properties 

The IMS engine manages three generic boolean properties for a media flow, called media mode properties. By 

observing the current state of the mode properties, the application will know what actions are possible on the flow, 

for example read or write operations. The mode properties are: 

d) exists: True if there is an end-to-end media flow, false otherwise. 

e) canRead: True if the fmedia low accepts read of data from it, false otherwise 

f) canWrite: True if the flow accepts write of data to it, false otherwise 

Each mode mode property depends on a number of mode factors, that describe the media object in general. The 

node properties change their values dynamically based on the mode factors. 

For 'exists', there is one mode factor for any type of media: 

(iv) 'Exists' becomes true when the data flow is set up according to the procedures of the media type transport 

protocol, and false when the media flow is torn down. 

That mode factor implies 'exists' is false if media is in STATE_INACTIVE, STATE_DELETED and STATE_PROPOSAL. 

For 'canRead' the following factors apply for any type of media: 



• The 'exists' mode is true. 

• The media direction is DIRECTION_RECEIVE or DIRECTION_SEND_RECEIVE 

• The flow contains, or is capable to contain, data available for read. 

For 'canWrite' the following factors apply for any type of media: 

• The 'exists' mode is true. 

• The media direction is DIRECTION_SEND or DIRECTION_SEND_RECEIVE 

• The media is in STATE_ACTIVE 

The media must be in STATE_ACTIVE due to that the application should be able to write data before the session is 

established. 

The IMS engine feeds the StreamMedia with input to the flow, and this additional factor applies there for 'canWrite': 

• There is data available from the stream media source 

'canRead' and 'canWrite' are independent of each other. 

Besides the above, device-specific constraints may apply. For example, if there is a higher priority process that 

claims networking resources, then 'canRead' and 'canWrite may be set to false until the resources are made 

available again to the application. 

The boolean methods Media.exists, Media.canRead, and Media.canWrite are available to all media objects to 

get the current property values. An application that reads incoming data SHOULD make sure that Media.canRead 

returns true before attempting to read, and that Media.canWrite returns true when writing data. 

Due to that properties are changed dynamically, the MediaListener callback interface is provided. This interface is 

used when the IMS engine notifies the application of mode changes on the media. 

A note on mode properties and media direction 

The direction of the media component is part of the session contract, i.e. it is an agreement between the local and 

remote devices on how the media is supposed to be used. By observing the media mode properties to see if it is 

allowed to operate on the media flow, the application does not have to consider the media direction in its code. 

Media objects from a signaling perspective 

There are some aspects of the media objects seen from a signaling perspective. These are described below. 


There are different rules for how a media MUST be initialized between media creation and session start or update. 

See further sections for the respective media types. 

Content Types 

Content types identifies the content type of a Media. They can be registered MIME types or some user defined type 

that follow the MIME syntax. See [RFC2045] and [RFC2046]. 

Example content types: 

• "text/plain" 

• "image/png" 

• "video/mpeg" 

• "application/myChess" 

Media Life Cycle 



The life cycle of each Media is independent of other Medias life cycles and has four main states: STATE_INACTIVE, 

STATE_PENDING, STATE_ACTIVE and STATE_DELETED. There is also a fifth state, STATE_PROPOSAL, that is not part of 

the ordinary life cycle but instead only meant to track changes on a modified Media. 

The media life cycle is connected to the life cycle of the Session. A transition in a Media is the effect of a session 

transition in the form of a session callback, or a method call in the session, as can be seen in Figure 1. 

Figure 1: The media states visible on the originating endpoint, except STATE_PROPOSAL 

Update state 

The update state is used to track changes that have been done to an active Media on either the originating or 

terminating endpoint. If a Media has been accepted in a session the update state will be UPDATE_UNCHANGED. 

If a Media is proposed to be removed or modified the getUpdateState reflect the changes but the modifications 

does not take place before the Session has been negotiated and accepted. The modifications can however be 

traced by inspecting the proposed Media, that can be obtained with the getProposal method, until the Session is 

updated. 

After a session update the application SHOULD call getMedia on the Session and take actions if needed. 

Examples of the Media states and update states 

This example shows which state and update state the Media can reside in at the terminating endpoint when 

receiving a session invitation or session update. The state and update state will be the same for the originating 

endpoint as well. 

public void sessionInvitationReceived(CoreService service, Session session) { 

// all medias are pending in a session invite 

media.getState() == STATE_PENDING; 

// getUpdateState is not applicable in this state 

} 

... 

public void sessionUpdateReceived(Session session) { 



} 

// this will show that the media is proposed to be added to the session 

media.getState() == STATE_PENDING; 

// getUpdateState is not applicable in this state 

... 

// this will show that the media is proposed to be removed from the session 

media.getState() == STATE_ACTIVE; 

media.getUpdateState() == UPDATE_REMOVED; 

... 

// this will show that the media is proposed to be modified in a session 


media.getUpdateState() == UPDATE_MODIFIED; 

media.getProposal(); // returns a fictious media to track changes 

... 

// this will show a media that is unchanged in the session update 


media.getUpdateState() == UPDATE_UNCHANGED; 

This example shows how an application can inspect changes done to a media in a session update. 

public void sessionUpdateReceived(Session session) { 

// if the first media in the array is a media in STATE_ACTIVE and 

// update state is UPDATE_MODIFIED 

} 

Media currentMedia = session.getMedia()[0]; 

Media changedMedia = currentMedia.getProposal(); 

// then the application can track changes, for example 

if (currentMedia.getDirection() != changedMedia.getDirection()) { 

... 

} 

// and now the application can decide if the update should be accepted or 

// rejected 

session.accept(); 

Field Summary 

int DIRECTION_INACTIVE 

The Media has an inactive direction, meaning it cannot send or receive content. 

int DIRECTION_RECEIVE 

The Media can receive content, but not send. 

int DIRECTION_SEND 

The Media can send content, but not receive. 

int DIRECTION_SEND_RECEIVE 

The Media can send and receive content, also known as a bi-directional media. 


The Media exists in a session and the media offer has been accepted by both parties. 

int STATE_DELETED 

The Media has been part of an existing session but is now removed, or the Media has 

been rejected or deleted by the IMS engine. 


The Media is created and added to a session. 


The Media exists in a session and a media offer has been sent to the remote endpoint. 

int STATE_PROPOSAL 

The Media is a fictitious media and is only meant to be inspected to track changes during 

a session update. 

Page 

147 

147 

148 

148 

148 

148 

148 

148 

148 



int UPDATE_MODIFIED 

This sub-state specifies that this Media is proposed to be modified and must be negotiated 

before the modifications can be deployed. 

int UPDATE_REMOVED 

This sub-state specifies that this Media is proposed to be removed from the session and 

must be negotiated before removal can be made. 

int UPDATE_UNCHANGED 

This sub-state specifies that this Media is unchanged since session establishment or the 

last session update. 

149 

149 

149 


boolean canRead() 

Returns true if it is possible to read from the data flow. 

boolean canWrite() 

Returns true if it is possible to write to the data flow. 

boolean exists() 

Returns true if there is a data flow for this media. 

int getDirection() 

Returns the current direction of this Media. 

MediaDescriptor[] getMediaDescriptors() 

Returns the media descriptor(s) associated with this Media. 

Media getProposal() 

Returns a fictitious media that is only meant to track changes that are about to be 

made to the media. 


Returns the current state of this Media. 

int getUpdateState() 

Returns the current update state of this Media. 

void setDirection(int direction) 

Sets the direction of this Media. 

void setMediaListener(MediaListener listener) 

Sets a listener for this Media, replacing any previous MediaListener. 

Page 

151 

151 

151 

149 

149 

150 

150 

150 

150 

151 

Field Detail 

DIRECTION_INACTIVE 

public static final int DIRECTION_INACTIVE 

The Media has an inactive direction, meaning it cannot send or receive content. 

DIRECTION_RECEIVE 

public static final int DIRECTION_RECEIVE 

The Media can receive content, but not send. 



DIRECTION_SEND 

public static final int DIRECTION_SEND 

The Media can send content, but not receive. 

DIRECTION_SEND_RECEIVE 

public static final int DIRECTION_SEND_RECEIVE 

The Media can send and receive content, also known as a bi-directional media. 



The Media is created and added to a session. 

The Media is not active and there can currently be no content transfer within this Media. 

STATE_PENDING 


The Media exists in a session and a media offer has been sent to the remote endpoint. A new Media that is 

added in an incoming invite/update also resides in this state. 


STATE_ACTIVE 


The Media exists in a session and the media offer has been accepted by both parties. 

The Media is active and content can be transferred within this Media. 

STATE_DELETED 

public static final int STATE_DELETED 

The Media has been part of an existing session but is now removed, or the Media has been rejected or 

deleted by the IMS engine. 


STATE_PROPOSAL 

public static final int STATE_PROPOSAL 



The Media is a fictitious media and is only meant to be inspected to track changes during a session update. 

After the session update this Media should be considered discarded. 


public static final int UPDATE_UNCHANGED 

This sub-state specifies that this Media is unchanged since session establishment or the last session 

update. 

UPDATE_MODIFIED 

public static final int UPDATE_MODIFIED 

This sub-state specifies that this Media is proposed to be modified and must be negotiated before the 

modifications can be deployed. 

The modifications can be traced by inspecting the proposed Media by calling getProposal. 

UPDATE_REMOVED 

public static final int UPDATE_REMOVED 

This sub-state specifies that this Media is proposed to be removed from the session and must be 

negotiated before removal can be made. 

Method Detail 

getMediaDescriptors 

MediaDescriptor[] getMediaDescriptors() 

Returns the media descriptor(s) associated with this Media. 

Returns: 

the media descriptor(s) 

getDirection 

int getDirection() 

Returns the current direction of this Media. 

Returns: 

the current direction of this Media 

See Also: 

setDirection(int) 



setDirection 

void setDirection(int direction) 

Sets the direction of this Media. 

If a Media is changed in an established Session, the application has the responsibility to call update on the 

Session. 

Note: If the Media is in STATE_ACTIVE the direction will be set on the proposal media until the Session has 

been updated. The proposal media can be retrieved with the getProposal method on the Media interface. 

Parameters: 

direction - the direction of the Media 

Throws: 

IllegalStateException - if the Media is not in STATE_INACTIVE or STATE_ACTIVE 

IllegalArgumentException - if the direction argument is invalid 

See Also: 

getDirection() 

getState 


Returns the current state of this Media. 

Returns: 


getUpdateState 

int getUpdateState() 

Returns the current update state of this Media. 

Returns: 

the current update state 

Throws: 

IllegalStateException - if the Media is not in STATE_ACTIVE 

getProposal 

Media getProposal() 

Returns a fictitious media that is only meant to track changes that are about to be made to the media. 

After the Session has been accepted or rejected this proposed media should be considered discarded. 

Returns: 

a media proposal 

Throws: 

IllegalStateException - if the Media is not in STATE_ACTIVE, 

if the update state is not in UPDATE_MODIFIED 



exists 

boolean exists() 

Returns true if there is a data flow for this media. 

Returns: 

true if a data flow exists, false otherwise 

canRead 

boolean canRead() 

Returns true if it is possible to read from the data flow. 

Returns: 

true if a data flow allows read, false otherwise 

canWrite 

boolean canWrite() 

Returns true if it is possible to write to the data flow. 

Returns: 

true if a data flow allows write, false otherwise 

setMediaListener 

void setMediaListener(MediaListener listener) 

Sets a listener for this Media, replacing any previous MediaListener. The method 

MediaListener.modeChanged is called directly after setting a MediaListener with this method. 

A null reference is allowed and has the effect of removing any existing listener. 

Parameters: 



Interface MediaDescriptor 



public interface MediaDescriptor 

MediaDescriptor is an interface towards the media parts of the SDP. The interface is most useful for applications 

that, within the realm of a composed capability (ICSI, IARI and/or other service level feature tags), need to 

manipulate media-related fields of the session SDP in general, and add new application-specific attributes in 

particular. 

The example SDP below shows the media-related parts accessible from the interface in bold. 

v=0 

o=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com 

s= 

c=IN IP4 host.atlanta.example.com 

t=0 0 

m=audio 49170 RTP/AVP 0 8 97 

a=rtpmap:0 PCMU/8000 

a=rtpmap:8 PCMA/8000 

a=rtpmap:97 iLBC/8000 

m=video 51372 RTP/AVP 31 32 

a=rtpmap:31 H261/90000 

a=rtpmap:32 MPV/90000 

The getters of the interface read fields from the last received SDP. The setters modify all remaining SDPs to be 

sent during the lifetime of the media in the session, or until superseded by other modifications. 

The application can get, set, and remove SDP lines that are not reserved for the IMS engine. Attributes can be get, 

set and removed freely except reserved. The following attributes are classified as unconditionally reserved and can 

not be modified using the MediaDescriptor interface: des, curr, conf, mid, ice-pwd, ice-ufrag, candidate, 

remote-candidates, sendonly, recvonly, sendrecv, inactive, csup, creq, acap, tcap, pcfg, acfg, 3gpp_sync_info. 

Depending on the contents of the protocol field in the m-line (in the example SDP the field is set to RTP/AVP) other 

attributes are reserved according to the following: 

RTP/AVP (set for StreamMedia): rtpmap, fmtp, dccp-service-code, rtcp-mux, rtp-fb, ptime, maxptime, framesize, 

framerate, quality 

TCP (set for BasicReliableMedia): setup, connection 

TCP/MSRP (set for FramedMedia): setup, connection, accept-types, accept-wrapped-types, max-size, path 

See Also: 

SessionDescriptor 



Adds an attribute (a=) to the Media. 


Returns all attributes (a=) for the Media. 

String[] getBandwidthInfo() 

Returns the proposed bandwidth (b=) to be used by the media. 

String getMediaDescription() 

Returns the contents of the media description field (m=) of the current incoming SDP for this 

media. 

String getMediaTitle() 

Returns the title (i=) of the Media. 

Page 

154 

155 

154 

155 

153 




Removes an attribute (a=) from the Media. 

void setBandwidthInfo(String[] info) 

Sets the proposed bandwidth (b=) to be used by the media. 

void setMediaTitle(String title) 

Sets a title (i=) to the Media. 

154 

153 

153 

Method Detail 

setMediaTitle 

void setMediaTitle(String title) 

Sets a title (i=) to the Media. 

Parameters: 

title - the Media title to set 

Throws: 


IllegalArgumentException - if the title argument is null 

See Also: 

getMediaTitle() 

getMediaTitle 

String getMediaTitle() 

Returns the title (i=) of the Media. 


Returns: 

the Media title or null if the title has not been set 

See Also: 

setMediaTitle(String) 

setBandwidthInfo 

void setBandwidthInfo(String[] info) 

Sets the proposed bandwidth (b=) to be used by the media. 


Example: 

MediaDescriptor desc; 

desc.setBandwidthInfo(new String[]{ "AS:128" }); 

Parameters: 

info - the bandwidth info to set 

Throws: 

IllegalStateException - if the Media is not in STATE_INACTIVE or STATE_ACTIVE, 

if the current media profile is vs or mmtel. 



IllegalArgumentException - if the info argument is null or if the syntax is invalid 

See Also: 

getBandwidthInfo() 

getBandwidthInfo 

String[] getBandwidthInfo() 

Returns the proposed bandwidth (b=) to be used by the media. An empty string array will be returned if the 

bandwidth information could not be retrieved. 


Returns: 

bandwidth information 

See Also: 

setBandwidthInfo(String[]) 

removeAttribute 


Removes an attribute (a=) from the Media. 

The example below removes the "max-size:2048000" attribute for a FramedMedia. 

MediaDescriptor[] desc = framedMedia.getMediaDescriptors(); 

desc[0].removeAttribute("max-size:2048000"); 

Note: If the Media is in STATE_ACTIVE the attribute will be removed on the proposal media until the 

Session has been updated. The proposal media can be retrieved with the getProposal method on the 

Media interface. 

Parameters: 

attribute - the attribute to remove 

Throws: 

IllegalArgumentException - if the attribute argument is null, 

if the attribute does not exist in the Media, 

if the attribute could not be removed 


addAttribute 


Adds an attribute (a=) to the Media. Adding attributes that the IMS engine can set, such as "sendonly", 

"recvonly", "sendrecv", will lead to an IllegalArgumentException. 

The example below adds two attributes for a FramedMedia. 

MediaDescriptor[] desc = framedMedia.getMediaDescriptors(); 

desc[0].addAttribute("max-size:2048000"); 

desc[0].addAttribute("synced"); 

The resulting attribute lines will be: 



a=max-size:2048000 

a=synced 

Note: If the Media is in STATE_ACTIVE the attribute will be set on the proposal media until the Session has 

been updated. The proposal media can be retrieved with the getProposal method on the Media interface. 

Parameters: 

attribute - the attribute to add 

Throws: 

IllegalArgumentException - if the attribute argument is null or if the syntax of the attribute 

argument is invalid, 

if the attribute already exist in the Media, 

if the attribute could not be added 


getAttributes 


Returns all attributes (a=) for the Media. If there are no attributes, an empty string array will be returned. 

Returns: 

a string array containing the attributes 

getMediaDescription 

String getMediaDescription() 


Returns the contents of the media description field (m=) of the current incoming SDP for this media. 

Example of an SDP m-line that may be returned for an audio stream media: audio 4000 RTP/AVP 97 101 

Returns: 

the media description 

Throws: 

IllegalStateException - if the Media is in STATE_INACTIVE 


Interface MediaListener 

Interface MediaListener 


public interface MediaListener 

A listener type for receiving notification of when some mode property has changed on the media flow. 

See Also: 



void modeChanged(Media media) 

The method is called when some media mode property has changed. 

Page 

156 

Method Detail 

modeChanged 

void modeChanged(Media media) 

The method is called when some media mode property has changed. See Media interface for a description 

of media mode properties. 

Parameters: 

media - the concerned Media 


Class MediaPermission 




java.security.Permission 

java.security.BasicPermission 

javax.microedition.ims.core.media.MediaPermission 

public class MediaPermission 

extends java.security.BasicPermission 

This class represents permissions to send or receive files in the IMSAPI. A MediaPermission consists of a 

pathname and a set of actions valid for that pathname. 

Pathname is the pathname of the file or directory granted the specified actions. A pathname that ends in "/*" (where 

"/" is the file separator character, File.separatorChar) indicates all the files and directories contained in that 

directory. A pathname consisting of the special token "" matches any file. 

The actions to be granted are passed to the constructor in a string containing a list of one or more 

comma-separated keywords. The possible keywords are "read" and "write". "read" means permission to read the 

contents of the file and send to the remote endpoint. "write" means means permission to receive contents from the 

remote and write that to the file pathname. 

The actions string is converted to lowercase before processing. 


MediaPermission(String pathname, String actions) 

Creates a new MediaPermission object with the specified actions. 

Page 

158 


boolean equals(Object obj) 

Checks two MediaPermission objects for equality. 

String getActions() 

Returns the "canonical string representation" of the actions. 

int hashCode() 


boolean implies(java.security.Permission p) 

Checks if this FilePermission object "implies" the specified permission. 

Page 

158 

158 

158 

159 

Methods inherited from class java.security.BasicPermission 

newPermissionCollection 

Methods inherited from class java.security.Permission 

getName, toString 




MediaPermission 

public MediaPermission(String pathname, 

String actions) 

Creates a new MediaPermission object with the specified actions. pathname is the pathname of a file or 

directory possibly ending with "/*", or the special token "" matching any file. actions 

contains a comma-separated list of the desired actions granted on the file. Possible actions are "read" and 

"write". 

Parameters: 

pathname - the pathname of the file 

actions - the action string 

Throws: 

IllegalArgumentException - if actions is null, empty or contains an action other than the 

specified possible actions. 

Method Detail 

equals 

public boolean equals(Object obj) 

Checks two MediaPermission objects for equality. 

Overrides: 

equals in class java.security.BasicPermission 

Parameters: 

obj - the object we are testing for equality with this object. 

Returns: 

true if obj is a MediaPermission and has the same path and actions as this MediaPermission 

object. 

See Also: 

java.security.Permission.equals(java.lang.Object) 

getActions 

public String getActions() 

Returns the "canonical string representation" of the actions. That is, this method always returns present 

actions in the following order: read, write. For example, if this MediaPermission object allows both write 

and read actions, a call to getActions will return the string "read,write". 

Overrides: 

getActions in class java.security.BasicPermission 

Returns: 

the canonical string representation of the actions. 

See Also: 

java.security.Permission.getActions() 

hashCode 

public int hashCode() 




Overrides: 

hashCode in class java.security.BasicPermission 

Returns: 

a hash code value for this object. 

implies 

public boolean implies(java.security.Permission p) 

Checks if this FilePermission object "implies" the specified permission. This method returns true if: 

• p is an instanceof FilePermission 

• p's actions are a proper subset of this object's actions, and 

• p's pathname is implied by this object's pathname. For example, "/tmp/*" implies "/tmp/foo", since 

"/tmp/*" encompasses all files in the "/tmp" directory, including the one named "foo". 

Overrides: 

implies in class java.security.BasicPermission 

Parameters: 

p - the permission to check against. 

Returns: 

true if the specified permission is not null and is implied by this object, false otherwise. 


Interface StreamMedia 




Media 

public interface StreamMedia 

extends Media 

The StreamMedia represents a standardized application-independent streaming media that can be rendered in 

real-time. The typical use is to stream audio or video content between endpoints in real-time, in for example 

telephony applications. The IMS engine manages the media formats, codecs and protocols used in the 

transmission according to relevant standard. It is possible to stream audio and video separately, as well as 

combined audio and video. 

By default, the StreamMedia object supports audio streaming, which is mandatory for all devices claiming 

streaming support. The data is sourced from a microphone of the device. 

The originating endpoint may call StreamMedia.setStreamType to explicitly set the media type for streaming, 

regardless of whether it is going to send or receive media. This is not possible for the terminating endpoint. For 

video (moving pictures), the camera is used to source video content. Both peripherals are used for the combined 

audio video media. If the terminal has several microphones, or cameras, the choice is implementation-specific. 

It is possible for an originating endpoint to change the data source to something else if needed. This is not available 

to the terminating endpoint, thus limiting it to stream only from microphone and/or camera. 

Players 

A pair of players is used to control the data flow, and rendering. If canRead returns true, the application may call 

Player.start or Player.prefetch on the receiving player, and then the IMS engine starts receiving data and 

render. If canWrite returns true, the application may call Player.start or Player.prefetch for a sending player, 

and then the IMS engine starts sending data and render it. If the methods return false, then Player.start and 

Player.prefetch throw MediaException. 

If canRead and/or canWrite returns false while a receiving and/or sending player is started, respectively, the IMS 

engine calls Player.deallocate on those players. 

It may be the case, depending on the underlying session negotiation process, that the players got from the media 

are in an Unrealized or Realized state. When canRead and canWrite eventually returns true, the players are 

realized to enable player.start. 

On a started player, the application can call Player.stop and Player.deallocate even if the media mode 

properties (see Media interface) are still true. 

A call to Player.close aborts the data flow transfer for that player immediately. It is not possible to recover. 


StreamMedia requires no further initialization before calling Session.start or Session.update. However, the 

developer should consider calling setStreamType or setSource, and setPreferredQuality. 

Setting up streaming media session 

To setup the streaming media in a session, the originating endpoint goes through the following steps: 

• Creates streaming media objects 

• Set direction 

• Set the streaming media type for the objects, or set the data source if needed 



• start the session 

• get the players and start 

The terminating endpoint does the following in response to the invitation 

• Inspects the offered media components of the session 

• accept session 

• get the players and start 

Playback Examples 

Set up a bidirectional audio media 

try { 

myMedia = 

(StreamMedia)mySession.createMedia("StreamMedia", 


myMedia.setStreamType(STREAM_TYPE_AUDIO); 

myMedia.setSource("capture://audio"); 


pIn = myMedia.getReceivingPlayer(); 

pOut = myMedia.getSendingPlayer(); 

} catch (ImsException ie) { 

} 

Wait until the media flow mode changes to allow read and write. The code below can be placed in the 

MediaListener.modeChanged callback: 

if (myMedia.canRead()) { 

try { 

pIn.start(); 

} catch (MediaException me) { 

} 

} 


try { 

pOut.start(); 


} 

} 

Stream from a multiplexed file 

try { 

myMedia = 

(StreamMedia)mySession.createMedia("StreamMedia", Media.DIRECTION_SEND); 

myMedia.setStreamType(STREAM_TYPE_AUDIO_VIDEO); 

myMedia.setSource("file:///root/sample.mpg"); 


pOut = myMedia.getSendingPlayer(); 


} 

As before, the player is started in the MediaListener.modeChanged callback. 


try { 

pOut.start(); 


} 

} 

Putting a stream media on hold 



RFC 3264 An Offer/Answer Model Session Description Protocol [RFC3264] describes a procedure for putting 

media streams on hold, i.e. request the remote to (temporarily) stop sending a media flow. A send receive media 

will be given direction Send, and a Receive media gets the Inactive direction. In the code example below, myMedia 

had direction Send Receive. 

try { 

myMedia.setDirection(DIRECTION_SEND); 

mySendingPlayer.deallocate(); 

mySession.update(); 


} 

To resume myMedia, the application restores the original direction and then start players in for example the 

MediaListener.modeChanged callback: 

try { 

if (myMedia.canRead()) { 

myReceivingPlayer().start(); 

} 


mySendingPlayer().start(); 

} 


} 

Field Summary 

int QUALITY_HIGH 

Enables the platform to choose a higher quality codec during the negotiation of the media. 

int QUALITY_LOW 

Enables the platform to choose a lower quality codec during the negotiation of the media. 

int QUALITY_MEDIUM 

Enables the platform to choose a medium quality codec during the negotiation of the 

media. 

int STREAM_TYPE_AUDIO 

Indicates that the streaming will consist only of audio. 

int STREAM_TYPE_AUDIO_VIDEO 

Indicates that the streaming will consist of audio and video. 

int STREAM_TYPE_VIDEO 

Indicates that the streaming will consist only of video. 

Page 

163 

163 

163 

163 

163 

163 






javax.microedition.media.Player 

javax.microedition.media.Player 

int 

void 

getReceivingPlayer() 

Returns a Player initiated to render the receiving part of this Media. 

getSendingPlayer() 

Returns a Player initiated to source the sending part of this Media. 

getStreamType() 

Returns the stream type for the Media. 

setPreferredQuality(int quality) 

Sets a preferred quality of the media stream. 

Page 

165 

165 

164 

165 



void 

void 

setSource(String source) 

Sets the source to capture media from. 

setStreamType(int type) 

Sets the stream type for the Media. 

164 

164 




Field Detail 

QUALITY_LOW 

public static final int QUALITY_LOW 

Enables the platform to choose a lower quality codec during the negotiation of the media. 

QUALITY_MEDIUM 

public static final int QUALITY_MEDIUM 

Enables the platform to choose a medium quality codec during the negotiation of the media. 

QUALITY_HIGH 

public static final int QUALITY_HIGH 

Enables the platform to choose a higher quality codec during the negotiation of the media. 

STREAM_TYPE_AUDIO 

public static final int STREAM_TYPE_AUDIO 

Indicates that the streaming will consist only of audio. 

STREAM_TYPE_VIDEO 

public static final int STREAM_TYPE_VIDEO 

Indicates that the streaming will consist only of video. 

STREAM_TYPE_AUDIO_VIDEO 

public static final int STREAM_TYPE_AUDIO_VIDEO 

Indicates that the streaming will consist of audio and video. 



Method Detail 

setSource 

void setSource(String source) 

Sets the source to capture media from. If this method is not called, then the audio is sourced from a default 

microphone of the device, and video is sourced from a default camera. 

Supported sources: 

• capture:// 

• file:// 

device = "audio" / "video" / "audio_video" / dev_name 

dev_name = alphanumeric 

alphanumeric = 1*( ALPHA / DIGIT ) 

See [JSR135] for more information on the capture locator. 

See [JSR75] for more information on the file locator. 

Parameters: 

source - the source locator URI of media to be streamed 

Throws: 


IllegalArgumentException - if the syntax of the source argument is invalid or not supported 

setStreamType 

void setStreamType(int type) 

Sets the stream type for the Media. This is used as an indication for the IMS engine regarding which 

stream type to use for this media. 

If the stream type has not been set, it will default to STREAM_TYPE_AUDIO. 

Note: The use case for this method is when the application adds a StreamMedia to a session with direction 

set to DIRECTION_RECEIVE. In this case, the IMS engine does not know which kind of StreamMedia to use 

in the negotiation. If the setSource method conflicts with the stream type, the setSource method has 

priority. 

Parameters: 

type - the stream type 

Throws: 


IllegalArgumentException - if the type argument is not a valid identifier or not supported 

See Also: 

getStreamType() 

getStreamType 

int getStreamType() 

Returns the stream type for the Media. 



If the stream type has not been set, it will default to STREAM_TYPE_AUDIO. 

Returns: 

the stream type 

See Also: 

setStreamType(int) 

getReceivingPlayer 

javax.microedition.media.Player getReceivingPlayer() 


Returns a Player initiated to render the receiving part of this Media. The returned Player is in the 

REALIZED state. 

Returns: 

a Player 

Throws: 

java.io.IOException - if the exists property is false for the media 

getSendingPlayer 

javax.microedition.media.Player getSendingPlayer() 


Returns a Player initiated to source the sending part of this Media. The returned Player is in the 

REALIZED state. 

Returns: 

a Player 

Throws: 

java.io.IOException - if the exists property is false for the media 

setPreferredQuality 

void setPreferredQuality(int quality) 

Sets a preferred quality of the media stream. This method does not guarantee the desired quality but 

enables the platform during the media negotiation to select an appropriate quality of service if possible. 

Defaults to QUALITY_MEDIUM. 

Parameters: 

quality - the preferred quality 

Throws: 


IllegalArgumentException - if the quality argument is invalid 


Appendix A 

Appendix A: Implementation guidelines 

This chapter contains implementation best practice using the SIP, SDP and other protocols of IMS, to address 

interoperability between IMSAPI implementations and the IMS network. 

Classes, interfaces and methods are described and it is shown how these will behave and relate to the protocols 

and procedures used. The following specifications (and their references) should be considered normative where 

applicable: 

• 3GPP TS24.229 6.17.0, and the documents that it refers to 

• 3GPP TS24.229 7.11.0, only for the parts relevant to ICSI and IARI. 

Overview 

The IMSAPI is designed to be an abstraction of IMS concepts that allows implementing IMS applications, according 

to the application model described initially in the specification. 

The term IMS Engine is used in this chapter to refer to the IMS functionality of the device. It can be understood 

from the IMS application model employed in the JSR 281. For any given general IMS application, language and 

platform independent, the API divides the set of requirements in two: 

• Application-specific: The Java JSR 281 IMS application realizes requirements that map above the API. 

• IMS-specific: The IMS Engine realizes requirements that map below the API. 

The IMS engine maintains the fundamental distinction between the signaling and the media plane in the API. It 

manages the SIP transactions and dialogs according to the standards, formats SIP messages, and creates proper 

SDP payloads for sessions and media streams. 

SIP methods, with the transactions and dialogs they imply, have abstractions in the API. 

The core service object relates to IMS registration and the SIP REGISTER message. 

The service methods (the sub-interfaces to ServiceMethod) correspond to non-REGISTER SIP messages and, 

where applicable, the session oriented SDP lines, sent to remote endpoints, including the standardized 

transactions and dialogs that the standards imply. 

• Session - INVITE, UPDATE, BYE, CANCEL 

• Reference - REFER and NOTIFY 

• Subscription - SUBSCRIBE and NOTIFY 

• Publication - PUBLISH and NOTIFY 

• Capabilities - OPTIONS 

• PageMessage - MESSAGE 

The SIP INFO method has no representation in this API. 

An important design feature of the IMSAPI is its level of abstraction that hides protocol specific details from the 

developer. This means that an application cannot modify the SIP message sequences. Some support to access the 

contents of individual SIP messages is available in the Message interface. 

The media types (sub-interfaces to Media) are related to media streams and the media oriented SDP lines. The 

StreamMedia type is based on the RTP/AVP-profile, and the media content is handled in the IMS engine. The 

Framed media type is based on MSRP, where the IMS engine handles the MSRP protocol, and the application 


Appendix A 

handles the content. For BasicUnreliableMedia and BasicReliableMedia, the application implements a protocol 

on top of UDP and TCP, respectively. 

CoreService 

RFC: 3840, 3841, Caller preferences framework 

The IMSAPI core service object is related to IMS registration. A core service object is in an active state when it can 

be used to create service methods, and receive incoming ones. This can happen in two ways: 

• The application calls Connector.open(), 

• There is a MIDP Push registration with a proper imscore locator as connector string (or some other 

equivalent mechanism according to the Java profile). 

The IMS application Registry contains capabilities that are used in the caller preferences framework. This is the 

main mechanism to support multiple IMS applications. The IMS engine act as a proxy for the IMS applications. 

Related to the core service, the following tasks are included: 

• Behavior for startup and shutdown. 

• Creating the ‘Contact’-header. 

• Creating ‘Accept-Contact’ headers for outgoing requests. 

• Given an incoming request, route the request to the right core service based on the contents of the 

‘Accept-Contact’ header. 

These items are described: 

Startup 

Startup means the earliest point in time after the device is switched on, and the Java Application Management 

System (AMS) and the native IMS engine have started and are operational. 

At startup, the IMS engine sends a REGISTER message with the capabilities for the Push registered core services. 

If the IMS engine has already sent a REGISTER with the user's contact address, then this REGISTER updates that 

registration. Otherwise, the IMS engine uses this as the initial IMS registration. The procedures are according to 

standard. 

The implementation MUST maintain the registration (SIP REGISTER message to the registrar) with respect to the 

feature sets for all active core services at all times. The implementation must keep a model of what capabilities is 

currently registered, and maintain a mapping to individual active core services. Unnecessary signaling with 

REGISTER messages should be avoided. 

Update 

When IMS Engine performs a REGISTER refresh, this can take up to a few seconds depending on the update. If 

an application requests an update (i.e. via a Connector.open()) at the same time as the REGISTER refresh 

(update collision) the IMS Engine shall wait until to the REGISTER refresh is competed. 

Shutdown 

Shutdown is mainly a device specific matter. If there are no core services active, and hence no reason to maintain 

a model of what capabilities are registered, the IMS engine may stop maintaining the registration. 

Creating Contact header when a core service is activated. 

This section describes how to construct a ’Contact’ header with feature tags derived from the Registry contents in 

outgoing SIP messages. 

Purpose 

Update the ‘Contact’ header with features when a core service is activated from a Connector.open() call. The 

algorithm is also used for Push registered core services at startup, and in this case the algorithm updates the 

header successively for each core service. The IMS engine maintains the current ‘Contact’ header value, and this 

is the existing ‘Contact’ header value referred to below. The initial value for the ‘Contact’ header is device specific, 

where the IMS engine supplies with a contact URI, device specific feature tags, and q-value. The device may at the 

end of the algorithm remove any added feature tag that cannot be supported. 


Appendix A 

Description 

Given an existing ‘Contact’ header value, Registry and a core service, the algorithm goes through each capability 

carrying IMS property and adds feature tags to the ‘Contact’ header. Since other active core services may share 

the ‘Contact’, the algorithm counts references to each tag, to be examined when the ‘Contact’ header is modified 

again. As a side effect, the algorithm returns a flag that tells whether the header was changed. This flag can be 

used to avoid sending redundant REGISTER messages. 


Appendix A 

Definitions 

Feature or feature params 

an expression T on the form feature tag [ = tag-value ] 

Feature tag 

a token. For a Feature T, then its tag is denoted with T.tag 

Tag-value 

value for a tag. For a Feature T, then its value is denoted with T.value 

Boolean feature 

value is either false or true 

Enumerated feature 

one token within an enumeration 

Numeric value 

integer or rational 

Negation 

excluding the particular value 

Input to the algorithm 

• R – The Registry that belongs to the IMS application that owns the input Core service. 

• cs – The input core service name. 

• F – An existing ‘Contact’ header value. 

• F.ref[T] – Reference count for feature T used in F. 

Output 

• F – Updated ‘Contact’ header value. 

• F.ref[T] - Updated reference count of feature T used in F. 

• A Boolean flag update. 

Procedure 

Define operations on F.ref[T]: 

• Read with the expression F.ref[T] and can be numerically compared. 

• Incremented with F.ref[T]++ 

• Decremented with F.ref[T]— 

• Set to a numeric non-negative value x with F.ref[T] = x 

The operator F += T is defined as such: 

The feature T is added to the ‘Contact’ header value F ensuring that T is a member of the (equivalent) contact 

feature set for F. The reference is counted, and the update flag is set if F was changed. 

Procedure of F += T: 

• If F already includes T, then F is unchanged. Apply F.ref[T]++ 

• If T is a (non-negated) Boolean feature, then suffix F with ; and append T.tag to that (so F = F + ";" + T.tag). 

Set F.ref[T] = 1. Set update = true 

• If T is an enumerated feature then: 

If F includes values for T.tag, then suffix the values with , and append T.value to those. 

Else append ;T to F. 

Note that there are no cases for numeric and negated values. 


Appendix A 

Main algorithm: 

Set update = false 

For the Registry R 

For each IMS property p in R: 

If p is StreamMedia property then 

If p is empty or p has both Audio and Video, then F += video and F += audio 

Else if Video is in p, then F += video 

Else If Audio is in p, then F += audio 

Else should not happen 

Else if p is FramedMedia then 

F += message 

Else if p is BasicMedia then 

For each content type xxx/yyy in p 

If xxx is application then 

F += application 

F += sub_apptype = yyy (this step is optional) 

Else if xxx is video then F += video 

Else if xxx is audio then F += audio 

Else if p is Event then 

For each event e in p 

F += events= e 

Else if p is a CoreService with the name cs then 

For each iari in p do 

F += +g.3gpp.iari_ref = iari 

For each icsi in p do 

F += +g.3gpp.icsi_ref = icsi 

(explicit and require flags are not placed in F) 

This step could also be used to create P-Preferred-Service SIP headers to the P-CSCF 

For each FT in p do 

F += FT 

(explicit and require flags are not placed in F) 

Else p is some other property, and F is unchanged 

The device removes all feature tags from F that cannot be supported 

Creating Contact header when a core service is closed 

Purpose 

Remove features from the ‘Contact’ header when a core service is closed. 

Description 

Given an existing ‘Contact’ header value, Registry and an active core service, the algorithm goes through each 

capability carrying IMS property and removes obsoleted features from the header. Because other core services 

may share the contact, the algorithm counts references to each feature, such that support for others remains valid. 

As a side effect, the algorithm returns a flag that tells whether the header was changed. The algorithm is a small 

modification of the activating case, and only the details for the new case are shown. 

Procedure 

Procedure of F -= T: 

• If F already includes T, then apply F.ref[T]--. If F.ref[T] == 0 then remove T from F. 

Main algorithm: 

The algorithm is the same as for the activating case, except that the += operator is replaced with the -= operator. 

Creating Accept-Contact header in outgoing non-REGISTER 

Given a set of existing ’Accept-Contact’ headers, a Registry, and a core service, the algorithm goes through the 

capability carrying IMS properties and extends the set accordingly. The headers are put in outgoing requests from 

that core service. 


Appendix A 

Procedure 

Note that the ‘Accept-Contact’ headers in Fs must all match a contact for a call to succeed. When a term T is 

added to Fs, some existing Accept-Contact header in Fs will preferably include it with a conjunction, or a new 

‘Accept-Contact’ is created and put in Fs. The reason for doing this is that each ‘Accept-Contact’ header must be 

internally consistent. This is expected to happen rather frequently in JSR 281, where the +g.3gpp.iari-ref and 

+g.3gpp.icsi-ref tags have several values (ICSI + IARI) that all must be matched to the remote. It is also the 

case that the ‘require’ and ‘explicit’ flags operate on all feature parameters in the ’Accept-Contact’ header, which 

may force extra headers to the Fs. 

The operator Fs

Appendix A 

{ "Write", "P-ImageIncluded" }, 

{ "Read", "P-ImageIncluded" }, 

{ "Cap", "Framed", "Req_Resp", "a=max-size:4096" } 

}; 

It will generate two ‘Accept-Contact’ headers. Reason for the second one is the ‘require’ tag that applies to the IARI, 

but not to other features: 

• Accept-Contact: *; application; app_subtype=”myChess”; message;events="Presence" 

• Accept-Contact: *; +g.3gpp.iari_ref="urn:IMSAPI:com.myCompany.iari.myChess"; require 

Routing and processing of an Accept-Contact header 

Purpose 

Route incoming request to the right active core service. 

Description 

If the incoming SIP message lacks ‘Accept-contact’ headers, then the request is passed to the device for further 

processing outside the scope of this specification. 

Given an incoming SIP message with ‘Accept-Contact’ headers, the core service that a callback should be 

generated from is identified. The procedure is based on the Caller Preferences framework [RFC 3841], where each 

active core service is treated as a candidate contact. The procedure works by going through each feature in 

each ’Accept-Contact’ header for all candidate core services. This process can result in a core service being 

excluded as a potential contact. If it is kept, it is assigned a caller preference score. The core service that ranks 

highest receives the call. 

Definitions 

R.prop 

gets the value of IMS property with name prop from the Registry R 

npf 

number of features in ‘Accept-Contact’ 

ncf 

number of ‘Accept-Contact’ feature tags where the Registry implies the same tag 

nvm 

number of value matches between ‘Accept-Contact’ and Registry for a feature tag 

nvm_cs 

number of matches for IARI, ICSI and Feature Tags fields in the CoreService property for a given cs 

nf_cs 

total number of features implied from IARI, ICSI and Feature Tags fields in the CoreService property for a 

given cs 

Score[h] 

an Accept-Contact header score for the cs 

Procedure 

The test V1 == V2 is defined as such: 

• If V1 or V2 are not atomic values, then Fail. 

• If V1 and V2 not the same types then Fail. 

• If V1 and V2 are Boolean or enumerated values, then Success if they are string-equal case insensitive. 

• If V1 and V2 are IARI or ICSI, then Success if they are lexically equvalence according to RFC 2141 URN 

Syntax. 


Appendix A 

• If V1 and V2 are other types of strings, then Success if they are string-equal case sensitive. 


Appendix A 

The test VA is_in VR is defined as such: 

• If VA is not a feature value from an ‘Accept-Contact’ header, or VR is not a value from a Registry property, 

then Fail. Note: VA and VR can have several values. 

• For all values a in VA until Success 

If there is a value r in VR such that a == r, then Success. 

else if a is on the form !b (negation), then if there is no value r in VR such that b == r, then Success 

else Fail. 

Main algorithm 

For each registry R with an active core service cs 

set nvm_cs to 0 

compute nf_cs for cs 

For each accept-contact header 

Set npf, ncf, nvm to 0 

For each feature f in that accept-contact 

npf ++ 

If f.tag is video then 

if Video is in R.Stream or video is in R.Basic then 

ncf++ 

nvm++ 

else if f.tag is audio then 

if Audio is in R.Stream or audio is in R.Basic then 

ncf++ 

nvm++ 

else if f.tag is message 

if R.Framed is defined then 

ncf++ 

nvm++ 

else if f.tag is events 

if R.Event is defined then 

ncf++ 

if f.value is_in R.Event then 

nvm++ 

else if f.tag is application 

if application is a top-level type in R.Basic then 

ncf++ 

nvm++ 

else if f.tag is app_subtype 

if application is a top-level type in R.Basic then 

ncf++ 

if some value of f occurs as sub-level of an application content type in R.Basic then 

nvm++ 

else if f.tag is +g.3gpp.iari_ref 

if R.CoreService contains an iari 

ncf++ 

if f.value is_in iari for R.CoreService with name cs then 

nvm++ 

nvm_cs++ 

else if f.tag is +g.3gpp.icsi_ref 

if R.CoreService contains some ICSI 

ncf++ 

if f.value is_in icsi for R.CoreService with name cs then 

nvm++ 

nvm_cs++ 

# This case is for backwards compatibility to older representation of ICSI and IARI 

else if f.tag is +g.3gpp.app_ref 

if R.CoreService contains some IARI or some ICSI 

ncf++ 

if f.value is_in iari or f.value is_in icsi for R.CoreService with name cs then 

nvm++ 

nvm_cs++ 


Appendix A 

else if f.tag is contained in Feature Tags for R.CoreService with name cs 

ncf++ 

let g be that feature of Feature Tags, where f.tag is g.tag 

if f.value is_in g.value 

nvm++ 

nvm_cs++ 

else if f.tag is handled by the device 

ncf++ 

if f.value is allowed in the device for f.tag 

nvm++ 

else 

(No action) 

when an ‘Accept-Contact’ header has been processed for this cs: 

set Score[h] = nvm/npf 

if Score[h] < 1.0 then 

if the ‘require’ flag is present for this ‘Accept-Contact’ header, then 

cs is dropped, and next candidate cs is tried. 

else if the ‘explicit’ flag is present, then 

set Score[h] = 0; 

when all headers for a cs is done: 

if nvm_cs < nf_cs then 

cs is dropped 

else 

caller preferences score of this cs (Sc[cs] ) is the arithmetic average of Score[h] for all its ‘Accept-Contact’ 

headers h 

when all cs have been processed: 

If the device has an internal policy to override Sc[cs] for some cs, then 

Let Sc[cs] = 1.0, for all such cs. 

If the device supports an internal callee preference ordering by q-value (q[cs]), then 

sort all cs based on q[cs], and for those that have the same q[cs] sort on Sc[cs] 

else 

sort only on Sc[cs] 

select the best cs to receive the request 

Processing of Reject-Contact header 

The above algorithm can be used to process ‘Reject-Contact’ headers by dropping all cs with Sc[cs] == 1 when 

processing features for reject before applying the algorithm for the ‘Accept-Contact’ case. 

Processing of Request-Disposition header 

The RFC 3840/3841 discusses the ‘Request-Disposition’ header and this may appear in incoming requests. The 

device shall not process directives contained in the header. If the cs that takes the request subsequently rejects it, 

then this means the request is rejected from the device altogether, and not just from that cs or IMS application. 

Internal preference handling 

The device may implement a callee preference among core services (core service q-value). There are no interfaces 

for this in the JSR 281 APIs. 

SIP messages and contact headers 

The SIP REGISTER MUST have a contact header with the contact address and the feature tags as constructed by 

the algorithm above. This means that the JSR 281 implementation requires the server to support caller 

preferences. 

The contact header must also be placed in the following SIP methods: INVITE, NOTIFY, OPTIONS, SUBSCRIBE, 

UPDATE, REGISTER, REFER, PUBLISH. 


Appendix A 


When the initial registration has been done, the Public User Identities (SIP URI user identities) returned via the 

getUserIdentities() method are taken from the ‘P-Associated-URI’ header of the REGISTER response. If this 

header cannot be retrieved (for whatever reason) then the method should be based on the collection of all public 

user identities that are made known to the device via the reg event package. The first URI in the list is the default 

user identity for the user. The application cannot test whether a certain user id is registered or not; it suffices for it 

to know which are usable for creating services. Typical use of the user id is that some can be used as input to 

service creation. User identities can also in general be provisioned by some mechanism outside this specification. 

Note that getting the list user identities can only be done while the state is connected. Creating core services can in 

general be done at any time. If there is no registration when a service is created, the implementation MUST try to 

make one. 

ConnectionState.isConnected 

Returns true if the device has an IMS registration active. 

ConnectionState.getUserIdentities 

This is a list of all identities that the device knows about for the current user, registered or not. The sources for the 

list may include the ‘P-Associated-URI’ header, registration events, and user identities otherwise provisioned to the 

user. 


Appendix A 

ServiceMethod 

With the ServiceMethod interface it is possible to add headers and body parts to outgoing SIP request messages 

and to inspect previously sent and received SIP messages (both request and responses). 

The getNextRequest() method will give a handle to the next outgoing SIP request message in the corresponding 

subclassed service method. Calling this method twice before the message is sent will give the same handle. The 

SIP request methods that can be manipulated are defined in the Message interface, for example SESSION_START 

that has the triggering interface method Session.start. 

The getNextResponse()method gives a handle to the next SIP response message. Since the response depends 

on a request message, and on a triggering action by an application, there are only a few places in the API where it 

is possible and meaningful for the application to call the method. In Table 1, the triggering interface methods are 

listed, and the response message is what is sent directly afterwards. See also Figure 1a where triggering methods 

and responses are shown in bold face. 

If getNextResponse()method is called and is not followed by any of the triggering methods listed below, then all 

changes made to the response message are discarded. 

Call back method 

Triggering interface method SIP Response 

CoreServiceListener.sessionInvitationReceived Session.accept() 

200 Ok 

CoreServiceListener.sessionInvitationReceived Session.reject() 

486 Busy here 

CoreServiceListener.sessionUpdateReceived Session.accept() 200 Ok 

CoreServiceListener.sessionUpdateReceived Session.reject() 486 Busy here 

Table 1: Triggering interface methods and with available SIP response messages 

If a SIP request message was sent/received successfully and it is connected to an identifier in the Message 

interface, it should be stored in the IMS engine. Only the last SIP request message for each Message identifier has 

to be stored. The same logic applies to SIP response messages. All SIP responses to the SIP request message 

that has a Message identifier should be stored, but again only the SIP responses to the last SIP request of each 

Message identifier. 

Table 2 below shows the mapping for a Message identifier and the triggering interface method. It also shows which 

SIP method that is expected to be sent. SESSION_UPDATE and SESSION_TERMINATE can use one of two SIP 

methods depending on the situation. 

Message identifier 

CAPABILITIES_QUERY 

Triggering interface method SIP method 

Capabilities.queryCapabilities() OPTIONS 

PAGEMESSAGE_SEND PageMessage.send() MESSAGE 

PUBLICATION_PUBLISH Publication.publish() PUBLISH 

PUBLICATION_UNPUBLISH Publication.unpublish() PUBLISH 

REFERENCE_REFER Reference.refer() REFER 

SESSION_START Session.start() INVITE 

SESSION_UPDATE Session.update() INVITE,UPDATE 

SESSION_TERMINATE Session.terminate() BYE,CANCEL 

SUBSCRIPTION_POLL Subscription.poll() SUBSCRIBE 

SUBSCRIPTION_SUBSCRIBE Subscription.subscribe() SUBSCRIBE 

SUBSCRIPTION_UNSUBSCRIBE Subscription.unsubscribe() 

Table 2: Message identifiers and SIP messages to store 

SUBSCRIBE 

Consider Figure 1a below. If the application calls getPreviousResponses(SESSION_START) at the 

sessionAlerting() callback, the following SIP responses should be returned in an array: 183 Session Progress 


Appendix A 

and 180 Ringing (100 Trying may also reside in the array, but it is not shown in the figure). The 183 Session 

Progress will reside in the first slot in the array since it was the first response to the SIP INVITE request message. If 

the application calls getPreviousRequest(SESSION_START) at the SessionInvitationReceived() callback, the 

SIP INVITE request message will be returned. 

The algorithm for computing ‘Contact’ and ‘Accept-Contact’ headers described in the section on core service apply 

to outgoing SIP messages for all service methods where applicable. For incoming SIP messages, not part of an 

existing dialog, the routing algorithm is used to find the best core service to generate the callback from. 

getRemoteUserId 

This method returns the trusted user identity or identities of the remote endpoint. The value is an array of all 

P-Asserted-Identity header values (display name and URI) that can be found in the SIP message exchanged with 

the remote in the order they have been found. 

User identity management for Core service and Service methods 

The device decides on an appropriate default public user identity and a default display name to use with the URI of 

the identity whenever supported. If the identity has not been registered, the device must make sure it has been 

registered at the time the first Connector.open() is called and the device must also subscribe to the reg event 

package. The default identity can be overridden by the application supplying a value for the ‘userId=’ parameter 

in the argument to Connector.open(). If this public user identity is not registered, explicitly or implicitly, then the 

device shall attempt to register it if explicit registration of additional public user identities according to the procedure 

of [24.229] is supported. In any case, the identity and display name shall be the default to put in the 

‘P-Preferred-Identity’ header in SIP messages for service methods eventually originating from the local endpoint 

and core service object. 

The getLocalUserId() method on the CoreService interface returns the overridden user identity instead of the 

default user identity (first in the 'P-Associated-URI' header). Again, display names shall be supported. 

The from argument in service methods is mapped to the ‘From:’ header in the outgoing SIP message for the 

service method. The requirements that RFC3261 places on the contents of the ‘From:’ header apply to the from 

argument as well, except for a ‘tag’ parameter that the application is not allowed to insert. 

The to argument maps similarly to the ‘To:’ header, and stripped from display name it also form the ‘Request-URI’ 

of the start line of the request. Hence, the to argument bears more significance to the service method than the 

‘To:’ header alone for the SIP request. 

Session 

Handling of sessions builds on the core SIP specifications, and 3GPP TS 24.229 Rel 6. 

RFC: 3261, SIP: Session Initiation Protocol 

RFC: 3264, An Offer/Answer Model with the Session Description Protocol (SDP) 

RFC: 3312, Integration of Resource Management and SIP 

Start a session 

When MO call session.start() the IMS engine prepares the SDP offer with the media and sends that to the 

remote endpoint in the initial SIP INVITE message according to the standards. The offer has an application 

independent part that relates to the media components of the session, and an application-dependent part that 

relates to SDP lines that the application has set using SessionDescriptor and MediaDescriptor interfaces. 

Session setup with and without the precondition extension are supported, and the distinction is kept transparent to 

the application. The implementation decides which to use. 

If the negotiation (and possible resource reservation) was successful the MT application is notified via the 

sessionInvitationReceived() callback. 


Appendix A 

Figure 1a: Sequence for preconditional session setup and terminate. Bold sequences show the SIP messages that 

were triggered as a direct effect from an application using certain parts of the API, so called application-triggered 

messages. 


Appendix A 

Figure 1b: Sequence for session setup without preconditions including terminate. 

Terminate a session 

When calling session.terminate() the IMS engine will send a SIP BYE or CANCEL request message to the 

remote endpoint and request that the session should be terminated. 

• SIP CANCEL should be sent if a final response has not been received for the initial SIP INVITE message 

that was sent in session.start(). The remote endpoint should respond with 200 OK for the SIP CANCEL 

followed by a 487 Request Terminated on the SIP INVITE message. For the application that called 

session.terminate, sessionListener.sessionTerminated() is called, and on the other 

endpoint sessionListener.startFailed() is called. This happens regardless of MO or MT session. 

• SIP BYE should be sent if the session has been established. On both endpoints 

sessionListener.sessionTerminated() is called. 

• If the network terminates the session before session is established, sessionListener.startFailed() is called 

on both endpoints. If it does this after session is established, sessionListener.sessionTerminated() is called 

on both endpoints. 

Update a session 

A session can be updated due to only a number of reasons. The type of update decides how the SIP signaling 

should be realized and which listener methods should be called back in response to the update that has been 

made. Below follows a listing of cases and how they should be dealt with: 


Appendix A 

1 MO app calls session.update() with added media: 

Use SIP reINVITE (possibly with resource reservation, if that is needed) on MO. MT requires reINVITE and 

should reject UPDATE. Make call backs on MT side sessionUpdateReceived. The MT app must process 

both the offer and accept the update. Call sessionUpdated when SIP ACK is sent and received. (See Figure 

2a and 2b) 

2 MO app calls session.update() with an updated application-specific offer: 

Use reINVITE on MO to send the offer. MT requires reINVITE and should reject UPDATE. Do not call 

sessionUpdateReceived. Call sessionUpdated. (see Figure 2c) 

3 MO app calls session.update() with removed media and/or changed media directions: 

Use SIP UPDATE on MO. On MT accept reINVITE and UPDATE. Call sessionUpdated only. (See figure 2d) 

4 MO IMS engine, and not the app, calls session.update() with an application-independent update. The offer 

include an updated b-line, if changes to that is reserved in the current media profile. 

IMS engine shall use SIP UPDATE, and no listener on either endpoint should be called. (See figure 2e) 

The cases above are listed in decreasing order of impact. There may be a mix of cases in one update, and then the 

following applies: Only a mix consists of cases in classes 1-3 is allowed, and if so it is handled according to the 

case with lowest number. Class 4 update MUST be handled separately. If there is an ongoing update in class 4, 

and an app-initiated update (cases 1-3) occurs, then that shall be queued until the class 4 update is completed, and 

vice versa. If MT has an ongoing update, it shall reject the update until the current one completes. 

For application-initiated updates (1-3) are handled uch that if a session is updated with several changes the change 

that tops the list decides the type of update. 

Figure 2a: Sequence for session update using SIP reINVITE with resource reservation. The MT app is to answer 

the updated offer and confirm the updated session. 


Appendix A 

Figure 2b: Sequence for session update using SIP reINVITE without resource reservation. The MT app is to 

answer the updated offer and confirm the updated session. 

Figure 2c: Sequence for session update with SIP reINVITE not requiring resource reservation, useful for example 

when MO app made only an updated application-specific offer. 


Appendix A 

Figure 2d: Sequence for session update with SIP UPDATE, useful when MO app made updates where MT does 

not confirm the change. 

Figure 2e: Sequence for session update with SIP UPDATE, where IMS engines on both sides need not involve the 

application at all. 

Capabilities 

RFC: 3840, Indicating User Agent Capabilities in the Session Initiation Protocol (SIP) 

Requesting capabilities 

When calling Capabilities.queryCapabilities() the IMS engine will send a SIP OPTIONS request message to 

the remote endpoint. When the remote endpoints IMS engine receives the SIP OPTIONS request it will construct a 

response message and respond. Note that this request will not trigger any application to be launched and the user 

behind the IMS engine will not be aware of this request. 

Figure 3: Sequence for queryCapabilities 

getRemoteUserIdentities 

This method will return all SIP & TEL URI:s that are found in the ‘Contact’ header. For example 

mailto:carol@chicago.com must not be returned. 


Appendix A 

hasCapabilities 

This method checks whether the remote device includes the same capabilities as the local IMS application (and 

core service) given an imscore:// connector string argument. If there is a match this method will return true. 

The comparison is made only on matching feature tags. Use the received ‘Contact’ header as input to the contact 

header construction algorithm described earlier. If the output header is the same as the input, true is returned. 

If the flag to include SDP is set in the queryCapabilities() method call, then the SDP that the IMS engine uses 

for OPTIONS responses is used as body in the outgoing request. 

PageMessage 

RFC: 3428, Session Initiation Protocol (SIP) Extension for Instant Messaging 

Send a PageMessage 

When calling PageMessage.send(content, contentType) the IMS engine will send a SIP MESSAGE request 

message to the remote endpoint. 

Figure 4: Sequence for send 


Appendix A 

Publication 

RFC: 3903, Session Initiation Protocol (SIP) Extension for Event State Publication 

Publish 

This method will send a SIP PUBLISH request message to the remote endpoint. The IMS engine is responsible to 

refresh the publication and make sure that the publication does not expire. If the publication is about to be expired, 

the IMS engine must prepare a SIP PUBLISH request message with the same added headers and body that was 

set for the initial message and refresh the publication. 

Figure 5: Sequence for publish and unpublish 

Unpublish 

This method will send a SIP PUBLISH request message to the remote endpoint. The 'Expires' header will be set to 

zero and thereby terminating the publication. 

Reference 

RFC: 3515, The Session Initiation Protocol (SIP) Refer Method 

A typical reference involes three user agents, the local endpoint that creates the reference and sends it, the remote 

endpoint that receives the REFER request and creates a service method based on the reference method and 

sends that to a third party. 


Appendix A 

Figure 6: Sequence for a minimal refer implementation 

Sending a Reference 

The method Reference.refer() will send a SIP REFER request message to a remote endpoint. The 'Refer-To' 

header field must be set to the third party that the remote endpoint will refer to. 

Receiving a Reference 

When a well-formed SIP REFER request is received by the remote endpoint the IMS engine should respond with 

202 Accepted. The IMS engine is also responsible to make a implicit subscription to the ‘refer’ event and 

immediately send a SIP NOTIFY to the endpoint that issued the REFER request. 

Accepting a Reference 

The remote endpoint is now responsible to create a service method based on the refer method to the third party 

specified by the 'Refer-To' user identity. 

Connecting a Reference 

The method connectReferMethod() will connect a service method with the third party specified by the 'Refer-To' 

header field. This method enables the IMS engine to identify the third party and send notifications to the local 

endpoint when the reference is terminated. 

Replaces header 

The method setReplaces() accepts the contents of the o= line of the SDP. The implementation shall convert this 

to the format described in RFC3891 for the local device. For getReplaces() it is the opposite conversion. 


Appendix A 

Subscription 

RFC: 3265, Session Initiation Protocol (SIP) Specific Event Notification 

Subscribe 

This method will send a SIP SUBSCRIBE request message to the remote endpoint. The IMS engine is responsible 

to refresh the subscription and make sure that the subscription does not expire. If the subscription is about to be 

expired, the IMS engine must prepare a SIP SUBSCRIBE request message with the same added headers and 

body that was set for the initial message and refresh the subscription. 

Figure 7: Sequence for subscribe and unsubscribe 

Update 

When a Subscription needs to perform a refresh, this can take up to a few seconds depending on the refresh. If an 

Subscription also requests an update (i.e. via a subscribe()) at the same time as the refresh (update collision) the 

subscribe call shall wait until the Subscription refresh is completed. 

Unsubscribe 

This method will send a SIP SUBSCRIBE request message to the remote endpoint with the 'Expires' header set to 

zero and thereby terminating the subscription. The IMS engine will then receive a SIP NOTIFY that terminates the 

subscription and the IMS engine should invoke the subscriptionNotify() callback followed by the 

subscriptionTerminated() callback. 

Anonymize 


Appendix A 

Anonymity for MO 

The originating application anonymizes on a per service method basis. It is not possible to anonymize on core 

service level. 

When the application creates a service method using the CoreService interface and provides a from argument that 

includes the anonymous host name of anonymous.invalid, the implementation shall anonymize the service 

method using a privacy type value of “id” and perform anonymization of SIP requests and responses part of the 

service method as further described in RFC3325. 

Anonymity for MT 

No support to anonymize responses from the MT side. 

Media profiles 

Introduction and rationale 

The concept of [streaming] media profiles was introduced in the JSR 281 because the set of possible devices that 

can implement the 281 differ in their media capabilities. This is perhaps most obvious for streaming media where 

the JSR features an API of high abstraction level, for example: 

• Details of data transport in RTP and RTCP streams are hidden from the application. 

• SDP negotiation mechanism for media offer is hidden. 

• Setting up network connections with required quality-of-service is managed by the IMS engine. 

• Usage of MIDP players, not exposing the data streams to Java space. 

The JSR 281 Media, StreamMedia and MediaDescriptor interfaces do not specify the implementation 

behaviour. It leaves a considerable space open for further requirements. That space not open to applications to 

specify because it makes the specification hard to use, making third party developers required to be standards 

experts. 

If it would be left unspecified, it is harmful for portability of applications from a Java perspective, and interoperability 

from an IMS perspective. If it would be unambiguously specified in the JSR implementation, the set of devices 

possible for the JSR to target would shrink to only a small set. 

There are several ways in SIP and IMS today can differentiate and manage variation among SIP and IMS devices 

in terms of their capabilities: 

• The SDP offer/answer model, where the endpoints negotiate to a common set of capabilities on a per session 

basis, for example the codecs in media offers. 

• Using separate URIs destined to reach endpoints with certain characteristics, for example a voice mail server 

has its own URI. 

• Using the caller preferences framework where an originating endpoint can make a statement for preferred 

characteristics of the terminating endpoint. 

Media handling is standardized in IMS for a particular service or area of similar services. Since devices are 

developed to support certain services, the media profiles in JSR 281 are based on specification standards. Hence, 

media profiles come close to services that are usually given a feature tag (e.g. ICSI) that indicates that media 

profiles would be handled within caller preferences. The IMS application in JSR 281 defines the media profile that 

MUST be used for its composed capability (ICSI, IARI, other other feature tag) in its Registry. An application 

installed to a device that lacks the required media profile will not execute because of the lack of media capability. 

Note that the media profiles do not have their own feature tags as this would require further standardization, but 

rather it is the application that picks the needed profile to realize its capability. 

Taken into the caller preferences framework means the following: 

• The originating endpoint having a certain feature tag prefers to reach a remote endpoint with the same feature 

tag in its session. The definition of the feature tag common for both endpoints, means the media profile is 

common as well. This will also work for IMS applications that are not using the JSR 281 since there is a 

standard behind the media profile. 

For each installed application, it is known which profile it uses. This solves the portability problem for Java. Each 

installed application makes sure it reaches a remote application with the same feature tag. This solves the 

interoperability issue for IMS. 


Appendix A 

Common procedures 

The application Registry sets up a composed capability in the CoreService property and a media profile in the 

mprof property. This is how the required dependency between a capability and a profile is expressed. If the device 

cannot create the dependency, the application cannot be interoperable. 

Codecs 

On the MO side for session setup, the IMS engine MUST place all mandatory codecs of the profile for the media 

stream in the SDP offer. All optional codecs in the profile that the device supports SHOULD be offered as well. 

Codecs not part of the profile MUST NOT be offered even if they could be used for the media type. On the resulting 

set of codecs, the device applies the value of setPreferredQuality to obtain an ordering of the codecs within 

the offer according to preference. That ordering is device-specific. 

On the MT side, following the standards, the IMS engine removes unsupported codecs and MUST remove offered 

codecs NOT part of the profile. 

Quality of service 

Any statement of network bitrate and delay applies as the device sets up network connections to transport media. 

This is mostly a matter for the local device. 

SDP attributes 

SDP attributes that are part of the profile are reserved to the IMS engine. This means that the application cannot 

access them in Sessiondescriptor and MediaDescriptor. Any values or negotiation rules for SDP lines and 

attributes of the profile are managed in the IMS engine part of its support for the profile. This also includes any 

extra SIP signaling related to the media and specific for the profile. 

Feature Tags 

Sometimes a standard for a profile contains service or application-related feature tags where the media profile is 

expected to be used. This is exempt from the IMS engine, and it is up to the application to make the association 

between the media profile and feature tags as mentioned above. 

Terminal capability requirements 

Some profiles may express certain other hardware-related device capabilities in order to realize the profile. Such 

requirements are placed here as well. 

Basic profile “Basic” 

If the device implements [26.235], then it supports the Basic Profile. 

MMTel profile “MMTel” 

If the device implements [26.114], then it supports the MMTel Profile. 

The IMS engine shall implement the video adaptation as per [26.114, ch 10.3] 

Media handling 

The implementation shall process media according to the guidelines below. 

Media flow properties 

‘exists’ is true when there is a socket (or equivalent) created. When it closes ‘exists’ is false. ‘canRead’ and 

‘canWrite’ assume values as described in the API based on mode factor conditions that all must be fulfilled. Data 

availability is one factor, and for 

‘canRead’ for other types of media depends less on data availability. It is set to true as soon as the first data 

packets destined for the application arrive at the socket. Subsequent pauses in the data transfer shall not make 

‘canRead’ set to false, unless it is known that an IO error has occurred that causes transfer interrupt. 

Implementations shall prepare their media flows bidirectionally, even if the media is unidirectional. This is because 

the direction can later be renegotiated. 

When the session is terminated, the implementation shall allow the application to read any locally buffered data. 


Appendix A 

The MediaListener.modeChanged() call back shall be applied for all changes of the mode properties except when 

the session is terminated reported to the application via a call to SessionListener.startFailed() or 

SessionListener.sessionTerminated(). 

When the application calls Media.setMediaListener, the call back shall be applied directly afterwards. 


BasicUnreliableMedia is based on UDP, and the proto field of the SDP is ‘udp’. The ‘exists’ property is true 

whenever the local device starts listening for incoming udp traffic on a server socket. Due to the nature of udp, 

sending does not affect ‘exists’ property. 


BasicUnreliableMedia is based on TCP, and the proto field of the SDP is ‘tcp’. The ‘exists’ property is true 

whenever a tcp socket connection is established, regardless of the passive or active role used in TCP connection 

setup. 

StreamMedia 

StreamMedia is based on RTP, and the proto field is RTP/AVP. The ‘exists’ property is true whenever the RTP 

mechanisms of the device are operational. 

Data availability enables ‘canRead’ whenever there is data in the incoming buffers that can be rendered. There is 

no requirement that the media must be in an active state for this to happen. This enables the application to start 

playing out any received media before the session goes to established state, and will mitigate the risk of losing 

initial data. Data availability enables ‘canWrite’ when the source for StreamMedia starts delivering renderable data. 

If the source stops or delivers EOF, then ‘canWrite’ becomes false. 

FramedMedia 

Framed media is based on MSRP protocol of [RFC4975] and the proto field is TCP/MSRP. If the ‘connection’ 

Registry property is not defined for the core service that the session is created from with a FramedMedia, then the 

[draft-ietf-simple-msrp-acm-00] shall be followed. The FramedMediaListener.transferProgress() listener 

method available at both the sending and receiving endpoints shall be called between the message chunks 

sent/received. That is, if there after having sent/received a message chunk there remains more chunks, then 

FramedMediaListener.transferProgress() shall be called. 

The IMS engine shall manage sending of bodyless requests according to RFC4975. Bodyless requests shall not be 

visible for sending or receiving applications. 

Error handling 

In the case of communication problems, the IMS engine should use adequate timeouts and retransmissions in 

order to reestablish the communication. If the communication could not be reestablished the IMS engine should act 

according to the following. 

Loss of network, no communication with proxy 

The application has a non open service 

• The application is notified with imsDisconnected(). 

The application has an open service 

• The service will be closed and notified with serviceClosed() in the case of a CoreService. 


The application has an open service and a service method 

• The corresponding service method is terminated, for example sessionTerminated(), 

subscriptionTerminated(). 

• The service will be closed and notified with serviceClosed() in the case of a CoreService. 


Appendix A 


Loss of network, no communication with remote endpoint 

If the communication with the remote endpoint cannot be reestablished the application should be notified through 

the corresponding service method. For example if the service method is a Session, sessionTerminated() should 

be invoked. 

Loss of Media connection 

• BasicUnreliableMedia - Fire and forget. IOException may be thrown if the IMS engine detects loss of 

Media connection. 

• BasicReliableMedia – connectionError() is invoked on BasicReliableMediaListener. IOException 

is thrown when the application tries to read/write to streams. 

• FramedMedia – connectionError() is invoked on FramedMediaListener. If the application still tries to 

send data deliveryFailure() is invoked. 

• StreamMedia - Exception is thrown from the Player. 

Reestablishment of communication 

When the IMS engine is able to reestablish the connection to the IMS network, the IMS engine should invoke 

imsConnected() on the ConnectionStateListener. The application must create and open new services, this in 

not done by the IMS engine. 

Quality of Service guidelines 

This sections gives guidance on how to realize quality of service in the UMTS access network for the types of 

media supported in the IMSAPI. 

StreamMedia 

QoS for StreamMedia follows the procedures in 3GPP standards. The API covers the whole streaming functionality 

where the IMS application can only start and stop the session. The IMS engine derives required bitrate and delay 

characteristics from its knowledge of the media format and codecs of the session. 

At session initiation (i.e. where originating endpoint creates the initial SDP offer), the IMS engine shall use the 

SetPreferredQuality as a hint to make an initial ordering of codecs in terms of the perceived quality. For high quality, 

the codec considered to give the highest perceived quality on the local device should be placed first on the offer, 

then the medium codec, and last the low quality codec. For medium, a medium quality codec is placed first followed 

by low, then high. For low, the lowest quality is preferred, then followed by medium and then high. 

When the session negotiation is completed where codecs have been selected, both endpoints enter the resource 

reservation phase. 

The IMS engine shall assign proper UMTS QoS parameters to the PDP contexts created or modified based on its 

knowledge of the session as described in [24.229, chapter 6.1]. A mapping procedure is specified in [29.213, 

Chapter 6.5]. It is up to the QoS management of the local device to determine whether the device actually supports 

the desired QoS at the moment, considering the network conditions and other usage of the device. 

In summary, streaming class is mandatory, conversational is optional. 

FramedMedia 

For FramedMedia there is in the API no information whether the session is going to be used for file transfer or an 

interactive chat, awaiting further standardization in this area. 

The background class is mandatory to support, and the conversational is optional. It is implementation-specific to 

set a priority. 


Appendix A 

BasicMedia 

BasicUnreliableMedia is an interface to the UDP protocol, and the BasicReliableMedia is TCP. The IMS application 

is responsible for realizing protocols and codecs part of its code. Hence, the application specifies its QoS 

requirements as well. This is done in the Registry Qos property of the CoreService. 

The implementation uses the flowspec for two purposes: 

* Set the b=AS: parameter in the SDP to be sent out from the device 

* Map the flowspec data to UMTS QoS parameters. This is described below. 

The flowspec is optional, and if it is present, some of its parts are optional. 

The IMS engine shall process a flowspec for a BasicMedia in the following way. 

Set b=AS: in the SDP media to the peak bitrate if given, otherwise to the average rate if given, otherwise not at all. 

If the flowspec is missing, then the UMTS traffic class is background. 

If the flowspec includes bitrate, but no delay, then the traffic class is interactive. Set the maximum bitrate to the 

peak bitrate, if that is given, otherwise to the average bitrate. The priority is implementation-specific. 

If the flowspec includes bitrate and delay, then select Conversational class if the delay is less than 300ms, 

otherwise Streaming. Use peak bitrate as maximum and average as guaranteed bitrate. 

No mapping exists for the DelayVariance. 

User id handling 

A user id that the application places in the To argument of service methods can be a local number tel uri without a 

phone context parameter. If this is the case, the IMS engine shall insert the home network domain name of the 

current subscription as value for the parameter into the URI for any requests sent out based on the service method. 

If the home network domain name is not known to the local device, an algorithm to create the domain name based 

on the IMSI is given in 3GPP TS 23.003 that shall be used. 

Subscription Update 

When IMS Engine performs a SUBSCRIBE refresh to the server, this can take up to a few seconds depending on 

the update. If an application requests an update (i.e. via Subscription.subscribe()) at the same time as the 

SUBSCRIBE refresh (update collision) the IMS Engine shall wait until the current refresh is completed. 

Securing FW/NAT traversal between the mobile operator and the 

Internet 

The operator network offers private IP address plan and Network Address Translation (NAT) at the edge of the 

Internet. This breaks the originally envisioned model of IP e2e across the Internet since devices inside operator’s 

network are not directly addressable from outside the Local Area Network (LAN). 

Additionally operators protect their LAN using Firewalls (FW), which usually prohibit terminals in the public internet 

to access operator’s network using IMS related protocols. 

These limitations can be overcome by different mechanism for mapping public IP addresses and private one’s in 

the operator’s network behind NAT and keeping the communication channel active using keep-alive signaling. This 

puts certain requirements on the implementation provided by the IMS stack vendor (terminal vendor) for each 

particular type of protocol in use. 

These guidelines describe the protocol details and mechanisms to be used for implementation of both SIP control 

channel and all four types of media connections provided by IMS stack in JSR-281, StreamMedia, FramedMedia, 

BasicReliableMedia, BasicUnreliableMedia. 


Appendix A 

SIP 

SIP signaling can rely on either TCP or UDP protocol. This guideline recommends to follow the recommendation in 

draft-ietf-sip-outbound which is what 3GPP R7 version of TS24.229 refers to, to include the outbound options tag in 

the Supported header. Additionally keep-alive signaling should be implemented both in case of TCP and UDP 

bearer. 

TCP 

Keep alive should include double CRLF sequence (CRLFCRLF). 

A 3GPP R7 compliant P-CSCF will respond with sending back a single CRLF to indicate to the UE the liveliness of 

the TCP connection. 

If TCP connection is broken, UE needs to do a new registration to IMS. 

UDP 

Keep alive should include a STUN binding request. 

A 3GPP R7 compliant P-CSCF will respond with a STUN binding response. The response can be used by the UE 

to determine if the NAT has rebooted and remapped the SIP/UDP flow to another public port, in which case the UE 

need to make a new registration to IMS. 

FramedMedia 

FramedMedia provides ability to send and receive any content using MSRP protocol. 

Keep-alive using CRLF sequence should be implemented. 

Additionally for the purpose of traversing NAT RFC4145 should be implemented in the SIP stack in the terminal 

and Session Boarder Gateway (SBG) should be used for the media streams. 

It is also recommended to follow the OMA IM example and deviate from the MSRP RFC on the point of using the 

address and port conveyed through the SDP c and m lines, instead of the address:port from the MSRP URI in the 

a=path line, as destination for the TCP open request for an MSRP connection. The motivations for this can be 

found in the I.D draft-blau-msrp-acm. 

StreamMedia 

StreamMedia provides ability to stream audio or video using RTP protocol. Additionally RTCP protocol is use as the 

control protocol for RTCP. 

RTP 

Keep alive using not negotiated payload format in the header should be implemented. 

Additionally for the purpose of traversing NAT Session Boarder Gateway (SBG) should be used for the media 

streams. 

RTCP 

RR/SR can keep the communication channel is sent according to the specification (each 2.5s). Otherwise emptySR 

should be sent as keep-alive. 

Additionally for the purpose of traversing NAT Session Boarder Gateway (SBG) should be used for the media 

streams. 


BasicReliableMedia provides ability to send and receive any application data encapsulated as the payload in the 

TCP protocol. 


Appendix A 

Terminal vendors should activate, if possible, the system controlled keep-alive for the socket. If not possible the 

application needs to actively take care of sending keep-alive and decide what data sequence should be used for 

that. The data used for keep-alive should not interfere with the applicationc data. 

Additionally for the purpose of traversing NAT, RFC4145 should be implemented in the SIP stack and Session 

Boarder Gateway (SBG) should be used for the media streams. 


BasicUnreliableMedia provides ability to send and receive any application data encapsulated as the payload in the 

UDP protocol. 

The application needs to actively take care of sending keep-alive and decide what data sequence should be used 

for that. The data used for keep-alive should not interfere with the application data. 

Additionally for the purpose of traversing NAT, Session Boarder Gateway (SBG) should be used for the media 

streams. 

Resolution of keep-alive timer 

Following the recommendation in draft-ietf-sip-outbound, which is what 3GPP R7 version of TS24.229 refers to, the 

following values should be used: 

TCP: 14min 

UDP: 29s 


Appendix A 

Appendix B: MIDP 2.0 PushRegistry for JSR 281 

Introduction 

This appendix describes implementation requirements for MIDP 2.0 PushRegistry. It covers connections using 

URIs that have the imscore: scheme. 

PushRegistry Registration Parameters 

This section describes the parameters for static and dynamic push registrations. These are ConnectionURL, 

MIDletClassName and AllowedSender. For a static push registration, the parameters are found in the manifest file 

or the JAD file for the MIDlet suite under the MIDlet-Push- attribute. For dynamic registration, they are 

arguments to the PushRegistry.registerConnection() method. 

ConnectionURL Parameter 

The connectionURL parameter is the same as the imscore: connector string argument used in the 

Connector.open() call. Please refer to the documentation for the javax.microedition.ims package. 

AllowedSender Parameter 

The allowedSender is a filter specification of incoming requests that are allowed to push start the MIDlet. The list 

is composed of three parts. The first part shows domains of allowed remote users. The second part specifies 

accepted incoming service methods. The third part allows exclusions of certain unwanted specific URIs. The 

allowedSender syntax is shown in the table below: 

 

::= [ “;method=”] [ “;blacklist=”] 

 

::= “*” | 

 

::= “,” | 

 

::= | 

 

::= A domain name as found in SIP or TEL URIs 

 

::= SIP or TEL URI 

::= [“,” ] 

::= “Session” | “Reference” | “PageMessage” | “Subscribe” ( “ “ “ “ )+ 

 

::= event package name 

 

::= 

The details of an incoming SIP request message is matched to the allowedSender field in order to reject it if it 

does not pass and hence avoid constructing objects unnecessarily. The matching process is as follows: 

If the white filter is * the match succeeds. Else, SIP and/or TEL URIs shall be taken out of the P-Asserted-Identity 

and Contact headers. If some of the domains found there are in the white domain list the request passes this part. 

If there is no method part of the filter, then if the SIP method is INVITE then the request passes. For other methods, 

it fails. If service methods are listed in the filter, then only SIP messages with methods that would trigger a call back 

to the application pass the filter: Session – SIP INVITE, PageMessage – SIP MESSAGE, Reference – SIP REFER, 

Subscribe – NOTIFY. For NOTIFY, it is required that the received NOTIFY message matches the SUBSCRIBE to 

and event parameters as well. 

If the blacklist is present, then if some SIP or TEL URI from P-Asserted-Identity and Contact headers match a 

domain name or is equal to some address in the blacklist, then the request fails. To filter out anonymous requests 

from launching a MIDlet, then the URI sip:anonymous@anonymous.invalid shall appear in the blacklist. 

Failed requests are responded with 488 Not acceptable here. 


Appendix A 

Notes for Subscribe 

Using Subscribe as allowed method makes the MIDlet push registration create an event subscription directed to the 

server at the to address. When a response to that subscription is received, the application is launched. Regardless 

of the whitelist and blacklist filters, events from the server always pass. Note that the syntax allows several 

subscriptions to be created. 

Examples 

Explanations are in parenthesis: 

* (all requests match) 

*;method=Session (Session invitation requests are allowed. Reference, PageMessage and Subscription events are 

not allowed.) 

Jcp.org;method=PageMessage (Page messages are allowed from jcp.org) 

Jcp.org;method=PageMessage,Subscribe sip:server@ims.com presence (Page messages from jcp.org and 

Subscribe presence events are accepted) 

Jcp.org,ims.org,government.se;blacklist=sip:john@spamsalot.com (all requests from these domains are accepted, 

except for those sent from sip:john@spamsalot.com). 

Jcp.org,ims.org,government.se;blacklist=tel:+4646232809@ims.org (all requests from these domains are accepted, 

except for those sent from tel:+4646232809@ims.org). 

Push registrations overview 

This section describes the model of IMS push registrations used in the JSR 281. A key ingredient is when the SIP 

REGISTER message is sent out in relation to the call to Connector.open(). 

In a manual start of non-push registered MIDlets, the IMS registration is updated (via a SIP REGISTER message to 

the proxy server) at the time the MIDlet calls Connector.open() as it obtains the core service object. For the 

push registered case, the creation of core service follows a lazy scheme, in that the SIP REGISTER is sent before 

the MIDlet calls Connector.open(). This can happen in two ways. (1) At system start, the IMS engine processes 

all imscore push registrations in the system and sends out the SIP REGISTER. (2) For push registrations added at 

a later stage, new SIP REGISTER messages are sent out to update the IMS registration as they arrive, either via 

installation of application suites with static push registrations, or dynamically, via the 

PushRegistry.registerConnection() call. 

Creating and handling a push registration 

The main design principle is outlined in this section. 

For push registrations, the AMS acts as client to the IMS engine rather than the application. When processing a 

push registration (which usually is done at system start) the AMS calls Connector.open() on the 

connectionURL strings. The AMS buffers the core service objects, waiting for further activity from the IMS 

network. For the Subscription case, the AMS also creates and buffers a subscription service method object from 

the core service. 

On an incoming request that targets such a buffered core service created for a push registration, the AMS launches 

the MIDlet owning the IMS application. When the MIDlet makes the call to Connector.open() with the 

connectionURL string, the buffered core service is passed to the MIDlet instead of creating a new one. 

Meanwhile, the IMS engine has created a service method for the incoming request, and this is passed to the MIDlet 

once it has set the appropriate listener on the core service object. At this stage, handover of the core service and 

service method is complete. For the subscription case, the event is delivered to the application once the MIDlet has 

set the subscription listener. More details of the scenario are given below in the section “AMS accepting incoming 

imscore connections”. 

Note that the AMS must use internal interfaces to the IMS engine in order to monitor the progress of the MIDlet and 

perform details of the handover. For example, the AMS should not (meaningfully) set a listener on the created core 

service since it does not handle the incoming service method; that is done by the application. This is specific to the 

push registry implementation of the device. 


Appendix A 

Removing a push registration 

A push registration is removed either by uninstalling the application suite, or when the MIDlet calls 

Pushregistry.unregisterConnection(). When this happens, then the IMS registration at the server MUST 

be updated with a new contact header showing the removed push registration is no longer active. In the scenario 

above, a saved core service is closed. 

Maintaining a push registration 

Since it may take some time between a push registration and when an incoming connection is accepted, the push 

registry mechanisms for IMS MUST monitor the current IMS registration. If it happens that the device is 

de-registered, the implementation MUST try to recover the IMS registration as soon as possible. This should be 

done in harmony with the device policy. When the IMS network is once again available, registrations shall be 

restored. 

AMS accepting incoming imscore connections 

The process of transferring ownership of objects from the AMS to the MIDlet is called “hand over”, and is a key part 

in the push launch. 

Hand over requires the MIDlet must be programmed in a certain way. This is however what IMS MIDlets would 

normally do when using the IMSAPI for the non-push registered case. In the sections below, the criteria that the 

MIDlet program must follow to properly handle a push start are presented. 

PageMessage, Reference and Session handling 

The MIDlet MUST do: 

1. Call Connector.open with the connectionURL string: 

cs = (CoreService)Connector.open(“imscore://myApp”); 

The IMS engine here hands over the core service that the AMS created for the push registration. 

2. Set the core service listener, assuming this implements the CoreServiceListener interface: 

cs.setListener(this); 

The application is handed over the PageMessage via CoreServiceListener.PageMessageReceived(), 

Reference via CoreServiceListener.referenceReceived(), and Sessions via 

CoreServiceListener.SessionInvitationReceived(). 

Subscription event handling 

The MIDlet MUST do: 

1. Call Connector.open with the connectionURL string: 

cs = (CoreService)Connector.open(“imscore://myApp”); 

The IMS engine here returns the core service that the AMS created for the push registration. 

2. Set the core service listener, assuming this implements the CoreServiceListener interface: 

cs.setListener(this); 

3. Create a Subscription with the same to and event arguments as specified in the allowed sender string: 

sub = cs.createSubscription(“sip:alice@ims.org”, “sip:server@ims.org”, “myEvent”); 

4. Set a subscription listener, assuming this implements the SubscriptionListener interface: 

sub.setListener(this); 

The application gets SubscriptionListener.subscriptionStarted call back and then the event that 

caused it to launch with SubscriptionListener.subscriptionNotify. 


Appendix A 

To summarize, for all push registrations, the AMS is responsible to handle them up until the point where the MIDlet 

creates the core service and sets the listener. From that point the MIDlet assumes responsibility. After the core 

service is closed (for whatever reason) incoming connections are rejected until the MIDlet opens it again. The IMS 

registration MUST be updated with a contact header that reflects this situation. When the MIDlet terminates, AMS 

takes the responsibility again to monitor incoming connections on behalf of the MIDlet. This results in a re-update of 

the IMS registration to again include an updated contact header for this application. 

If the MIDlet fails to do any of these steps, then hand over does not succeed and the AMS could not transfer the 

object ownership. For core services not handed over, the AMS buffers them until the push registration is 

terminated. 

Note that the AMS owns push registered connections up until the MIDlet does setListener on the core service 

object. 

AMS rejecting incoming imscore connections 

This section makes it explicit when the AMS rejects incoming connections for push registry. This happens in the 

following cases. 

• If an incoming connection could not route to a core service. 

• If the connection does not pass the allowedSender field of the push registration. 

• If the connection includes a request that does not match the argument list of the connectionURL (note that 

Session is accepted if the list is not specified). 

In these cases, the MIDlet will not launch. The AMS keeps its ownership. Note that if the application creates the 

core service on its own initiative (via connector.open()) then it will receive all incoming requests since it has claimed 

ownership. 

MIDlet auto-invocation 

There is a permission associated with auto-launch of application based on the string 

javax.microedition.io.PushRegistry. When the user is prompted, the following information MUST be presented to 

the user: 

• The name of the MIDlet, and the IMS application name. 

• The request type (Session, PageMessage, Reference, Subscription event). 

• The From and the P-Asserted-Identity header fields of the incoming request. If the request is anonymous, 

then this MUST be indicated to the user. 

• If there are several incoming requests that attempt to launch the same application, then this MUST be 

presented to the user. 

Buffering 

The section explains details on the buffering of incoming requests until the MIDlet is ready to handle them. 

If the device has an IMS registration that reflects that it is ready to handle incoming requests targeted at a certain 

IMS application and some of its core services, then the IMS network and remote endpoints should not need to be 

aware that the MIDlet is not running yet. Buffering should be implemented as transparently as possible. 

The AMS must buffer incoming service methods and subscription events in a first in first served manner. The size 

of the buffer is implementation specific. If the buffer overflows, the request shall be rejected with 480 Temporarily 

not available. 

The AMS MUST buffer at least one service method object and one subscription event for a push registered core 

service until some of the following happens: 


Appendix A 

• The AMS can reject the incoming connection according to above. 

• The AMS can accept the incoming imscore connection according to above (performs a successful 

handover) 

• The MIDlet calls Connector.open() using the connectionURL string for the push registered core 

service and then closes it without following through on the remaining steps listed as the criteria for 

acceptance. 

• The push registration is removed. 

• The MIDlet is uninstalled from the device. 

• Buffered for at least 128 seconds. This is the INVITE transaction timeout T1*64 according to [24.229]. 

Example jad-file in MIDP 2.0 

A chess application is configured to launch based on when the opponent opens a session, or when, for example, a 

community server for chess players shows someone is interested in a new game is present. 

MicroEdition-IMS-1-Identity: org.jsr281.myChess, MyChess 

MicroEdition-IMS-1-Event: Presence 

MicroEdition-IMS-1-CoreService-1: myChess, urn:IMSAPI:com.myCompany.iari.myChess, , 

MIDlet-Push-1: imscore://myChess, org.jsr281.myChess, *;method=Session, Subscribe 

sip:server@chess.ims.org presence

JSR 281 IMS Services API - Oracle Software Delivery Cloud

Create successful ePaper yourself

Delete template?

Save as template?