jsr281 Api FR v1.0

JSR 281 IMS Services API
for Java Micro Edition

Final Release Version 1.0
JSR 281 Expert Group
jsr-281-comments@ericsson.com

J ava Community Process
JSR 281 IMS Services API Page 1 of 155

J SR 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 J SR 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 J ava
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, J ava 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 Licensees Independent
Implementation or products derived from it. However, except with respect to implementations of the
Specification (and products derived from them) by Licensees licensee that satisfy limitations of Section 1.3
(a)-(c) above, Licensee may neither: (i) grant or otherwise pass through to Licensees licensees any
licenses under intellectual property rights licensable by Ericsson; nor (ii) authorize Licensees licensees to
make any claims concerning their implementations 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 Licensees patent rights, which are or would be infringed by all technically feasible
implementations of the Specification, on the following terms:
(i) the license grant shall be under each patent claim that Licensee own, will own or have the
authority to license, and
(ii) the license shall be granted on fair, reasonable and non-discriminatory terms, and
(iii) the license shall be perpetual, non-exclusive, non-transferable and worldwide within the
scope of the licenses granted above by Ericsson, and
(iv) 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
(v) 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) 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
licensees patent claims where there is no technically feasible alternative that would avoid
the infringement of such claims (with respect to Licensees exercise of the rights
described in subparagraphs (iv) (v) immediately above); or
(ii) 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:
(iii) 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 Licensees licenses to Ericssons 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 Licensees 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 J ava 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 Licensees 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 Ericssons
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 SUBJ ECT 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) Licensees use of the Specification; (ii) the use or distribution of Licensees J ava
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 J ava Community
Process, or (ii) bound by obligations of the J ava 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 Licensees 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

Preface.........................................................................................................................................................................7
Revision History........................................................................................................................................................7
Who Should Use This Specification..........................................................................................................................7
How This Specification Is Organized........................................................................................................................7
References................................................................................................................................................................7
Terms and Abbreviations ..........................................................................................................................................8
J SR 281 Expert Group..............................................................................................................................................9
Document Conventions.............................................................................................................................................9
Report and Contact...................................................................................................................................................9
Overview....................................................................................................................................................................10
IP Multimedia Subsystem........................................................................................................................................10
IMS and J SR 281....................................................................................................................................................11
IMS Applications......................................................................................................................................................13
Further reading of IMS ............................................................................................................................................15
MIDP Push registration of IMS applications............................................................................................................15
Security...................................................................................................................................................................16
Identification of the IMSAPI.....................................................................................................................................16
Quality-of-Service management in IMSAPI ............................................................................................................16
Optional Parts of the IMSAPI ..................................................................................................................................18
Requirements on the StreamMedia Player.............................................................................................................18
Package javax.microedition.ims .............................................................................................................................19
Class Configuration.................................................................................................................................................26
Class ConnectionState............................................................................................................................................29
Interface ConnectionStateListener..........................................................................................................................31
Class ImsException.................................................................................................................................................32
Interface Service.....................................................................................................................................................33
Class ServiceClosedException...............................................................................................................................35
Package javax.microedition.ims.core.....................................................................................................................36
Interface Capabilities...............................................................................................................................................38
Interface CapabilitiesListener..................................................................................................................................41
Interface CoreService .............................................................................................................................................42
Interface CoreServiceListener.................................................................................................................................47
Interface Message...................................................................................................................................................49
Interface MessageBodyPart....................................................................................................................................55
Interface PageMessage..........................................................................................................................................57
Interface PageMessageListener .............................................................................................................................61
Interface Publication................................................................................................................................................62
Interface PublicationListener...................................................................................................................................66
Interface Reference.................................................................................................................................................68
Interface ReferenceListener....................................................................................................................................75
Interface ServiceMethod.........................................................................................................................................77
Interface Session.....................................................................................................................................................81
Interface SessionDescriptor....................................................................................................................................92
Interface SessionListener........................................................................................................................................96
Interface Subscription .............................................................................................................................................99
Interface SubscriptionListener...............................................................................................................................102
Package javax.microedition.ims.core.media .......................................................................................................104
Interface BasicReliableMedia................................................................................................................................106
Interface BasicReliableMediaListener...................................................................................................................109
Interface BasicUnreliableMedia............................................................................................................................110
Interface BasicUnreliableMediaListener ...............................................................................................................113
Interface FramedMedia.........................................................................................................................................114
Interface FramedMediaListener............................................................................................................................120
Interface Media......................................................................................................................................................123
Interface MediaDescriptor.....................................................................................................................................130
Interface StreamMedia..........................................................................................................................................134
Implementation guidelines ....................................................................................................................................139

Preface
This document defines the IMS Services API (IMSAPI), a J ava API for the IP Multimedia Subsystem (IMS) on end
user mobile devices. The IMSAPI is an optional package for the J ava 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. J ava can play an important role in the deployment and adoption of IMS at large,
because of the volume of installed J ava 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 J ava 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 J ava 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 J SR to consider.
Revision History
Date Version Description
10-February-2006 IMS Specification First draft provided by the Specification Lead
18-J uly-2006 Draft version 0.2 Changes and clarifications
25-J uly-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-J une-2008 FR version 1.0 Final Release
Who Should Use This Specification
This document is targeted at the following audiences:
The J ava Community Process (J CP) 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, J avaDoc 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 J avaDoc parts. The
appendix is used as a guide for implementers of the specification.
References
[J SR75] J SR 75 FileConnection API
[J SR118] J SR 118 MIDP2.0
[J SR135] J SR 135 Mobile Media API
[J SR139] J SR 139 CLDC 1.1
[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
[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"
[RFC3840] RFC 3840 "Indicating User Agent Capabilities in the Session Initiation Protocol (SIP)"
[RFC3841] RFC 3841 "Caller Preferences for the Session Initiation Protocol (SIP)"
[RFC4145] RFC 4145 "TCP-Based Media Transport in the Session Description Protocol"
[RFC4566] RFC 4566 "SDP Session Description Protocol"
[RFC4975] RFC 4975 "The Message Session Relay Protocol"
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.
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).
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: J ava J SR 281 IP Multimedia Subsystem API.
IMS Application: A realization of a number of IMS capabilities for a well-defined end user purpose.
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 J SR 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 Definition
MUST The associated definition is an absolute requirement of this specification.
MUST
NOT
The definition is an absolute prohibition of this specification.
SHOULD 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.
SHOULD
NOT
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.
MAY Indicates that an item is truly optional.
Formatting Conventions
This specification uses the following formatting conventions.
Convention Description
Cour i er New
Used in all J ava 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 and User Identities
For many years, phone numbers have been used to identify subscribers and their devices. In fixed networks, the
number indicated the line to the subscriber. In mobile telephony, the SIM card has a similar role and is used to
authorize access to the network. In these systems, the phone number relates more to the device rather than the
subscriber. In IMS, identities focus on the subscriber to make a unique identification. A subscriber can share an
identity across multiple devices, and other factors decide which device handles an incoming call. The user identity
is an operator specified string formatted as a SIP URI:
sip:user@domain
If the subscriber has a telephone number it can be formatted as a TEL URI and used as a user identity:
tel:number
Service and Service Identifier
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 (PSI). If Alice wants to take part in a conference, she dials into the conference using its PSI. The
conference server arranges for her participation. A PSI is formatted as a SIP URI (like the user identity).
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 J SR 281 assumes.
Capabilities of a JSR 281 IMS Application
When writing an IMS application in J SR 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:
ur n: ur n- xxx: 3gpp- ser vi ce. i ms. i csi . mmt el
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 J SR 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:
ur n: I MSAPI : 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 J SR 281, but may be in other complementary J SRs. Nonetheless, J SR 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 J SR 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 J SR 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 J SR 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 J SR 281, it is independent of its particular interfaces and J ava.
It is important to keep IMS application and J ava 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 J SR 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 J SR 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.
IMS Applications in IMSAPI
The IMSAPI is purposely designed to enable efficient management of IMS applications in a J ava ME. An IMS
application realized within the framework of J SR 281, is called a JSR 281 IMS application. A parent J ava
application contains a suite of J SR 281 IMS applications. Hence, it is important not to confuse J ava and IMS
applications in J SR 281.
Like the J ava application framework, there are two main aspects of an IMS application model:
Installing and uninstalling of IMS applications.
Starting and stopping IMS application execution.
A J SR 281 IMS application consists of the parent J ava code whose execution defines the local runtime behavior,
and a set of IMS properties that the J SR implementation uses to manage correct operation towards the IMS
network. Specifically, it plays a key role for interoperability. The J ava code and the IMS properties are both
necessary parts of an IMS application and are created at development time.
The IMS property set is maintained in the Registry, a small data base for the application. The Registry is created at
install, and removed at uninstall. It is used when an IMS application is started, and is never accessed from IMS
application code.
IMS Application Identifiers
To be able to refer to a specific IMS application, an IMS application identifier (AppId) is used. The AppId is a
symbol that follows the form of fully qualified J ava class names or any naming syntax that provides a natural way to
differentiate between application vendors. The AppId is set at development time, and MUST be unique within the
context of the IMS application suite and the parent J ava application suite.
Summary
This completes the description of the IMSAPI model of IMS applications. A J ava 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 users 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 J SR 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].
MIDP Push registration of IMS applications
MIDP defines a mechanism to register a MIDlet to respond when an incoming connection is made. Once the MIDlet
has been launched it performs the same operations as it would normally do. For J SR 281 applications this allows
the Application Management System (AMS) to launch the MIDlet if there is an incoming IMS call whose needed
capabilities matches those of its IMS application capabilities.
Each service that the application expects to receive IMS calls from is listed in the Push registration. A Push
registration for J SR 281 follows that of MIDP and has three parts:
connection - The complete connection argument as is passed to Connector.open of that MIDlet to create
the core service. The argument includes the AppId and other optional parameters, such as serviceId, and
userId.
midlet - The class name of the MIDlet to be launched. This MUST be the same as the class name for the
IMS application.
filter - Not used in J SR 281.
Push registrations in MIDP can be registered statically or dynamically. MIDlet Push registration cannot be done for
uninstalled IMS applications. In particular, this rules out the combination of a dynamic IMS application installation
and a static Push registration. It is not possible to have two suites installed where two of Push registrations contain
the same set of composed capabilities. Hence, it is possible to have several Push registrations with the same
connector string contents, as long as the constraint above is not violated. The system MUST accept IMS
applications with the same AppId in different suites.
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 Secur i t yExcept i on is
thrown. Below, follows a list of permission names, the included protected method calls, and the mapping to a
function group.
Permission Permitted Java API Calls 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
Identification of the IMSAPI
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.0
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 nul l MUST be
returned.
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 J SR 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 J SR
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 J ava 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.
Optional Parts of the IMSAPI
The StreamMedia interface is conditionally mandatory, meaning that if the device has support for streaming it
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.
Supported codecs
An IMSAPI implementation MUST support the codecs:
AMR-NB
AMR-WB, if the device is wideband
H.263, if streaming video is supported
Mandatory Controls
The following table outlines the J SR 135 Mobile Media API controls that are mandatory for the IMSAPI
implementation.
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 [J SR118] and [J SR135], 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
RateControl Setting the playback rate is not supported
Package javax.microedition.ims
This package collects classes and interfaces to install and configure IMS applications.
See:
Description
Interface Summary
Page
ConnectionStateListener A listener type for receiving notifications about changes to the IMS connection. 31
Service
Ser vi ce is the base interface for IMS Services, and follows the Generic
Connection Framework (GCF).
33

Class Summary
Page
Configuration
The Conf i gur at i on class realizes dynamic installation of IMS applications with the pair
of methods set Regi st r y and r emoveRegi st r y.
26
ConnectionState
The Connect i onSt at e class is used to monitoring the IMS connection and accessing
user identities.
29

Exception Summary
Page
ImsException An I msExcept i on indicates an unexpected error condition in a method. 32
ServiceClosedException
A Ser vi ceCl osedExcept i on indicates that a method is invoked on a Ser vi ce
that is closed.
35
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 J SR 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 Conf i gur at i on. set Regi st r y. Both installation methods
are mentioned below.
Go online
The application creates a Ser vi ce when it is prepared to handle calls. A Ser vi ce is created by calling
Connect or . open. In order to receive incoming calls, it is recommended that the Cor eSer vi ceLi st ener is set as
soon as the Ser vi ce is opened.
Connect a call
The final step that needs to be done is to create a Sessi on that will manage the call. The call can be configured by
adding various media and is then initiated by calling Sessi on. st ar t .
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.
myCor eSer vi ce = ( Cor eSer vi ce) Connect or . open( i mscor e: / / com. myCompany. Cal l App) ;
myCor eSer vi ce. set Li st ener ( t hi s) ;

mySessi on = myCor eSer vi ce. cr eat eSessi on( nul l , si p: bob@home. net ) ;
mySessi on. set Li st ener ( t hi s) ;

myMedi a = ( St r eamMedi a) mySessi on. cr eat eMedi a( St r eamMedi a, Medi a. DI RECTI ON_SEND_RECEI VE) ;
myMedi a. set Sour ce( capt ur e: / / audi o) ;

mySessi on. st ar t ( ) ;
The JSR 281 IMS Application Registry
In this section, the logic and structure of the Registry is described. In the following two, the notation used at static
and dynamic install is specified.
A Registry consists of 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.
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 J SR 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 St r eamMedi a 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 Fr amedMedi a somewhere in its code. If it
does not, then the Registry does not include the property.
Value: The value is a set of all MIME content types used in the media.
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 Basi cUnr el i abl eMedi a and/or
Basi cRel i abl eMedi a 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.
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, a set of IARIs, ICSIs, and Feature Tags on standardized formats. ICSI
and Feature Tags can also have the explicit and require flags. 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 J SR 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 J SR 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.
Dynamic Installation
Dynamic installation uses the method Conf i gur at i on. set Regi st r y, that binds an IMS application to a J ava
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" }
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, IARIs, ICSIs, and Feature Tags. Individual ICSIs and Feature Tags can be appended
with ; r equi r e and/or ; expl i ci t to flag them for require and explicit processing.
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-xxx:org.3gpp.icsi;require;explicit", "" }
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: "<average rate><buffer size><peak rate><delay><delayVariance>
<max chunk size><minimal policed size>".
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" }
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 Conf i gur at i on. set Regi st r y call expected for the myChess application:
St r i ng[ ] [ ] r egi st r y = new St r i ng[ ] [ ] {
{ " Basi c" , " appl i cat i on/ myChess" },
{ " Fr amed" , " t ext / pl ai n i mage/ png" },
{ " Event " , " Pr esence" },
{ " Cor eSer vi ce" , " myChess" , " ur n: I MSAPI : com. myCompany. i ar i . myChess" , " " , " " },
{ " Qos" , " myChess" , " appl i cat i on/ myChess" , " 2 3 2 10 5 2 3" , " " },
{ " Reg" , " myChess" , " Requi r e: pr ef " },
{ " Wr i t e" , " P- I mageI ncl uded" },
{ " Read" , " P- I mageI ncl uded" },
{ " Cap" , " Fr amed" , " Req_Resp" , " a=max- si ze: 4096" }
};
Conf i gur at i on. set Regi st r y( " or g. j sr 281. myChess" , " MyChess" , r egi st r y) ;
Static Installation
IMS applications can be installed at the time of J ava 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 r egi st r y argument to
Conf i gur at i on. set Regi st r y. 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 J ava application suite. To avoid possible name collisions with
attributes of other packages, all attributes names for the IMSAPI begin with Mi cr oEdi t i on- I MS- .
A J ava 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-<n>attribute of
MIDP:
Mi cr oEdi t i on- I MS- - I dent i t y: <AppI D>, <cl ass>
MicroEdition-IMS--Stream
Encodes the Stream property for IMS application i.
Mi cr oEdi t i on- I MS- - St r eam: <Val ue>
MicroEdition-IMS--Framed
Encodes the Framed property for IMS application i.
Mi cr oEdi t i on- I MS- - Fr amed: <Val ue>
MicroEdition-IMS--Basic
Encodes the Basic property for IMS application i.
Mi cr oEdi t i on- I MS- - Basi c: <Val ue>
MicroEdition-IMS--Event
Encodes the Event property for IMS application i.
Mi cr oEdi t i on- I MS- - Event : <Val ue>
MicroEdition-IMS--CoreService-<j>
Encodes the j-th CoreService property for IMS application i.
Mi cr oEdi t i on- I MS- - Cor eSer vi ce- <j >: <ser vi ceI d>, , , <Feat ur e Tags>
The and <Feat ur e Tags> may have the flags ; r equi r e and/or ; expl i ci t appended.
MicroEdition-IMS--Qos-<j>
Encodes the j-th QosProfile property for IMS application i.
Mi cr oEdi t i on- I MS- - Qos- <j >: <ser vi ceI d>, <Cont ent Type>, <Fl owSpecSend>,
<Fl owSpecRecei ve>
MicroEdition-IMS--Reg-<j>
Encodes the j-th Registration header property for IMS application i.
Mi cr oEdi t i on- I MS- - Reg- <j >: <ser vi ceI d>, <Header 1>, . . . , <Header n>
MicroEdition-IMS--Write
Encodes the Write property for IMS application i.
Mi cr oEdi t i on- I MS- - Wr i t e: <Val ue>
MicroEdition-IMS--Read
Encodes the Read property for IMS application i.
Mi cr oEdi t i on- I MS- - Read: <Val ue>
MicroEdition-IMS--Cap-<j>
Encodes the j-th Configure capabilities property for IMS application i.
Mi cr oEdi t i on- I MS- - Cap- <j >: <sect or I d>, <messageType>, <SDP f i el d 1>, . . . , <SDP f i el d n>
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:
Mi cr oEdi t i on- I MS- 1- I dent i t y: or g. j sr 281. myChess, MyChess
Mi cr oEdi t i on- I MS- 1- Basi c: appl i cat i on/ myChess
Mi cr oEdi t i on- I MS- 1- Fr amed: t ext / pl ai n i mage/ png
Mi cr oEdi t i on- I MS- 1- Event : Pr esence
Mi cr oEdi t i on- I MS- 1- Cor eSer vi ce- 1: myChess, ur n: I MSAPI : com. myCompany. i ar i . myChess, ,
Mi cr oEdi t i on- I MS- 1- Qos- 1: myChess, appl i cat i on/ myChess, 2 3 2 10 5 2 3,
Mi cr oEdi t i on- I MS- 1- Reg: myChess, Requi r e: pr ef
Mi cr oEdi t i on- I MS- 1- Wr i t e: P- I mageI ncl uded
Mi cr oEdi t i on- I MS- 1- Read: P- I mageI ncl uded
Mi cr oEdi t i on- I MS- 1- Cap: Fr amed, Req_Resp, a=max- si ze: 4096
Executing IMS applications
An IMS application in general can be said to be in a state of execution whenever some of its capabilities are in use.
A J SR 281 IMS application is executing whenever at least one of its Core Services are created and active.
The parent J ava application creates Core Service objects for an IMS application using a Connect or . open call of
the Generic Connection Framework (GCF) where the connector argument string has the syntax:
i mscor e: <AppId>; user I d=<userId>; ser vi ceI d=<serviceId>
where:
The locator <AppId>is the AppId of the IMS application
The optional parameter <userId>is the selected user identity of the local user. If unspecified, a default user
identity is used.
The optional parameter <serviceId>is the serviceId of a CoreService property of the Registry of this IMS
application. If unspecified, it defaults to a CoreService property with the empty 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 by calling its cl ose method.
Class Configuration
Class Configuration
javax.microedition.ims
j ava. l ang. Obj ect
javax.microedition.ims.Configuration

f i nal publ i c cl ass Configuration
ext ends Obj ect
The Conf i gur at i on class realizes dynamic installation of IMS applications with the pair of methods set Regi st r y
and r emoveRegi st r y. 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
J ava application installation.

Method Summary
Page
st at i c
Conf i gur at i on
getConfiguration( )
Returns a Conf i gur at i on that enables dynamic installation of IMS applications.
26
St r i ng[ ]
getLocalAppIds( )
Returns all AppIds for the local endpoint.
28
St r i ng[ ] [ ]
getRegistry( St r i ng appI d)
Returns the registry for an IMS application with the specified appI d.
27
voi d
removeRegistry( St r i ng appI d)
Removes the registry for the IMS application and deletes the binding to a J ava
application.
28
voi d
setRegistry( St r i ng appI d, St r i ng cl assname, St r i ng[ ] [ ] r egi st r y)
Sets the registry for an IMS application and binds it to a parent J ava application.
26
Method Detail
getConfiguration
publ i c st at i c synchr oni zed Conf i gur at i on getConfiguration( )
Returns a Conf i gur at i on that enables dynamic installation of IMS applications.
Returns:
a Conf i gur at i on instance that enables dynamic installation of IMS applications.

setRegistry
publ i c voi d setRegistry( St r i ng appI d,
St r i ng cl assname,
St r i ng[ ] [ ] r egi st r y)
Sets the registry for an IMS application and binds it to a parent J ava application. Any previous registry and
binding for that IMS application is deleted, including all properties. The new registry is defined in the
r egi st r y argument.
Class Configuration
The cl assname argument identifies a J ava application according to the particular J ava runtime environment.
For a MIDP2-based implementation, the classname must be registered with the Mi dl et - <n> attribute.
The r egi st r y argument specifies a registry as an unordered array of IMS properties. The general pattern
of the r egi st r y 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" },
{ " Basic" , " MIME Content types" },
{ " Event" , " Event package names" },
{ " CoreService" , " ServiceId" ,
" Zero or more IARIs" ,
" 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" }}
Example:
St r i ng myAppI d = " com. myCompany. games. chess" ;
Conf i gur at i on myConf i gur at i on = Conf i gur at i on. get Conf i gur at i on( ) ;
{ " Event " , " pr esence" },
};
myConf i gur at i on. set Regi st r y( myAppI d, cl assname, r egi st r y) ;
Parameters:
appI d - the application id
cl assname - the classname of the J ava application that the IMS application is bound to
r egi st r y - an array of arrays, specifying key and value(s)
Throws:
I l l egal Ar gument Except i on - if the appI d or cl assname argument is nul l ,
if the r egi st r y argument is nul l or if it has invalid syntax,
if the cl assname argument is not specified as a MIDlet-<n>attribute (for MIDP implementations)
See Also:
get Regi st r y( St r i ng)

getRegistry
publ i c St r i ng[ ] [ ] getRegistry( St r i ng appI d)
Returns the registry for an IMS application with the specified appI d.
Class Configuration
Parameters:
Returns:
the registry for the IMS application specified by the appI d argument
Throws:
I l l egal Ar gument Except i on - if appI d is not set in the registry
See Also:
set Regi st r y( St r i ng, St r i ng, St r i ng[ ] [ ] )

removeRegistry
publ i c synchr oni zed voi d removeRegistry( St r i ng appI d)
Removes the registry for the IMS application and deletes the binding to a J ava 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 appI d argument, this does not affect
services that are already created.
Parameters:
Throws:
I l l egal Ar gument Except i on - if appI d is not set in the registry

getLocalAppIds
publ i c St r i ng[ ] 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

f i nal publ i c cl ass ConnectionState
ext ends Obj ect
The Connect i onSt at e 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 Connect or . 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.

Method Summary
Page
st at i c
Connect i onSt at e
getConnectionState( )
Returns a Connect i onSt at e that monitors the connection to the IMS network.
29
St r i ng[ ]
getUserIdentities( )
Returns the network provisioned user identities.
30
bool ean
isConnected( )
This method can be used to determine if the device is connected to the IMS network.
29
voi d
setListener( Connect i onSt at eLi st ener l i st ener )
Sets a listener for this Connect i onSt at e, replacing any previous
Connect i onSt at eLi st ener .
30
Method Detail
getConnectionState
publ i c st at i c Connect i onSt at e getConnectionState( )
Returns a Connect i onSt at e that monitors the connection to the IMS network.
Returns:
a Connect i onSt at e instance that monitors the connection to the IMS network

isConnected
publ i c bool ean isConnected( )
This method can be used to determine if the device is connected to the IMS network.
Returns:
t r ue if the device is connected to the IMS network, f al se otherwise

setListener
publ i c voi d setListener( Connect i onSt at eLi st ener l i st ener )
Sets a listener for this Connect i onSt at e, replacing any previous Connect i onSt at eLi st ener . A nul l
reference is allowed and has the effect of removing any existing listener.
Parameters:
l i st ener - the listener to set, or nul l to remove it

getUserIdentities
publ i c St r i ng[ ] getUserIdentities( )
Returns the 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 URI, see [RFC3261] (chapter 19.1).
Returns:
the network provisioned user identities, an empty string array will be returned if no user identities
are available
Interface ConnectionStateListener
Interface ConnectionStateListener

publ i c i nt er f ace ConnectionStateListener
A listener type for receiving notifications about changes to the IMS connection.
See Also:
Connect i onSt at e. i sConnect ed( )

Method Summary
Page
voi d
imsConnected( )
Notifies the application when the device is connected to the IMS network.
31
voi d
imsDisconnected( )
Notifies the application when the device is disconnected from the IMS network.
31
Method Detail
imsConnected
voi d imsConnected( )
Notifies the application when the device is connected to the IMS network.

imsDisconnected
voi d imsDisconnected( )
Notifies the application when the device is disconnected from the IMS network.
Class ImsException
Class ImsException
j ava. l ang. Thr owabl e
j ava. l ang. Except i on
javax.microedition.ims.ImsException

publ i c cl ass ImsException
ext ends Except i on
An I msExcept i on indicates an unexpected error condition in a method.

Constructor Summary
Page
ImsException( )
Constructs an I msExcept i on with nul l as its error detail message.
32
ImsException( St r i ng r eason)
Constructs an I msExcept i on with the specified detail message.
32
Constructor Detail
ImsException
publ i c ImsException( )
Constructs an I msExcept i on with nul l as its error detail message.

ImsException
publ i c ImsException( St r i ng r eason)
Constructs an I msExcept i on with the specified detail message. The error message string r eason can later
be retrieved by the Thr owabl e. get Message( ) method of class j ava. l ang. Thr owabl e.
Parameters:
r eason - the detail message
Interface Service
Interface Service
All Superinterfaces:
javax.microedition.io.Connection
All Known Subinterfaces:
CoreService

publ i c i nt er f ace Service
ext ends j avax. mi cr oedi t i on. i o. Connect i on
Ser vi ce 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 Connect or . open( ) where the string argument has the general form
(described in [RFC2396]):
<scheme>:<target>[<params>]
where:
scheme is a supported IMS scheme. In this specification the i mscor e is defined in the Cor eSer vi ce
interface
target is an AppId. An AppId should follow the form of fully qualified J ava 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.
The returned Ser vi ce object depends on the used scheme.
The call to Connect or . open( ) is synchronous, and for some services the call might take several seconds to
complete.
Exceptions when opening a service
The following exceptions can be thrown when calling Connect or . Open( ) .
I l l egal Ar gument Except i on - If a parameter is invalid.
Connect i onNot FoundExcept i on - If the target of the name cannot be found, or if the requested protocol
type is not supported.
I OExcept i on - If some other kind of I/O error occurs.
Secur i t yExcept i on - May be thrown if access to the protocol handler is prohibited.
The following exceptions can be throws due to IMS specific errors.
I OExcept i on - The IMS profile is missing or corrupt.
I OExcept i on - The Internet profile is missing or corrupt.
I OExcept i on - The subscriber failed to authenticate within the IMS network.
I OExcept i on - The Register request failed to reach the IMS network.
I OExcept i on - The IMS network responded with a service or server specific error code.
Connect i onNot FoundExcept i on - The AppId is not an installed IMS Application.
Closing a service
The application SHOULD invoke cl ose( ) on the Ser vi ce when it is finished using the Ser vi ce.
Interface Service
See Also:
Cor eSer vi ce

Method Summary
Page
St r i ng
getAppId( )
Returns the application id string that this Ser vi ce was created with.
34
St r i ng
getScheme( )
Returns the scheme used for this Ser vi ce.
34

Methods inherited from interface javax.microedition.io.Connection
cl ose
Method Detail
getAppId
St r i ng getAppId( )
Returns the application id string that this Ser vi ce was created with.
Returns:
the application id of this Ser vi ce

getScheme
St r i ng getScheme( )
Returns the scheme used for this Ser vi ce.
Returns:
the scheme used for this Ser vi ce
Class ServiceClosedException
Class ServiceClosedException
j ava. l ang. Thr owabl e
j ava. l ang. Except i on
j ava. i o. I OExcept i on
javax.microedition.ims.ServiceClosedException

publ i c cl ass ServiceClosedException
ext ends j ava. i o. I OExcept i on
A Ser vi ceCl osedExcept i on indicates that a method is invoked on a Ser vi ce that is closed.

Constructor Summary
Page
ServiceClosedException( )
Constructs a Ser vi ceCl osedExcept i on with nul l as its error detail message.
35
ServiceClosedException( St r i ng r eason)
Constructs a Ser vi ceCl osedExcept i on with the specified detail message.
35
Constructor Detail
publ i c ServiceClosedException( )
Constructs a Ser vi ceCl osedExcept i on with nul l as its error detail message.

publ i c ServiceClosedException( St r i ng r eason)
Constructs a Ser vi ceCl osedExcept i on with the specified detail message. The error message string
r eason can later be retrieved by the Thr owabl e. get Message( ) method of class j ava. l ang. Thr owabl e.
Parameters:
r eason - the detail message
Package javax.microedition.ims.core
This package collects classes and interfaces that enable an application to create IMS services.
See:
Description
Interface Summary
Page
Capabilities The Capabi l i t i es is used to query a remote endpoint about its capabilities. 38
CapabilitiesListener
This listener type is used to notify the application about responses to capability
queries.
41
CoreService
The Cor eSer vi ce gives the application the possibility to call remote peers over the
IMS network.
42
CoreServiceListener
A listener type for receiving notifications on remotely initiated core service
methods.
47
Message
The Message interface provides functionality to manipulate headers and body parts
of outgoing request messages and to inspect previously transferred messages.
49
MessageBodyPart
A MessageBodyPar t can contain different kinds of content, for example text, an
image or an audio clip.
55
PageMessage
The PageMessage interface is used for simple instant messages or exchange of
small amounts of content outside of a session.
57
PageMessageListener
This listener type is used to notify the application about the status of sent page
messages.
61
Publication The Publ i cat i on is used for publishing event state to a remote endpoint. 62
PublicationListener
This listener type is used to notify the application of the status of requested
publications.
66
Reference
The Ref er ence is used for referring a remote endpoint to a third party user or
service.
68
ReferenceListener
This listener type is used to notify an application about events regarding a
Ref er ence.
75
ServiceMethod
The Ser vi ceMet hod interface provides methods to manipulate the next outgoing
request message and to inspect previously sent request and response messages.
77
Session The Sessi on is a representation of a media exchange between two IMS endpoints. 81
SessionDescriptor
The Session Description Protocol (SDP) provides a standard representation of
media details, transport addresses and other session descriptions to the
participants.
92
SessionListener A listener type for receiving notification on session events. 96
Subscription A Subscr i pt i on is used for subscribing to event states from a remote endpoint. 99
SubscriptionListener
This listener type is used to notify the application about subscription status and the
event state of the subscribed event package.
102
Package javax.microedition.ims.core Description
This package collects classes and interfaces that enable an application to create IMS services.

Static Structure

Figure 1: Static structure of the package.
Interface Capabilities
javax.microedition.ims.core
ServiceMethod

publ i c i nt er f ace Capabilities
ext ends Ser vi ceMet hod
The Capabi l i t i es is used to query a remote endpoint about its capabilities.
Example use of Capabilities
publ i c voi d checkSuppor t ( Cor eSer vi ce ser vi ce) {
t r y {
Capabi l i t i es caps;
caps = ser vi ce. cr eat eCapabi l i t i es( nul l , " si p: al i ce@home. net " ) ;
caps. set Li st ener ( t hi s) ;
caps. quer yCapabi l i t i es( f al se) ;
} cat ch( Except i on e) {
/ / handl e Except i ons
}
}

publ i c voi d capabi l i t yQuer yDel i ver ed( Capabi l i t i es caps) {
bool ean f eat = caps. hasCapabi l i t i es( " com. myCompany. games. chess" ) ;
}
See Also:
Cor eSer vi ce. cr eat eCapabi l i t i es( St r i ng, St r i ng)

Field Summary
Page
i nt
STATE_ACTIVE
The capability response is received.
39
i nt
STATE_INACTIVE
The capability request has not been sent.
39
i nt
STATE_PENDING
The capability request is sent and the platform is waiting for a response.
39

Method Summary
Page
St r i ng[ ]
getRemoteUserIdentities( )
Returns an array of strings representing valid user identities for the remote endpoint.
39
i nt
getState( )
Returns the current state of this Capabi l i t i es.
40
bool ean
hasCapabilities( St r i ng appI d)
This method checks if the remote endpoint has the needed capabilities of the IMS
application with appI d argument.
40
voi d
queryCapabilities( bool ean sdpI nRequest )
Sends a capability request to a remote endpoint.
39
voi d
setListener( Capabi l i t i esLi st ener l i st ener )
Sets a listener for this Capabi l i t i es, replacing any previous Capabi l i t i esLi st ener .
40

Methods inherited from interface javax.microedition.ims.core.ServiceMethod
get Next Request , get Pr evi ousRequest , get Pr evi ousResponses, get Remot eUser I d
Field Detail
STATE_INACTIVE
publ i c st at i c f i nal i nt STATE_INACTIVE
The capability request has not been sent.

STATE_PENDING
publ i c st at i c f i nal i nt STATE_PENDING
The capability request is sent and the platform is waiting for a response.

STATE_ACTIVE
publ i c st at i c f i nal i nt STATE_ACTIVE
The capability response is received.
Method Detail
queryCapabilities
voi d queryCapabilities( bool ean sdpI nRequest )
t hr ows Ser vi ceCl osedExcept i on
Sends a capability request to a remote endpoint.
The Capabi l i t i es will transit to STATE_PENDI NG after calling this method.
Parameters:
sdpI nRequest - if t r ue, the IMS engine will add a Session Description Protocol (SDP) to the
capability request
Throws:
Ser vi ceCl osedExcept i on - if the Ser vi ce is closed
I l l egal St at eExcept i on - if the Capabi l i t i es is not in STATE_I NACTI VE

getRemoteUserIdentities
St r i ng[ ] 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:
I l l egal St at eExcept i on - if the Capabi l i t i es is not in STATE_ACTI VE

getState
i nt getState( )
Returns the current state of this Capabi l i t i es.
Returns:
the current state of this Capabi l i t i es

hasCapabilities
bool ean hasCapabilities( St r i ng appI d)
This method checks if the remote endpoint has the needed capabilities of the IMS application with appI d
argument.
Note: Even if this method returns t r ue, it is not guaranteed that the AppId is installed at the remote
endpoint. It only means that the remote endpoint has support for the capabilities associated with the AppId.
Example:
capabi l i t i es. hasCapabi l i t i es( " com. myCompany. games. chess" ) ;
Parameters:
appI d - the appI d to check
Returns:
t r ue if the remote endpoint has the capabilities, otherwise f al se
Throws:
I l l egal St at eExcept i on - if the Capabi l i t i es is not in STATE_ACTI VE
I l l egal Ar gument Except i on - if the appI d argument is nul l or unknown

setListener
voi d setListener( Capabi l i t i esLi st ener l i st ener )
Sets a listener for this Capabi l i t i es, replacing any previous Capabi l i t i esLi st ener . A nul l reference is
allowed and has the effect of removing any existing listener.
Parameters:
l i st ener - the listener to set, or nul l
Interface CapabilitiesListener
Interface CapabilitiesListener

publ i c i nt er f ace CapabilitiesListener
This listener type is used to notify the application about responses to capability queries.
See Also:
Capabi l i t i es. set Li st ener ( Capabi l i t i esLi st ener )

Method Summary
Page
voi d
capabilityQueryDelivered( Capabi l i t i es capabi l i t i es)
Notifies the application that the capability query response from the remote endpoint was
successfully received.
41
voi d
capabilityQueryDeliveryFailed( Capabi l i t i es capabi l i t i es)
Notifies the application that the capability query response from the remote endpoint was not
successfully received.
41
Method Detail
capabilityQueryDelivered
voi d capabilityQueryDelivered( Capabi l i t i es capabi l i t i es)
Notifies the application that the capability query response from the remote endpoint was successfully
received.
The Capabi l i t i es has transited to STATE_ACTI VE.
Parameters:
capabi l i t i es - the concerned Capabi l i t i es

capabilityQueryDeliveryFailed
voi d capabilityQueryDeliveryFailed( Capabi l i t i es capabi l i t i es)
Notifies the application that the capability query response from the remote endpoint was not successfully
received.
The Capabi l i t i es has transited to STATE_I NACTI VE.
Parameters:
capabi l i t i es - the concerned Capabi l i t i es
Interface CoreService
javax.microedition.io.Connection, Service

publ i c i nt er f ace CoreService
ext ends Ser vi ce
The Cor eSer vi ce 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 Ser vi ceMet hod.
The application can react to incoming IMS calls by implementing the listener interface Cor eSer vi ceLi st ener .
Integration of CoreService to GCF
Connector.open(String name)
A Cor eSer vi ce is created with Connect or . open( ) , see Ser vi ce, using a name string in the following form:
imscore:<target>[<params>]
where t ar get is the application id, and <par ams> are the optional semi-colon separated parameters:
userId=<sip user identity> is the local user identity. This can be used to override the default user
identity provisioned by the IMS network.
serviceId=<service alias> is set if this Cor eSer vi ce shall support the service alias specified in the
Registry
Connector.open(String name, String mode)
The optional second parameter 'mode' in Connector.open() specifies the access mode. This is ignored when
creating a Cor eSer vi ce.
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. If this
parameter is set the implementation may throw an I nt er r upt edI OExcept i on when it detects a timeout condition.
Exceptions when opening a CoreService
The following exceptions can be throws due to Cor eSer vi ce specific errors, see Ser vi ce for more exceptions.
I OExcept i on - The Registry is not consistent, see j avax. mi cr oedi t i on. i ms for more information.
CoreService creation rules
For a given application identity and no service identity, it is possible to create at most one instance of a
Cor eSer vi ce. For a given application identity and a service identity, it is possible to have at most one
Cor eSer vi ce.
Examples
This code shows how to create a Cor eSer vi ce 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 Cor eSer vi ce. The third example shows a call
used to create a Cor eSer vi ce with a service identity specified.
ser vi ce = ( Cor eSer vi ce) Connect or . open( " i mscor e: / / com. myCompany. games. chess" ) ;

ser vi ce = ( Cor eSer vi ce) Connect or . open( " i mscor e: / / com. myCompany. games. chess;
user I d=si p: al i ce@home. net " ) ;
ser vi ce = ( Cor eSer vi ce) Connect or . open( " i mscor e: / / com. myCompany. games. chess;
user I d=si p: al i ce@home. net ;
ser vi ceI d=game" ) ;
Closing a CoreService
The application SHOULD invoke cl ose on the Cor eSer vi ce when it is finished using the Cor eSer vi ce. The IMS
engine may also close the Cor eSer vi ce due to external events. This will trigger a call to ser vi ceCl osed on the
Cor eSer vi ceLi st ener interface.
See Also:
Cor eSer vi ceLi st ener

Method Summary
Page
Capabi l i t i es
createCapabilities( St r i ng f r omUser I d, St r i ng t oUser I d)
Creates a Capabi l i t i es with f r omUser I d as sender, addressed to t oUser I d.
45
PageMessage
createPageMessage( St r i ng f r omUser I d, St r i ng t oUser I d)
Creates a PageMessage with f r omUser I d as sender, addressed to t oUser I d.
44
Publ i cat i on
createPublication( St r i ng f r omUser I d, St r i ng t oUser I d, St r i ng event )
Creates a Publ i cat i on for an event package with f r omUser I d as sender and t oUser I d
as the user identity to publish event state on.
44
Ref er ence
createReference( St r i ng f r omUser I d, St r i ng t oUser I d, St r i ng r ef er ToUser I d, St r i ng
r ef er Met hod)
Creates a Ref er ence with f r omUser I d as sender, addressed to t oUser I d and
r ef er ToUser I d as the user identity to refer to.
46
Sessi on
createSession( St r i ng f r omUser I d, St r i ng t oUser I d)
Creates a Sessi on with f r omUser I d as sender, addressed to t oUser I d.
45
Subscr i pt i on
createSubscription( St r i ng f r omUser I d, St r i ng t oUser I d, St r i ng event )
Creates a Subscr i pt i on for an event package with f r omUser I d as sender and
t oUser I d as the user identity to subscribe event state on.
45
St r i ng
getLocalUserId( )
Returns the local user identity used in this Cor eSer vi ce.
43
voi d
setListener( Cor eSer vi ceLi st ener l i st ener )
Sets a listener for this Cor eSer vi ce, replacing any previous Cor eSer vi ceLi st ener .
46

Methods inherited from interface javax.microedition.ims.Service
get AppI d, get Scheme

Methods inherited from interface javax.microedition.io.Connection
cl ose
Method Detail
getLocalUserId
St r i ng getLocalUserId( )
Returns the local user identity used in this Cor eSer vi ce.
Returns:
the local user identity

createPageMessage
PageMessage createPageMessage( St r i ng f r omUser I d,
St r i ng t oUser I d)
t hr ows Ser vi ceCl osedExcept i on,
I msExcept i on
Creates a PageMessage with f r omUser I d as sender, addressed to t oUser I d.
Parameters:
f r omUser I d - sender user identity, if nul l the user identity is assumed to be the local user identity
of the Ser vi ce
t oUser I d - the user identity to send a PageMessage to
Returns:
a new PageMessage
Throws:
I msExcept i on - if the PageMessage could not be created
I l l egal Ar gument Except i on - if the t oUser I d argument is nul l ,
if the syntax of the f r omUser I d or t oUser I d argument is invalid

createPublication
Publ i cat i on createPublication( St r i ng f r omUser I d,
St r i ng t oUser I d,
St r i ng event )
I msExcept i on
Creates a Publ i cat i on for an event package with f r omUser I d as sender and t oUser I d as the user
identity to publish event state on.
The event package must be defined as a J AD file property or set with the set Regi st r y method in the
Conf i gur at i on class.
Parameters:
of the Ser vi ce
t oUser I d - the user identity to publish event state information on, if nul l the user identity is
assumed to be the local user identity of the Ser vi ce
event - the event package to publish event state information on
Returns:
a new Publ i cat i on
Throws:
I msExcept i on - if the Publ i cat i on could not be created
I l l egal Ar gument Except i on - if the syntax of the f r omUser I d or t oUser I d argument is invalid,
if the event argument is not a defined event package

createSubscription
Subscr i pt i on createSubscription( St r i ng f r omUser I d,
St r i ng event )
I msExcept i on
Creates a Subscr i pt i on for an event package with f r omUser I d as sender and t oUser I d as the user
identity to subscribe event state on.
The event package must be defined as a J AD file property or set with the set Regi st r y method in the
Conf i gur at i on class.
Parameters:
of the Ser vi ce
t oUser I d - the user identity to subscribe state information on, if nul l the user identity is assumed
to be the local user identity of the Ser vi ce
event - the event package to subscribe state information on
Returns:
a new Subscr i pt i on
Throws:
I msExcept i on - if the Subscr i pt i on could not be created
I l l egal Ar gument Except i on - if the syntax of the f r omUser I d or t oUser I d argument is invalid,
if the event argument is not a defined event package

createCapabilities
Capabi l i t i es createCapabilities( St r i ng f r omUser I d,
I msExcept i on
Creates a Capabi l i t i es with f r omUser I d as sender, addressed to t oUser I d.
Parameters:
of the Ser vi ce
t oUser I d - the remote user identity
Returns:
a new Capabi l i t i es
Throws:
I msExcept i on - if the Capabi l i t i es could not be created

createSession
Sessi on createSession( St r i ng f r omUser I d,
I msExcept i on
Creates a Sessi on with f r omUser I d as sender, addressed to t oUser I d.
Parameters:
of the Ser vi ce
Returns:
a new Sessi on
Throws:
I msExcept i on - if the Sessi on could not be created

createReference
Ref er ence createReference( St r i ng f r omUser I d,
St r i ng r ef er ToUser I d,
St r i ng r ef er Met hod)
I msExcept i on
Creates a Ref er ence with f r omUser I d as sender, addressed to t oUser I d and r ef er ToUser I d as the user
identity to refer to.
Parameters:
of the Ser vi ce
r ef er ToUser I d - the user identity to refer to
r ef er Met hod - the reference method to be used by the reference request, e.g. "INVITE", "BYE",
see 3GPP TS 24.229, Stage 3, release 6
Returns:
a new Ref er ence
Throws:
I msExcept i on - if the Ref er ence could not be created
I l l egal Ar gument Except i on - if the t oUser I d or r ef er ToUser I d argument is nul l ,
if the syntax of the f r omUser I d, t oUser I d or r ef er ToUser I d argument is invalid,
if the r ef er Met hod argument is nul l or if the syntax is invalid

setListener
voi d setListener( Cor eSer vi ceLi st ener l i st ener )
Sets a listener for this Cor eSer vi ce, replacing any previous Cor eSer vi ceLi st ener . A nul l removes any
existing listener.
Parameters:
Interface CoreServiceListener

publ i c i nt er f ace CoreServiceListener
A listener type for receiving notifications on remotely initiated core service methods.
See Also:
Cor eSer vi ce. set Li st ener ( Cor eSer vi ceLi st ener )

Method Summary
Page
voi d
pageMessageReceived( Cor eSer vi ce ser vi ce, PageMessage message)
Notifies the application when a page message is received from a remote endpoint.
47
voi d
referenceReceived( Cor eSer vi ce ser vi ce, Ref er ence r ef er ence)
Notifies the application when a reference request is received from a remote endpoint.
48
voi d
serviceClosed( Cor eSer vi ce ser vi ce)
Notifies the application when a Cor eSer vi ce is closed.
48
voi d
sessionInvitationReceived( Cor eSer vi ce ser vi ce, Sessi on sessi on)
Notifies the application when a session invitation is received from a remote endpoint.
47
voi d
unsolicitedNotifyReceived( Cor eSer vi ce ser vi ce, Message not i f y)
Notifies the application when an unsolicited notify is received.
48
Method Detail
pageMessageReceived
voi d pageMessageReceived( Cor eSer vi ce ser vi ce,
PageMessage message)
Notifies the application when a page message is received from a remote endpoint.
Parameters:
ser vi ce - the concerned Ser vi ce
message - the received PageMessage

sessionInvitationReceived
voi d sessionInvitationReceived( Cor eSer vi ce ser vi ce,
Sessi on sessi on)
Notifies the application when a session invitation is received from a remote endpoint.
Parameters:
sessi on - the received session invitation
See Also:
Sessi on. accept ( ) , Sessi on. r ej ect ( )

referenceReceived
voi d referenceReceived( Cor eSer vi ce ser vi ce,
Ref er ence r ef er ence)
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:
r ef er ence - the received reference

unsolicitedNotifyReceived
voi d unsolicitedNotifyReceived( Cor eSer vi ce ser vi ce,
Message not i f y)
Notifies the application when an unsolicited notify is received. This notify request is received outside any
existing subscription.
Parameters:
not i f y - the received notify

serviceClosed
voi d serviceClosed( Cor eSer vi ce ser vi ce)
Notifies the application when a Cor eSer vi ce is closed.
Parameters:
Interface Message
Interface Message

publ i c i nt er f ace Message
The Message interface provides functionality to manipulate headers and body parts of outgoing request messages
and to inspect previously transferred messages. A Message can be retrieved by calling
Ser vi ceMet hod. get Next Request , Ser vi ceMet hod. get Pr evi ousRequest or
Ser vi ceMet hod. get Pr evi ousResponses.
Restricted headers
The access to these headers is restricted and an exception will be thrown if they are read or modified.
Read-only headers
These headers can only be read, an I msExcept i on should be thrown if the application tries to modify the following
headers:
Accept - Cont act , Cal l - I D, Cont act , Cont ent - Lengt h, Cont ent - Type, CSeq, Event , Fr om,
P- Access- Net wor k- I nf o, P- Asser t ed- I dent i t y, P- Associ at ed- URI , P- Pr ef er r ed- I dent i t y, RAck, Ref er - To,
Ref er r ed- By, Repl aces, RSeq, SI P- ETag, SI P- I f - Mat ch, To, WWW- Aut hent i cat e
Inaccessible headers
These headers can not be read or modified, an I msExcept i on should be thrown if the application tries to read or
modify the following headers:
Aut hent i cat i on- I nf o, Aut hor i zat i on, Max- For war ds, Mi n- Expi r es, Pr oxy- Aut hent i cat e,
Pr oxy- Aut hor i zat i on, Recor d- Rout e, Secur i t y- Cl i ent , Secur i t y- Ser ver , Secur i t y- Ver i f y,
Ser vi ce- Rout e, Vi a
See [RFC3261] for more information about headers and body parts in a request message.
See Also:
Ser vi ceMet hod

Field Summary
Page
i nt
CAPABILITIES_QUERY
Identifier for the quer yCapabi l i t i es method on the Capabi l i t i es interface.
50
i nt
PAGEMESSAGE_SEND
Identifier for the send method on the PageMessage interface.
50
i nt
PUBLICATION_PUBLISH
Identifier for the publ i sh method on the Publ i cat i on interface.
51
i nt
PUBLICATION_UNPUBLISH
Identifier for the unpubl i sh method on the Publ i cat i on interface.
51
i nt
REFERENCE_REFER
Identifier for the r ef er method on the Ref er ence interface.
51
i nt
SESSION_START
Identifier for the st ar t method on the Sessi on interface.
51
i nt
SESSION_TERMINATE
Identifier for the t er mi nat e method on the Sessi on interface.
51
Interface Message
i nt
SESSION_UPDATE
Identifier for the updat e method on the Sessi on interface.
51
i nt
STATE_RECEIVED
This state specifies that this Message was received from a remote endpoint.
52
i nt
STATE_SENT
This state specifies that the Message is sent from the local endpoint.
52
i nt
STATE_UNSENT
This state specifies that the Message is unsent.
52
i nt
SUBSCRIPTION_SUBSCRIBE
Identifier for the subscr i be method on the Subscr i pt i on interface.
51
i nt
SUBSCRIPTION_UNSUBSCRIBE
Identifier for the unsubscr i be method on the Subscr i pt i on interface.
51

Method Summary
Page
voi d
addHeader( St r i ng key, St r i ng val ue)
Adds a header value, either on a new header or appending a new value to an
already existing header.
53
MessageBodyPar t
createBodyPart( )
Creates a new MessageBodyPar t and adds it to the message.
52
MessageBodyPar t [ ]
getBodyParts( )
Returns all body parts that are added to the message.
52
St r i ng[ ]
getHeaders( St r i ng key)
Returns the value(s) of a header in this message.
53
St r i ng
getMethod( )
Returns the SIP method for this Message.
53
St r i ng
getReasonPhrase( )
Returns the reason phrase of the response.
54
i nt
getState( )
Returns the current state of this Message.
53
i nt
getStatusCode( )
Returns the status code of the response.
54
Field Detail
CAPABILITIES_QUERY
publ i c st at i c f i nal i nt CAPABILITIES_QUERY
Identifier for the quer yCapabi l i t i es method on the Capabi l i t i es interface.

PAGEMESSAGE_SEND
publ i c st at i c f i nal i nt PAGEMESSAGE_SEND
Identifier for the send method on the PageMessage interface.

Interface Message
PUBLICATION_PUBLISH
publ i c st at i c f i nal i nt PUBLICATION_PUBLISH
Identifier for the publ i sh method on the Publ i cat i on interface.

PUBLICATION_UNPUBLISH
publ i c st at i c f i nal i nt PUBLICATION_UNPUBLISH
Identifier for the unpubl i sh method on the Publ i cat i on interface.

REFERENCE_REFER
publ i c st at i c f i nal i nt REFERENCE_REFER
Identifier for the r ef er method on the Ref er ence interface.

SESSION_START
publ i c st at i c f i nal i nt SESSION_START
Identifier for the st ar t method on the Sessi on interface.

SESSION_UPDATE
publ i c st at i c f i nal i nt SESSION_UPDATE
Identifier for the updat e method on the Sessi on interface.

SESSION_TERMINATE
publ i c st at i c f i nal i nt SESSION_TERMINATE
Identifier for the t er mi nat e method on the Sessi on interface.

SUBSCRIPTION_SUBSCRIBE
publ i c st at i c f i nal i nt SUBSCRIPTION_SUBSCRIBE
Identifier for the subscr i be method on the Subscr i pt i on interface.

SUBSCRIPTION_UNSUBSCRIBE
publ i c st at i c f i nal i nt SUBSCRIPTION_UNSUBSCRIBE
Identifier for the unsubscr i be method on the Subscr i pt i on interface.
Interface Message

STATE_UNSENT
publ i c st at i c f i nal i nt STATE_UNSENT
This state specifies that the Message is unsent.

STATE_SENT
publ i c st at i c f i nal i nt STATE_SENT
This state specifies that the Message is sent from the local endpoint.

STATE_RECEIVED
publ i c st at i c f i nal i nt STATE_RECEIVED
This state specifies that this Message was received from a remote endpoint.
Method Detail
createBodyPart
MessageBodyPar t createBodyPart( )
t hr ows I msExcept i on
Creates a new MessageBodyPar t and adds it to the message.
Returns:
a MessageBodyPar t
Throws:
I msExcept i on - if the body part could not be created
I l l egal St at eExcept i on - if the Message is not in STATE_UNSENT

getBodyParts
MessageBodyPar t [ ] 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 MessageBodyPar t s in the message body, an empty array will be returned if there are
no body parts in the Message

Interface Message
addHeader
voi d addHeader( St r i ng key,
St r i ng val ue)
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 Wr i t e property of the J AD file or set with the
set Regi st r y method in the Conf i gur at i on class.
Parameters:
key - the header name, in full form (see RFC3261)
val ue - the header value
Throws:
I msExcept i on - if the key is not a defined header or a restricted header
I l l egal Ar gument Except i on - if the key is nul l or invalid,
if the val ue is nul l or invalid

getHeaders
St r i ng[ ] getHeaders( St r i ng key)
Returns the value(s) of a header in this message. The header must be defined in the Read property of the
J AD file or set with the set Regi st r y method in the Conf i gur at i on class.
Parameters:
Returns:
an array of all value(s) of the header, an empty array is returned if the header does not exist
Throws:
I msExcept i on - if the key is not a defined header or a restricted header

getMethod
St r i ng getMethod( )
Returns the SIP method for this Message.
Returns:
SIP method name, INVITE, UPDATE, BYE, etc. or nul l if the method is not available

getState
i nt getState( )
Returns the current state of this Message.
Returns:
the current state of this Message

Interface Message
getStatusCode
i nt 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
St r i ng 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 nul l if the reason phrase is not available
Interface MessageBodyPart

publ i c i nt er f ace MessageBodyPart
A MessageBodyPar t can contain different kinds of content, for example text, an image or an audio clip.
There are two main uses for a MessageBodyPar t :
A MessageBodyPar t can be created and attached to the next outgoing request Message by calling
cr eat eBodyPar t on a Message.
A MessageBodyPar t can be extracted from a previously sent or received Message by calling get BodyPar t s
on a Message.
See [RFC2045, 2046] for more information about body parts. [RFC2045] also describes some possible headers to
set with the set Header method.
See Also:
Ser vi ceMet hod, Message

Method Summary
Page
St r i ng
getHeader( St r i ng key)
Returns the value of a header in this MessageBodyPar t .
56
j ava. i o. I nput St r eam
openContentInputStream( )
Opens an I nput St r eamto read the content of the MessageBodyPar t .
55
j ava. i o. Out put St r eam
openContentOutputStream( )
Opens an Out put St r eamto write the content of the MessageBodyPar t .
55
voi d
setHeader( St r i ng key, St r i ng val ue)
Sets a header to the MessageBodyPar t .
56
Method Detail
openContentInputStream
j ava. i o. I nput St r eamopenContentInputStream( )
t hr ows j ava. i o. I OExcept i on
Opens an I nput St r eamto read the content of the MessageBodyPar t .
Returns:
an I nput St r eamto read the content of the MessageBodyPar t
Throws:
j ava. i o. I OExcept i on - if the I nput St r eamcould not be opened
See Also:
openCont ent Out put St r eam( )

openContentOutputStream
j ava. i o. Out put St r eamopenContentOutputStream( )
Opens an Out put St r eamto write the content of the MessageBodyPar t . If the Out put St r eamis not closed, it
will be closed by the Ser vi ceMet hod that invoked a transmission of the Message.
Returns:
an Out put St r eamto write the content of the MessageBodyPar t
Throws:
j ava. i o. I OExcept i on - if the Out put St r eamcould not be opened or if the Out put St r eamalready
has been opened
See Also:
openCont ent I nput St r eam( )

setHeader
voi d setHeader( St r i ng key,
St r i ng val ue)
Sets a header to the MessageBodyPar t . If the header key already exists the val ue will be replaced.
Only headers with the prefix "Content-" are allowed to set with this method.
Parameters:
val ue - the header value
Throws:
I l l egal Ar gument Except i on - if the key is nul l or invalid,
if the val ue is nul l or invalid
See Also:
get Header ( St r i ng)

getHeader
St r i ng getHeader( St r i ng key)
Returns the value of a header in this MessageBodyPar t .
Only headers with the prefix "Content-" are allowed to be retrieved with this method.
Parameters:
Returns:
a string containing the header value or nul l if the header does not exist
Throws:
I l l egal Ar gument Except i on - if the key is nul l or invalid
See Also:
set Header ( St r i ng, St r i ng)
Interface PageMessage
ServiceMethod

publ i c i nt er f ace 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_RECEI VED.
A PageMessage created with the factory method cr eat ePageMessage in the Cor eSer vi ce 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_RECEI VED.
Example of sending a simple PageMessage
t r y {
PageMessage pageMessage;
pageMessage = ser vi ce. cr eat ePageMessage( nul l , " si p: bal oo@l al aa. net " ) ;
pageMessage. set Li st ener ( t hi s) ;
pageMessage. send( " Hi , I ' mAl i ce! " . get Byt es( ) , " t ext / pl ai n" ) ;
} cat ch ( Except i on e) {
}
Example of sending a multipart PageMessage
t r y {
PageMessage pageMessage;
pageMessage = ser vi ce. cr eat ePageMessage( nul l , " si p: bal oo@l al aa. net " ) ;
pageMessage. set Li st ener ( t hi s) ;
Message message = pageMessage. get Next Request ( ) ;
/ / add f i r st body par t
MessageBodyPar t par t 1 = message. cr eat eBodyPar t ( ) ;
par t 1. set Header ( " Cont ent - Type" , " t ext / pl ai n" ) ;
Out put St r eamos = par t 1. openCont ent Out put St r eam( ) ;
os. wr i t e( . . . ) ;
os. cl ose( ) ;
/ / add f ol l owi ng body par t s
. . .
/ / when al l body par t s has been added
pageMessage. send( nul l , nul l ) ;
} cat ch ( Except i on e) {
}
Example of receiving a PageMessage
The callback method pageMessageRecei ved is found in the Cor eSer vi ceLi st ener interface.
publ i c voi d pageMessageRecei ved( Cor eSer vi ce ser vi ce,
PageMessage pageMessage) {
pageMessage. get Cont ent ( ) ;
. . . / / pr ocess cont ent
}
See Also:
Cor eSer vi ce. cr eat ePageMessage( St r i ng, St r i ng) ,
Cor eSer vi ceLi st ener . pageMessageRecei ved( Cor eSer vi ce, PageMessage)

Field Summary
Page
i nt
STATE_RECEIVED
This state specifies that this PageMessage was received from a remote endpoint.
58
i nt
STATE_SENT
This state specifies that the PageMessage is sent.
58
i nt
STATE_UNSENT
This state specifies that the PageMessage is unsent.
58

Method Summary
Page
byt e[ ]
getContent( )
Returns the content from this PageMessage.
59
St r i ng
getContentType( )
Returns the content MIME type of this PageMessage.
59
i nt
getState( )
Returns the current state of this PageMessage.
60
voi d
send( byt e[ ] cont ent , St r i ng cont ent Type)
Sends the PageMessage.
59
voi d
setListener( PageMessageLi st ener l i st ener )
Sets a listener for this PageMessage, replacing any previous PageMessageLi st ener .
59

Field Detail
STATE_UNSENT
publ i c st at i c f i nal i nt STATE_UNSENT
This state specifies that the PageMessage is unsent.

STATE_SENT
publ i c st at i c f i nal i nt STATE_SENT
This state specifies that the PageMessage is sent.

STATE_RECEIVED
publ i c st at i c f i nal i nt STATE_RECEIVED
This state specifies that this PageMessage was received from a remote endpoint.
Method Detail
send
voi d send( byt e[ ] cont ent ,
St r i ng cont ent Type)
Sends the PageMessage.
This method can be invoked send( nul l , nul l ) if the application uses the Message interface to fill the
content. In the case that the application uses both the Message interface and send( cont ent ,
cont ent Type) , 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:
cont ent - a byte array containing the content to be sent
cont ent Type - the content MIME type
Throws:
I l l egal St at eExcept i on - if the PageMessage is not in STATE_UNSENT
I l l egal Ar gument Except i on - if the syntax of the cont ent Type argument is invalid or if one of the
arguments is nul l

setListener
voi d setListener( PageMessageLi st ener l i st ener )
Sets a listener for this PageMessage, replacing any previous PageMessageLi st ener . A nul l reference is
Parameters:

getContent
byt e[ ] 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:
I l l egal St at eExcept i on - if the PageMessage is not in STATE_RECEI VED

getContentType
St r i ng 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:
I l l egal St at eExcept i on - if the PageMessage is not in STATE_RECEI VED

getState
i nt getState( )
Returns the current state of this PageMessage.
Returns:
the current state of this PageMessage
Interface PageMessageListener
Interface PageMessageListener

publ i c i nt er f ace PageMessageListener
This listener type is used to notify the application about the status of sent page messages.
See Also:
PageMessage. set Li st ener ( PageMessageLi st ener )

Method Summary
Page
voi d
pageMessageDelivered( PageMessage pageMessage)
Notifies the application that the PageMessage was successfully delivered.
61
voi d
pageMessageDeliveryFailed( PageMessage pageMessage)
Notifies the application that the PageMessage was not successfully delivered.
61
Method Detail
pageMessageDelivered
voi d pageMessageDelivered( PageMessage pageMessage)
Notifies the application that the PageMessage was successfully delivered.
Parameters:
pageMessage - the concerned PageMessage

pageMessageDeliveryFailed
voi d pageMessageDeliveryFailed( PageMessage pageMessage)
Notifies the application that the PageMessage was not successfully delivered.
Parameters:
pageMessage - the concerned PageMessage
Interface Publication
ServiceMethod

publ i c i nt er f ace Publication
The Publ i cat i on 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 unpubl i sh is called. Updates of the published event
state may be achieved by calling the publ i sh method again with modified event state.
The life cycle consist of three states, STATE_I NACTI VE, STATE_PENDI NG and STATE_ACTI VE.
A new Publ i cat i on starts in STATE_I NACTI VE and when publ i sh is called the state transits to STATE_PENDI NG
and remains there until a response arrives from the remote endpoint.
In STATE_ACTI VE, unpubl i sh can be called to cancel the publication and the state will then transit to
STATE_PENDI NG and remain there until a response arrives from the remote endpoint.
Example of a simple Publication
t r y {
pub = ser vi ce. cr eat ePubl i cat i on( nul l , " si p: al i ce@home. net " , " pr esence" ) ;
pub. set Li st ener ( t hi s) ;
pub. publ i sh( onl i neSt at us, " appl i cat i on/ pi df +xml " ) ;
}

publ i c voi d publ i cat i onDel i ver ed( Publ i cat i on pub) {
/ / i f t he publ i sh was successf ul l
}

Example of a multipart Publication
t r y {
pub = ser vi ce. cr eat ePubl i cat i on( nul l , " si p: al i ce@home. net " , " pr esence" ) ;
pub. set Li st ener ( t hi s) ;
Message message = pub. get Next Request ( ) ;
/ / add f i r st body par t
par t 1. set Header ( " Cont ent - Type" , " appl i cat i on/ pi df +xml " ) ;
Out put St r eamos = par t 1. openCont ent Out put St r eam( ) ;
os. wr i t e( . . . ) ;
os. cl ose( ) ;
/ / add f ol l owi ng body par t s
. . .
/ / when al l body par t s has been added
pub. publ i sh( nul l , nul l ) ;
}

publ i c voi d publ i cat i onDel i ver ed( Publ i cat i on pub) {
/ / i f t he publ i sh was successf ul l
}

See Also:
Cor eSer vi ce. cr eat ePubl i cat i on( St r i ng, St r i ng, St r i ng) , Subscr i pt i on

Field Summary
Page
i nt
STATE_ACTIVE
The Publ i cat i on is active and event state is available for subscription.
63
i nt
STATE_INACTIVE
The Publ i cat i on is not active, event state is not published.
63
i nt
STATE_PENDING
A Publ i cat i on request is sent and the platform is waiting for a response.
63

Method Summary
Page
St r i ng
getEvent( )
Returns the event package corresponding to this Publ i cat i on.
64
i nt
getState( )
Returns the current state of the state machine of this Publ i cat i on.
65
voi d
publish( byt e[ ] st at e, St r i ng cont ent Type)
Sends a publication request with an event state to the remote endpoint.
64
voi d
setListener( Publ i cat i onLi st ener l i st ener )
Sets a listener for this Publ i cat i on, replacing any previous Publ i cat i onLi st ener .
64
voi d
unpublish( )
Terminates this publication.
64

Field Detail
STATE_INACTIVE
The Publ i cat i on is not active, event state is not published.

STATE_PENDING
A Publ i cat i on request is sent and the platform is waiting for a response.

STATE_ACTIVE
The Publ i cat i on is active and event state is available for subscription.
Method Detail
publish
voi d publish( byt e[ ] st at e,
St r i ng cont ent Type)
Sends a publication request with an event state to the remote endpoint.
This method can be invoked publ i sh( nul l , nul l ) if the application uses the Message interface to fill the
event state. In the case that the application uses both the Message interface and publ i sh( st at e,
cont ent Type) , the event state will be added as the last body part.
The Publ i cat i on will transit to STATE_PENDI NG after calling this method. See example above.
Parameters:
st at e - event state to publish
Throws:
I l l egal St at eExcept i on - if the Publ i cat i on is in STATE_PENDI NG
I l l egal Ar gument Except i on - if the syntax of the cont ent Type argument is invalid or if one of the
arguments is nul l

unpublish
voi d unpublish( )
Terminates this publication.
The Publ i cat i on will transit to STATE_PENDI NG after calling this method.
Throws:
I l l egal St at eExcept i on - if the Publ i cat i on is not in STATE_ACTI VE

setListener
voi d setListener( Publ i cat i onLi st ener l i st ener )
Sets a listener for this Publ i cat i on, replacing any previous Publ i cat i onLi st ener . A nul l reference is
Parameters:

getEvent
St r i ng getEvent( )
Returns the event package corresponding to this Publ i cat i on.
Returns:
the event package

getState
i nt getState( )
Returns the current state of the state machine of this Publ i cat i on.
Returns:
the current state
Interface PublicationListener

publ i c i nt er f ace PublicationListener
This listener type is used to notify the application of the status of requested publications.
See Also:
Publ i cat i on. set Li st ener ( Publ i cat i onLi st ener )

Method Summary
Page
voi d
publicationDelivered( Publ i cat i on publ i cat i on)
Notifies the application that the publication request was successfully delivered.
66
voi d
publicationDeliveryFailed( Publ i cat i on publ i cat i on)
Notifies the application that the publication request was not successfully delivered.
66
voi d
publicationTerminated( Publ i cat i on publ i cat i on)
Notifies the application that the publication was terminated.
66
Method Detail
publicationDelivered
voi d publicationDelivered( Publ i cat i on publ i cat i on)
Notifies the application that the publication request was successfully delivered.
The Publ i cat i on has transited to STATE_ACTI VE.
Parameters:
publ i cat i on - the concerned Publ i cat i on

publicationDeliveryFailed
voi d publicationDeliveryFailed( Publ i cat i on publ i cat i on)
Notifies the application that the publication request was not successfully delivered.
The Publ i cat i on has transited to either STATE_ACTI VE or STATE_I NACTI VE.
Parameters:

publicationTerminated
voi d publicationTerminated( Publ i cat i on publ i cat i on)
Notifies the application that the publication was terminated.
The Publ i cat i on has transited to STATE_I NACTI VE.
Parameters:
Interface Reference
Interface Reference
ServiceMethod

publ i c i nt er f ace Reference
The Ref er ence is used for referring a remote endpoint to a third party user or service. The Ref er ence 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 Ref er ence has four states: STATE_I NI TI ATED, STATE_PROCEEDI NG, STATE_REFERRI NG and STATE_TERMI NATED.
Interface Reference
Reference States
This section describes the semantics for each of the Ref er ence states at the local and remote endpoint.
Local endpoint
STATE_INITIATED
When a Ref er ence is created it will enter STATE_I NI TI ATED.
A Ref er ence transits to:
STATE_PROCEEDI NG when r ef er is called on the Ref er ence.
STATE_PROCEEDING
When r ef er is called the Ref er ence enters STATE_PROCEEDI NG. Once this state is entered the communication with
the remote endpoint starts and a reference is sent to the remote endpoint.
STATE_REFERRI NG if the remote endpoint received the reference. The r ef er enceDel i ver ed method will be
invoked.
STATE_TERMI NATED if the remote endpoint did not receive the reference. The r ef er enceDel i ver yFai l ed
method will be invoked.
STATE_REFERRING
In this state the Ref er ence 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
r ef er enceNot i f y callback on the Ref er enceLi st ener .
STATE_TERMI NATED if the reference is considered as terminated. The r ef er enceTer mi nat ed method will
be invoked.
STATE_TERMINATED
In this state the Ref er ence has been rejected or terminated and any further actions on the Ref er ence object are
invalid.
Remote endpoint
STATE_PROCEEDING
An incoming reference request always starts in STATE_PROCEEDI NG.
STATE_REFERRI NG if accept is called on the reference.
STATE_TERMI NATED if reject is called on the reference.
STATE_REFERRING
The remote endpoint has accepted the reference and is now responsible to contact the third party with the
reference method provided with the get Ref er Met hod. 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.
Interface Reference
STATE_TERMI NATED if the remote endpoint contacted the third party or if the reference has failed. The
r ef er enceTer mi nat ed method will be invoked
STATE_TERMINATED
The Ref er ence is considered as terminated and any further actions on the Ref er ence object are invalid.
Example usage of Reference
The scenario below illustrates how Ref er ence 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 App is an IMS Application
running on her Device, for instance a Mobile Phone.
Create a Reference
In this example code, Alice tells Bob to establish a session with Charlotte.
t r y {
Ref er ence r ef = ser vi ce. cr eat eRef er ence( " si p: al i ce@home. net " ,
" si p: bob@home. net " ,
" si p: char l ot t e@home. net " ,
" I NVI TE" ) ;
r ef . set Li st ener ( t hi s)
r ef . r ef er ( ) ;

}

publ i c voi d r ef er enceDel i ver ed( Ref er ence r ef er ence) {
/ / i f t he r ef er ence was del i ver ed
}

publ i c voi d r ef er enceDel i ver yFai l ed( Ref er ence r ef er ence) {
/ / i f t he r ef er ence was not del i ver ed
}

publ i c voi d r ef er enceNot i f y( Ref er ence r ef er ence, Message not i f y) {
/ / check pr ogr ess of t he r ef er ence
}

publ i c voi d r ef er enceTer mi nat ed( Ref er ence r ef er ence) {
/ / t he r ef er ence i s t er mi nat ed
}
Accept a Reference
Bob receives a reference request and decides to accept it.
publ i c voi d r ef er enceRecei ved( Cor eSer vi ce ser vi ce, Ref er ence r ef er ence) {
St r i ng r ef er ToUser I d = r ef er ence. get Ref er ToUser I d( ) ;
St r i ng r ef er Met hod = r ef er ence. get Ref er Met hod( ) ;
/ / not i f y t he appl i cat i on of t he r ef er ence
. . .
r ef er ence. accept ( ) ;
/ / assume r ef er Met hod == " I NVI TE"
mySessi on = ser vi ce. cr eat eSessi on( nul l , r ef er ToUser I d) ;
/ / connect t he r ef er ence wi t h t he I MS engi ne
r ef er ence. connect Ref er Met hod( ( Ser vi ceMet hod) mySessi on) ;
/ / st ar t t he r ef er ence wi t h t he t hi r d par t y
}
Interface Reference

Figure 2: A simplified picture of the interaction between Alice, Bob and Charlotte.
See Also:
Cor eSer vi ce. cr eat eRef er ence( St r i ng, St r i ng, St r i ng, St r i ng) , Sessi on. cr eat eRef er ence( St r i ng,
St r i ng) , Cor eSer vi ceLi st ener , Ref er enceLi st ener

Field Summary
Page
i nt
STATE_INITIATED
This state specifies that the Ref er ence is created but not started.
72
i nt
STATE_PROCEEDING
This state specifies that the Ref er ence has been started.
72
i nt
STATE_REFERRING
This state specifies that the Ref er ence has been accepted and that the remote endpoint is
referring to the third party.
72
i nt
STATE_TERMINATED
This state specifies that the Ref er ence has been rejected or terminated.
72

Method Summary
Page
voi d
accept( )
Accepts an incoming reference request.
73
voi d
connectReferMethod( Ser vi ceMet hod ser vi ceMet hod)
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.
74
St r i ng
getReferMethod( )
Returns the reference method to be used.
73
Interface Reference
St r i ng
getReferToUserId( )
Returns the user identity to refer to.
73
i nt
getState( )
Returns the current state of this Ref er ence.
74
voi d
refer( )
Sends the reference request to the remote endpoint.
72
voi d
reject( )
Rejects an incoming reference request.
73
voi d
setListener( Ref er enceLi st ener l i st ener )
Sets a listener for this Ref er ence, replacing any previous Ref er enceLi st ener .
74

Field Detail
STATE_INITIATED
publ i c st at i c f i nal i nt STATE_INITIATED
This state specifies that the Ref er ence is created but not started.

STATE_PROCEEDING
publ i c st at i c f i nal i nt STATE_PROCEEDING
This state specifies that the Ref er ence has been started.

STATE_REFERRING
publ i c st at i c f i nal i nt STATE_REFERRING
This state specifies that the Ref er ence has been accepted and that the remote endpoint is referring to the
third party.

STATE_TERMINATED
publ i c st at i c f i nal i nt STATE_TERMINATED
This state specifies that the Ref er ence has been rejected or terminated.
Method Detail
refer
voi d refer( )
Sends the reference request to the remote endpoint.
Interface Reference
The Ref er ence will transit to STATE_PROCEEDI NG after calling this method.
Throws:
I l l egal St at eExcept i on - if the Ref er ence is not in STATE_I NI TI ATED

getReferToUserId
St r i ng getReferToUserId( )
Returns the user identity to refer to.
Returns:
the user identity

getReferMethod
St r i ng getReferMethod( )
Returns the reference method to be used.
Returns:
the reference method

accept
voi d accept( )
Accepts an incoming reference request.
The Ref er ence will transit to STATE_REFERRI NG 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:
I l l egal St at eExcept i on - if the Ref er ence is not in STATE_PROCEEDI NG

reject
voi d reject( )
Rejects an incoming reference request.
The Ref er ence will transit to STATE_TERMI NATED after calling this method.
Throws:
I l l egal St at eExcept i on - if the Ref er ence is not in STATE_PROCEEDI NG
Interface Reference

connectReferMethod
voi d connectReferMethod( Ser vi ceMet hod ser vi ceMet hod)
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:
ser vi ceMet hod - the Ser vi ceMet hod to connect
Throws:
I l l egal St at eExcept i on - if the Ref er ence is not in STATE_REFERRI NG
I l l egal Ar gument Except i on - if the ser vi ceMet hod argument is nul l

getState
i nt getState( )
Returns the current state of this Ref er ence.
Returns:
the current state of this Ref er ence

setListener
voi d setListener( Ref er enceLi st ener l i st ener )
Sets a listener for this Ref er ence, replacing any previous Ref er enceLi st ener . A nul l value is allowed
and has the effect of removing any existing listener.
Parameters:
Interface ReferenceListener

publ i c i nt er f ace ReferenceListener
This listener type is used to notify an application about events regarding a Ref er ence.
See Also:
Ref er ence. set Li st ener ( Ref er enceLi st ener )

Method Summary
Page
voi d
referenceDelivered( Ref er ence r ef er ence)
Notifies the application that the reference was successfully delivered.
75
voi d
referenceDeliveryFailed( Ref er ence r ef er ence)
Notifies the application that the reference was not successfully delivered.
75
voi d
referenceNotify( Ref er ence r ef er ence, Message not i f y)
Notifies the application with status reports regarding the Ref er ence.
76
voi d
referenceTerminated( Ref er ence r ef er ence)
Notifies the application that a reference has been terminated.
76
Method Detail
referenceDelivered
voi d referenceDelivered( Ref er ence r ef er ence)
Notifies the application that the reference was successfully delivered.
This method is invoked at the endpoint that sent the reference request.
The Ref er ence has transited to STATE_REFERRI NG.
Parameters:
r ef er ence - the concerned Ref er ence

referenceDeliveryFailed
voi d referenceDeliveryFailed( Ref er ence r ef er ence)
Notifies the application that the reference was not successfully delivered.
The Ref er ence has transited to STATE_TERMI NATED.
Parameters:

referenceTerminated
voi d referenceTerminated( Ref er ence r ef er ence)
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 Ref er ence has transited to STATE_TERMI NATED.
Parameters:

referenceNotify
voi d referenceNotify( Ref er ence r ef er ence,
Message not i f y)
Notifies the application with status reports regarding the Ref er ence.
Parameters:
not i f y - a status report regarding the Ref er ence
Interface ServiceMethod
Capabilities, PageMessage, Publication, Reference, Session, Subscription

publ i c i nt er f ace ServiceMethod
The Ser vi ceMet hod 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:
Sessi on mySessi on;
Message myMessage;

mySessi on = cor eSer vi ce. cr eat eSessi on( nul l , " si p: bob@home. net " ) ;
myMessage = mySessi on. get Next Request ( ) ;
myMessage. addHeader ( " P- I mageI ncl uded" , " yes" ) ;
In this code example, mySessi on. st ar t ( ) is the triggering interface method that sends a session invitation with a
header " P- I mageI ncl uded" 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 Cor eSer vi ce interface. To learn
more about using the different service methods please refer to the related interfaces, see list below:
Capabi l i t i es
PageMessage
Publ i cat i on
Sessi on
Subscr i pt i on
Ref er ence
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- I mageI ncl uded"
header in the initial INVITE method.
Originating endpoint
Sessi on mySessi on = mySer vi ce. cr eat eSessi on( . . . ) ;
. . .
Message myMessage = mySessi on. get Next Request ( ) ;
myMessage. addHeader ( " P- I mageI ncl uded" , " yes" ) ;
MessageBodyPar t messagePar t = myMessage. cr eat eBodyPar t ( ) ;
messagePar t . set Header ( " Cont ent - Type" , " i mage/ j peg" ) ;
Out put St r eamos = messagePar t . openCont ent Out put St r eam( ) ;
os. wr i t e( i mageDat a) ;
os. cl ose( ) ;
Terminating endpoint
publ i c voi d sessi onI nvi t at i onRecei ved( Cor eSer vi ce ser vi ce, Sessi on sessi on) {

Message mess = sessi on. get Pr evi ousRequest ( Message. SESSI ON_START) ;

i f ( " yes" . equal s( mess. get Header s( " P- I mageI ncl uded" ) [ 0] ) ) {
MessageBodyPar t [ ] par t s = mess. get BodyPar t s( ) ;

f or ( i nt i = 0; i par t s. l engt h; i ++) {
i f ( " i mage/ j peg" . equal s( par t s[ i ] . get Header ( " Cont ent - Type" ) ) ) {
I nput St r eami s = par t s[ i ] . openCont ent I nput St r eam( ) ;
byt e[ ] dat a = new byt e[ 1024] ;
/ / r ead cont ent
whi l e ( ( i s. r ead( dat a) ) ! = - 1) {
. . .
}
}
}
}
}

Method Summary
Page
Message
getNextRequest( )
This method returns a handle to the next outgoing request Message within this
Ser vi ceMet hod to be manipulated by the local endpoint.
80
Message
getPreviousRequest( i nt met hod)
This method enables the user to inspect a previously sent or received request message.
80
Message[ ]
getPreviousResponses( i nt met hod)
This method enables the user to inspect previously sent or received response messages.
80
St r i ng
getRemoteUserId( )
Returns the remote user identity of this Ser vi ceMet hod.
79
Method Detail
getRemoteUserId
St r i ng getRemoteUserId( )
Returns the remote user identity of this Ser vi ceMet hod.
Returns:
the remote user identity or nul l 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 Ser vi ceMet hod to be
manipulated by the local endpoint.
Returns:
the next outgoing request Message created for this Ser vi ceMet hod

getPreviousRequest
Message getPreviousRequest( i nt met hod)
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 nul l if the interface
method identifier has not been sent/received.
See Message for valid interface method identifiers to retrieve.
Parameters:
met hod - the interface method identifier
Returns:
the request Message
Throws:
I l l egal Ar gument Except i on - if the met hod argument is not a valid identifier

getPreviousResponses
Message[ ] getPreviousResponses( i nt met hod)
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
nul l if the interface method identifier has not been sent/received.
See Message for valid interface method identifiers to retrieve.
Parameters:
met hod - the interface method identifier
Returns:
an array containing all responses associated to the method
Throws:
I l l egal Ar gument Except i on - if the met hod argument is not a valid identifier
Interface Session
Interface Session
ServiceMethod

publ i c i nt er f ace Session
The Sessi on is a representation of a media exchange between two IMS endpoints. A Sessi on can be created
either locally through calling Cor eSer vi ce. cr eat eSessi on, or by a remote user, in which case the session will be
passed as a parameter to Cor eSer vi ceLi st ener . sessi onI nvi t at i onRecei ved.
A Sessi on is able to carry media of the type Medi a. Medi a objects represent a media connection and not the
media/content itself.
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 Sessi on has eight states: STATE_I NI TI ATED, STATE_NEGOTI ATI NG, STATE_ESTABLI SHI NG, STATE_ESTABLI SHED,
STATE_RENEGOTI ATI NG, STATE_REESTABLI SHI NG, STATE_TERMI NATI NG and STATE_TERMI NATED. 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.
Interface Session
Mobile Originated Session Establishment

Figure 1: The mobile originated session establishment states, all states and transitions are not shown

STATE_INITIATED
When a Sessi on is created through a call to Cor eSer vi ce. cr eat eSessi on, it will enter STATE_I NI TI ATED. After
the Sessi on is created, media can be added by calling Sessi on. cr eat eMedi a
A Sessi on transits to:
STATE_NEGOTI ATI NG when st ar t is called on the Sessi on.
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_NEGOTI ATI NG the listener method sessi onAl er t i ng will be called when the remote endpoint has
received the session invitation.
Interface Session
STATE_ESTABLI SHED if the remote endpoint accepts the session invitation. The sessi onSt ar t ed callback
will then be invoked.
STATE_TERMI NATED if the remote endpoint rejects the session invitation. The sessi onSt ar t Fai l ed
callback will then be invoked.
Mobile Terminated Session Establishment

Figure 2: The mobile terminated session establishment states, all states and transitions are not shown

Interface Session
STATE_INITIATED
STATE_I NI TI ATED is irrelevant to a receiving terminal because as soon as it is notified of an invitation the session
is already in STATE_NEGOTI ATI NG.
STATE_NEGOTIATING
When a session invitation reaches the terminating application it will be notified by a call to
sessi onI nvi t at i onRecei ved and the Sessi on will reside in STATE_NEGOTI ATI NG.
STATE_ESTABLI SHI NG if accept is called on the Sessi on.
STATE_TERMI NATED if r ej ect is called on the Sessi on.
STATE_ESTABLISHING
In this state accept has been called and the Sessi on is about to be established at both endpoints. A Sessi on
transits to:
STATE_ESTABLI SHED when the callback sessi onSt ar t ed 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
A Sessi on assumes STATE_RENEGOTI ATI NG through a call to updat e. Incoming session updates from the remote
endpoint will be discarded in this state.
A Sessi on transits back to STATE_ESTABLI SHED when the listener method:
sessi onUpdat ed is called, meaning that the remote endpoint accepted the new session offer.
sessi onUpdat eFai l ed is called, but here meaning that the remote endpoint rejected the update and the
session keeps its previous settings.
Mobile Terminated Session Renegotiation
STATE_RENEGOTIATING
If the remote endpoint has offered changes to the session, the state will transit to STATE_RENEGOTI ATI NG and the
session will be notified with a call to the sessi onUpdat eRecei ved in the Sessi onLi st ener interface.
STATE_REESTABLI SHI NG if the accept method of the Sessi on is called, thus the media offer is accepted.
STATE_ESTABLI SHED if the r ej ect method is called but in this case the session will keep its old settings.
Interface Session
STATE_REESTABLISHING
In this state accept has been called and the Sessi on is about to be updated at both endpoints. A Sessi on transits
to:
STATE_ESTABLI SHED when the callback sessi onUpdat ed is invoked.
Session Termination
The t er mi nat e method can be called from both endpoints on the Sessi on and thereby cancel the ongoing session
establishment or terminate a Sessi on in progress.
STATE_TERMINATING
A Sessi on enters STATE_TERMI NATI NG when the t er mi nat e method has been called on a Sessi on.
STATE_TERMI NATED when the remote endpoint has acknowledged the terminate request. The
sessi onTer mi nat ed callback will then be invoked.
An incoming terminate request from the remote endpoint is notified with the sessi onTer mi nat ed callback.

Field Summary
Page
i nt
STATE_ESTABLISHED
This state specifies that the Sessi on is established.
87
i nt
STATE_ESTABLISHING
This state specifies that the Sessi on is accepted by the mobile terminated endpoint.
87
i nt
STATE_INITIATED
This state specifies that the Sessi on is created but not started.
86
i nt
STATE_NEGOTIATING
This state specifies that the Sessi on establishment has been started.
86
i nt
This state specifies that the Sessi on update is accepted by the mobile terminated
endpoint.
87
i nt
STATE_RENEGOTIATING
This state specifies that the Sessi on is negotiating updates to the session.
87
i nt
STATE_TERMINATED
This state specifies that the Sessi on has been terminated.
87
i nt
STATE_TERMINATING
This state specifies that an established Sessi on is being terminated by the local endpoint.
87

Method Summary
Page
voi d
accept( )
This method can be used to accept a session invitation or a session update
depending on the context.
89
Capabi l i t i es
createCapabilities( )
Creates a Capabi l i t i es with the remote endpoint.
90
Medi a
createMedia( St r i ng t ype, i nt di r ect i on)
Creates a Medi a object with a media type name and adds it to the Sessi on.
89
Interface Session
Ref er ence
createReference( St r i ng r ef er ToUser I d, St r i ng r ef er Met hod)
This method is used for referring the remote endpoint to a third party user or
service.
90
Medi a[ ]
getMedia( )
Returns the Medi a that are part of this Sessi on.
89
Sessi onDescr i pt or
getSessionDescriptor( )
Returns the session descriptor associated with this Sessi on.
91
i nt
getState( )
Returns the current state of this Sessi on.
88
bool ean
hasPendingUpdate( )
This method checks if there are changes in this Sessi on that have not been
negotiated.
91
voi d
reject( )
This method can be used to r ej ect a session invitation or a session update
depending on the context.
90
voi d
removeMedia( Medi a medi a)
Removes a Medi a from the Sessi on.
89
voi d
restore( )
This method removes all updates that have been made to this Sessi on and to
medias that are part of this Sessi on that have not been negotiated.
91
voi d
setListener( Sessi onLi st ener l i st ener )
Sets a listener for this Sessi on, replacing any previous SessionListener.
87
voi d
start( )
Starts a session.
88
voi d
terminate( )
Terminate or cancel a session.
88
voi d
update( )
Synchronizes the session modifications that an application has done with the
remote endpoint.
88

Field Detail
STATE_INITIATED
publ i c st at i c f i nal i nt STATE_INITIATED
This state specifies that the Sessi on is created but not started.

STATE_NEGOTIATING
publ i c st at i c f i nal i nt STATE_NEGOTIATING
This state specifies that the Sessi on establishment has been started.

Interface Session
STATE_ESTABLISHING
publ i c st at i c f i nal i nt STATE_ESTABLISHING
This state specifies that the Sessi on is accepted by the mobile terminated endpoint.

STATE_ESTABLISHED
publ i c st at i c f i nal i nt STATE_ESTABLISHED
This state specifies that the Sessi on is established.

STATE_RENEGOTIATING
publ i c st at i c f i nal i nt STATE_RENEGOTIATING
This state specifies that the Sessi on is negotiating updates to the session.

publ i c st at i c f i nal i nt STATE_REESTABLISHING
This state specifies that the Sessi on update is accepted by the mobile terminated endpoint.

STATE_TERMINATING
publ i c st at i c f i nal i nt STATE_TERMINATING
This state specifies that an established Sessi on is being terminated by the local endpoint.

STATE_TERMINATED
publ i c st at i c f i nal i nt STATE_TERMINATED
This state specifies that the Sessi on has been terminated.
Method Detail
setListener
voi d setListener( Sessi onLi st ener l i st ener )
Sets a listener for this Sessi on, replacing any previous SessionListener. A nul l reference is allowed and
has the effect of removing any existing listener.
Parameters:
l i st ener - the listener to set

Interface Session
update
voi d 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 Sessi on will transit to STATE_RENEGOTI ATI NG after calling this method.
Throws:
I msExcept i on - if a Medi a in the Sessi on is not initiated correctly or if there are no Medi a in the
Sessi on
I l l egal St at eExcept i on - if the hasPendi ngUpdat e method returns false, meaning that there are
no updates to be made to the session,
if the Sessi on is not in STATE_ESTABLI SHED

start
voi d start( )
Starts a session. When this method is called the remote endpoint is invited to the session.
The Sessi on will transit to STATE_NEGOTI ATI NG after calling this method.
Throws:
I msExcept i on - if a Medi a in the Sessi on is not initiated correctly or if there are no Medi a in the
Sessi on
I l l egal St at eExcept i on - if the Sessi on is not in STATE_I NI TI ATED

terminate
voi d terminate( )
Terminate or cancel a session. A session that has been started should always be terminated using this
method.
The Sessi on will transit to STATE_TERMI NATI NG.
If the Sessi on is STATE_TERMI NATI NG or STATE_TERMI NATED this method will not do anything.
If the Sessi on is STATE_I NI TI ATED the Sessi on will transit directly to STATE_TERMI NATED, the
sessi onTer mi nat ed callback will not be invoked.

getState
i nt getState( )
Returns the current state of this Sessi on.
Returns:
the current state of this Sessi on

Interface Session
createMedia
Medi a createMedia( St r i ng t ype,
i nt di r ect i on)
Creates a Medi a object with a media type name and adds it to the Sessi on. The following type names are
recognized in this specification: BasicUnreliableMedia, BasicReliableMedia, FramedMedia and
StreamMedia.
If a Medi a is added to an established Sessi on, the application has the responsibility to call updat e on the
Sessi on.
Parameters:
t ype - a Medi a type name
di r ect i on - the direction of the Medi a flow
Returns:
a new Medi a implementing the type name interface
Throws:
I msExcept i on - if the t ype could not be created
I l l egal Ar gument Except i on - if the di r ect i on argument is invalid
I l l egal St at eExcept i on - if the Sessi on is not in STATE_ESTABLI SHED, STATE_I NI TI ATED
See Also:
Medi a

removeMedia
voi d removeMedia( Medi a medi a)
Removes a Medi a from the Sessi on.
If a Medi a is removed from an established Sessi on, the application has the responsibility to call updat e on
the Sessi on.
Parameters:
medi a - the Medi a to remove from the Sessi on
Throws:
I l l egal Ar gument Except i on - if the Medi a does not exist in the Sessi on or nul l
I l l egal St at eExcept i on - if the Sessi on is not in STATE_ESTABLI SHED, STATE_I NI TI ATED

getMedia
Medi a[ ] getMedia( )
Returns the Medi a that are part of this Sessi on. An empty array will be returned if there are no Medi a in the
Sessi on.
Returns:
an array of all Medi a in the Sessi on
Throws:
I l l egal St at eExcept i on - if the Sessi on is in STATE_TERMI NATED

accept
voi d accept( )
Interface Session
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_NEGOTI ATI NG if the remote endpoint has
initiated the session. The Sessi on will transit to STATE_ESTABLI SHI NG.
It can be used to accept a session update in STATE_RENEGOTI ATI NG if the remote endpoint has
initiated the session update. The Sessi on will transit to STATE_REESTABLI SHI NG.
Throws:
I l l egal St at eExcept i on - if the Sessi on is not in STATE_NEGOTI ATI NG or STATE_RENEGOTI ATI NG

createCapabilities
Capabi l i t i es createCapabilities( )
Creates a Capabi l i t i es with the remote endpoint.
Returns:
a new Capabi l i t i es
Throws:
I l l egal St at eExcept i on - if the Sessi on is not in STATE_ESTABLI SHED

createReference
Ref er ence createReference( St r i ng r ef er ToUser I d,
St r i ng r ef er Met hod)
This method is used for referring the remote endpoint to a third party user or service.
Parameters:
r ef er ToUser I d - the user identity to refer to
r ef er Met hod - the reference method to be used by the reference request, e.g. "INVITE", "BYE",
see 3GPP TS 24.229, Stage 3, release 6
Returns:
a new Ref er ence
Throws:
I l l egal Ar gument Except i on - if the r ef er ToUser I d argument is nul l or if the syntax is invalid,
if the r ef er Met hod argument is nul l or if the syntax is invalid

reject
voi d reject( )
This method can be used to r ej ect a session invitation or a session update depending on the context.
It can be used to r ej ect a session invitation in STATE_NEGOTI ATI NG if the remote endpoint has
initiated the session. The Sessi on will transit to STATE_TERMI NATED.
It can be used to r ej ect a session update in STATE_RENEGOTI ATI NG if the remote endpoint has
initiated the session update. The Sessi on will transit to STATE_ESTABLI SHED and the update is
discarded.
Throws:
I l l egal St at eExcept i on - if the Sessi on is not in STATE_NEGOTI ATI NG or STATE_RENEGOTI ATI NG
Interface Session

getSessionDescriptor
Sessi onDescr i pt or getSessionDescriptor( )
Returns the session descriptor associated with this Sessi on.
Returns:
the session descriptor

hasPendingUpdate
bool ean hasPendingUpdate( )
This method checks if there are changes in this Sessi on that have not been negotiated.
Returns:
t r ue if there is a pending update, f al se otherwise

restore
voi d restore( )
This method removes all updates that have been made to this Sessi on and to medias that are part of this
Sessi on that have not been negotiated.
Throws:
Interface SessionDescriptor

publ i c i nt er f ace SessionDescriptor
The Session Description Protocol (SDP) provides a standard representation of media details, transport addresses
and other session descriptions to the participants.
When one endpoint would like to start a new session containing media, or extend an existing session with new
media, it has to formulate an SDP offer. An SDP offer contains a range of available codecs that the client supports
and at which port(s) the terminal has opened for media streams. The SDP offer is then sent to the remote endpoint
and it will be negotiated until both endpoints agree on the session setup. In the response to the SDP offer the
remote endpoint states which port(s) it has opened for media streams.
An SDP description is denoted by the content MIME type "application/sdp" and is divided into three different parts:
session description, time description and media description. This interface covers the session description, see
Medi aDescr i pt or for more details on the media descriptor. See [RFC4566] for more detailed information about the
SDP.
A SDP offer for a session with one audio media and one video media could look like this:
v=0
o=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com
s=
c=IN IP4 host.atlanta.example.com
t=0 0
m=audi o 49170 RTP/ AVP 0 8 97
a=r t pmap: 0 PCMU/ 8000
a=r t pmap: 8 PCMA/ 8000
a=r t pmap: 97 i LBC/ 8000
m=vi deo 51372 RTP/ AVP 31 32
a=r t pmap: 31 H261/ 90000
a=r t pmap: 32 MPV/ 90000
See Also:
Medi aDescr i pt or

Method Summary
Page
voi d
addAttribute( St r i ng at t r i but e)
Adds an attribute to the Sessi on.
94
St r i ng[ ]
getAttributes( )
Returns all attributes for the Sessi on.
95
St r i ng
getProtocolVersion( )
Returns the version of the Session Description Protocol.
93
St r i ng
getSessionId( )
Returns a unique identifier for the session.
93
St r i ng
getSessionInfo( )
Returns textual information about the session.
94
St r i ng
getSessionName( )
Returns the textual session name.
93
voi d
removeAttribute( St r i ng at t r i but e)
Removes an attribute from the Sessi on.
94
voi d
setSessionInfo( St r i ng i nf o)
Sets the textual information about the session.
94
voi d
setSessionName( St r i ng name)
Sets the name of the session.
93
Method Detail
getProtocolVersion
St r i ng getProtocolVersion( )
Returns the version of the Session Description Protocol.
See [RFC4566], chapter 5.1. for more information.
Returns:
the protocol version or nul l if the protocol version could not be retrieved

getSessionId
St r i ng getSessionId( )
Returns a unique identifier for the session.
Returns:
the Sessi on identifier or nul l if the session identifier could not be retrieved

getSessionName
St r i ng getSessionName( )
Returns the textual session name.
Returns:
the Sessi on name or nul l if the session name is not set
See Also:
set Sessi onName( St r i ng)

setSessionName
voi d setSessionName( St r i ng name)
Sets the name of the session.
Parameters:
name - the session name
Throws:
I l l egal Ar gument Except i on - if the name argument is nul l
See Also:
get Sessi onName( )

getSessionInfo
St r i ng getSessionInfo( )
Returns textual information about the session. This method provides a human-readable description of the
session.
Returns:
Sessi on information or nul l if the session information is not set
See Also:
set Sessi onI nf o( St r i ng)

setSessionInfo
voi d setSessionInfo( St r i ng i nf o)
Sets the textual information about the session.
Parameters:
i nf o - session information
Throws:
I l l egal Ar gument Except i on - if the i nf o argument is nul l
See Also:
get Sessi onI nf o( )

removeAttribute
voi d removeAttribute( St r i ng at t r i but e)
Removes an attribute from the Sessi on.
The example below removes the " synced" attribute:
Sessi onDescr i pt or desc = sessi on. get Sessi onDescr i pt or ( ) ;
desc. r emoveAt t r i but e( " synced" ) ;
Parameters:
at t r i but e - the attribute to remove
Throws:
I l l egal Ar gument Except i on - if the at t r i but e argument is nul l ,
if the at t r i but e does not exist in the Sessi on,
if the at t r i but e could not be removed

addAttribute
voi d addAttribute( St r i ng at t r i but e)
Adds an attribute to the Sessi on. Adding attributes that the IMS engine can set, such as "sendonly",
"recvonly", "sendrecv", will lead to an I l l egal Ar gument Except i on.
Example:
Sessi onDescr i pt or desc = sessi on. get Sessi onDescr i pt or ( ) ;
desc. addAt t r i but e( " synced" ) ;
The resulting attribute line will be:
a=synced
Parameters:
at t r i but e - the attribute to add
Throws:
I l l egal Ar gument Except i on - if the at t r i but e argument is nul l or if the syntax of the at t r i but e
argument is invalid,
if the at t r i but e already exists in the Sessi on,
if the at t r i but e could not be added

getAttributes
St r i ng[ ] getAttributes( )
Returns all attributes for the Sessi on. If there are no attributes, an empty string array will be returned.
Returns:
a string array containing the attributes
Interface SessionListener

publ i c i nt er f ace SessionListener
A listener type for receiving notification on session events. When an event is generated for a Sessi on the
application is notified by having one of the methods called on the Sessi onLi st ener .
See Also:
Sessi on. set Li st ener ( Sessi onLi st ener )

Method Summary
Page
voi d
sessionAlerting( Sessi on sessi on)
Notifies the application that the remote part's terminal is alerting the user of this session
invitation.
97
voi d
sessionReferenceReceived( Sessi on sessi on, Ref er ence r ef er ence)
Notifies the application that a reference request has been received from a remote endpoint.
98
voi d
sessionStarted( Sessi on sessi on)
Notifies the application that the session has been established.
97
voi d
sessionStartFailed( Sessi on sessi on)
Notifies the application that the session could not be established.
98
voi d
sessionTerminated( Sessi on sessi on)
Notifies the application that the session has been terminated or that the session could no
longer stay established.
96
voi d
sessionUpdated( Sessi on sessi on)
Notifies the application that the session has been updated.
97
voi d
sessionUpdateFailed( Sessi on sessi on)
Notifies the application that the session update has been rejected.
97
voi d
sessionUpdateReceived( Sessi on sessi on)
Notifies the application that the remote endpoint requests an update of the session settings.
97
Method Detail
sessionTerminated
voi d sessionTerminated( Sessi on sessi on)
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 Sessi on has transited to STATE_TERMI NATED.
Parameters:
sessi on - the concerned Sessi on

sessionUpdateReceived
voi d sessionUpdateReceived( Sessi on sessi on)
Notifies the application that the remote endpoint requests an update of the session settings.
The Sessi on has transited to STATE_RENEGOTI ATI NG.
Parameters:

sessionUpdated
voi d sessionUpdated( Sessi on sessi on)
Notifies the application that the session has been updated.
This callback is invoked at both involved endpoints.
The Sessi on has transited to STATE_ESTABLI SHED.
Parameters:

sessionUpdateFailed
voi d sessionUpdateFailed( Sessi on sessi on)
Notifies the application that the session update has been rejected.
Parameters:

sessionAlerting
voi d sessionAlerting( Sessi on sessi on)
Notifies the application that the remote part's terminal is alerting the user of this session invitation.
Parameters:

sessionStarted
voi d sessionStarted( Sessi on sessi on)
Notifies the application that the session has been established.
Parameters:

sessionStartFailed
voi d sessionStartFailed( Sessi on sessi on)
Notifies the application that the session could not be established.
The Sessi on has transited to STATE_TERMI NATED.
Parameters:

sessionReferenceReceived
voi d sessionReferenceReceived( Sessi on sessi on,
Ref er ence r ef er ence)
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:
r ef er ence - the Ref er ence representing the request
Interface Subscription
ServiceMethod

publ i c i nt er f ace Subscription
A Subscr i pt i on is used for subscribing to event states from a remote endpoint. The subscription will be refreshed
periodically until unsubscr i be is called.
The life cycle consist of three states, STATE_I NACTI VE, STATE_PENDI NG and STATE_ACTI VE.
A new Subscr i pt i on starts in STATE_I NACTI VE and when subscr i be is called the state transits to STATE_PENDI NG
and remains there until a response arrives from the remote endpoint.
In STATE_ACTI VE, unsubscr i be can be called to cancel the subscription and the state will then transit to
STATE_PENDI NG and remain there until a response arrives from the remote endpoint.
Client subscription example
To establish a subscription, a Subscr i pt i on has to be created. The event package to subscribe to must be set,
and the subscription is started by calling subscr i be. If the remote endpoint accepts the request, a response will
immediately be sent with the current event state that corresponds to the subscribed event package.
t r y {
sub = ser vi ce. cr eat eSubscr i pt i on( nul l , " si p: bob@home. net " , " pr esence" ) ;
sub. set Li st ener ( t hi s) ;
sub. subscr i be( ) ;
}

publ i c voi d subscr i pt i onSt ar t ed( Subscr i pt i on sub) {
/ / i f t he subscr i pt i on was successf ul l
}

publ i c voi d subscr i pt i onNot i f y( Subscr i pt i on sub, Message not i f y) {
/ / check t he subscr i bed event st at e
}
.
.
See Also:
Cor eSer vi ce. cr eat eSubscr i pt i on( St r i ng, St r i ng, St r i ng) , Publ i cat i on

Field Summary
Page
i nt
STATE_ACTIVE
The Subscr i pt i on is active.
100
i nt
STATE_INACTIVE
The Subscr i pt i on is not active.
100
i nt
STATE_PENDING
A Subscr i pt i on request is sent and the IMS engine is waiting for a response.
100

Method Summary
Page
St r i ng
getEvent( )
Returns the event package corresponding to this Subscr i pt i on.
101
i nt
getState( )
Returns the current state of the state machine of the Subscr i pt i on.
101
voi d
setListener( Subscr i pt i onLi st ener l i st ener )
Sets a listener for this Subscr i pt i on, replacing any previous Subscr i pt i onLi st ener .
101
voi d
subscribe( )
Sends a subscription request.
100
voi d
unsubscribe( )
Terminates this subscription.
101

Field Detail
STATE_INACTIVE
The Subscr i pt i on is not active.

STATE_PENDING
A Subscr i pt i on request is sent and the IMS engine is waiting for a response.

STATE_ACTIVE
The Subscr i pt i on is active.
Method Detail
subscribe
voi d subscribe( )
Sends a subscription request.
The Subscr i pt i on will transit to STATE_PENDI NG after calling this method.
Throws:
I l l egal St at eExcept i on - if the Subscr i pt i on is not in STATE_I NACTI VE

unsubscribe
voi d unsubscribe( )
Terminates this subscription.
The Subscr i pt i on will transit to STATE_PENDI NG after calling this method.
Throws:
I l l egal St at eExcept i on - if the Subscr i pt i on is not in STATE_ACTI VE

setListener
voi d setListener( Subscr i pt i onLi st ener l i st ener )
Sets a listener for this Subscr i pt i on, replacing any previous Subscr i pt i onLi st ener . A nul l reference is
Parameters:

getEvent
St r i ng getEvent( )
Returns the event package corresponding to this Subscr i pt i on.
Returns:
the event package

getState
i nt getState( )
Returns the current state of the state machine of the Subscr i pt i on.
Returns:
the current state
Interface SubscriptionListener

publ i c i nt er f ace SubscriptionListener
This listener type is used to notify the application about subscription status and the event state of the subscribed
event package.
See Also:
Subscr i pt i on. set Li st ener ( Subscr i pt i onLi st ener )

Method Summary
Page
voi d
subscriptionNotify( Subscr i pt i on subscr i pt i on, Message not i f y)
Notifies the application of published event state.
103
voi d
subscriptionStarted( Subscr i pt i on subscr i pt i on)
Notifies the application that the subscription was successfully started.
102
voi d
subscriptionStartFailed( Subscr i pt i on subscr i pt i on)
Notifies the application that the subscription was not successfully started.
102
voi d
subscriptionTerminated( Subscr i pt i on subscr i pt i on)
Notifies the application that a subscription was terminated.
102
Method Detail
subscriptionStarted
voi d subscriptionStarted( Subscr i pt i on subscr i pt i on)
Notifies the application that the subscription was successfully started.
The Subscr i pt i on has transited to STATE_ACTI VE.
Parameters:
subscr i pt i on - the concerned Subscr i pt i on

subscriptionStartFailed
voi d subscriptionStartFailed( Subscr i pt i on subscr i pt i on)
Notifies the application that the subscription was not successfully started.
The Subscr i pt i on has transited to STATE_I NACTI VE.
Parameters:

subscriptionTerminated
voi d subscriptionTerminated( Subscr i pt i on subscr i pt i on)
Notifies the application that a subscription was terminated.
The Subscr i pt i on has transited to STATE_I NACTI VE.
Parameters:

subscriptionNotify
voi d subscriptionNotify( Subscr i pt i on subscr i pt i on,
Message not i f y)
Notifies the application of published event state.
Parameters:
not i f y - 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
Interface Summary
Page
BasicReliableMedia
The Basi cRel i abl eMedi a represents a media connection with application
content transported over TCP, according to [RFC4145].
106
BasicReliableMediaListener
A listener type for receiving notification of when a connection error has
occurred on the stream(s).
109
BasicUnreliableMedia
The Basi cUnr el i abl eMedi a represents a media connection with
application content transported over UDP.
110
BasicUnreliableMediaListener
A listener type for receiving notification of when Basi cUnr el i abl eMedi a
content is available.
113
FramedMedia
The Fr amedMedi a represents a media connection on which content is
delivered in packets.
114
FramedMediaListener
A listener type for receiving notification of when Fr amedMedi a content is
transferred.
120
Media This object is used to represent the media in an IMS session. 123
MediaDescriptor
The different medias in IMS are described by the Session Description
Protocol (SDP).
130
StreamMedia
The St r eamMedi a represents a streaming media that can be rendered in
real-time.
134
Package javax.microedition.ims.core.media Description
The package contains entities used to create media flows for IMS.

Static Structure

Figure 1: Static structure of the package.
Interface BasicReliableMedia
javax.microedition.ims.core.media
Media

publ i c i nt er f ace BasicReliableMedia
ext ends Medi a
The Basi cRel i abl eMedi a represents a media connection with application content transported over TCP,
according to [RFC4145]. A connection is established when the media has been negotiated and accepted in the
session. The media is accessed as streams, one in each active direction.
Setting up the media
The following setter must be set in order to use the Medi a, otherwise an I msExcept i on will be thrown in
Sessi on. st ar t ( ) or Sessi on. updat e( ) .
setContentType
Sending application specific content

myMedi a = ( Basi cRel i abl eMedi a) mySessi on. cr eat eMedi a( " Basi cRel i abl eMedi a" ,
Medi a. DI RECTI ON_SEND) ;
myMedi a. set Cont ent Type( " appl i cat i on/ myChess" ) ;
. . .
Out put St r eamos = myMedi a. get Out put St r eam( ) ;
os. wr i t e( myGameDat a. get Byt es( ) ) ;
Receiving application specific content
The input stream is opened and the r ead method will return when there is content available on the connection.
myMedi a = ( Basi cRel i abl eMedi a) mySessi on. cr eat eMedi a( " Basi cRel i abl eMedi a" ,
Medi a. DI RECTI ON_RECEI VE) ;
. . .
I nput St r eami s = myMedi a. get I nput St r eam( ) ;
whi l e ( ( num= i s. r ead( buf ) ) ! = - 1)
{
/ / Consume t he r ead cont ent
}

Fields inherited from interface javax.microedition.ims.core.media.Media
DI RECTI ON_I NACTI VE, DI RECTI ON_RECEI VE, DI RECTI ON_SEND, DI RECTI ON_SEND_RECEI VE, STATE_ACTI VE,
STATE_DELETED, STATE_I NACTI VE, STATE_PENDI NG, STATE_PROPOSAL, UPDATE_MODI FI ED, UPDATE_REMOVED,
UPDATE_UNCHANGED

Method Summary
Page
St r i ng
getContentType( )
Returns the content type of this Medi a.
108
j ava. i o. I nput St r eam
getInputStream( )
Returns an I nput St r eamwhere incoming content can be read.
107
j ava. i o. Out put St r eam
getOutputStream( )
Returns an Out put St r eamwhere outgoing content can be written.
107
voi d
setContentType( St r i ng cont ent Type)
Sets the content type of this Medi a.
107
voi d
setListener( Basi cRel i abl eMedi aLi st ener l i st ener )
Sets a listener for this Basi cRel i abl eMedi a, replacing any previous
Basi cRel i abl eMedi aLi st ener .
108

Methods inherited from interface javax.microedition.ims.core.media.Media
get Di r ect i on, get Medi aDescr i pt or s, get Pr oposal , get St at e, get Updat eSt at e, set Di r ect i on
Method Detail
getInputStream
j ava. i o. I nput St r eamgetInputStream( )
Returns an I nput St r eamwhere incoming content can be read. It is only possible to invoke this method if
the media direction is setup to receive content.
Returns:
an I nput St r eamto read incoming content from
Throws:
j ava. i o. I OExcept i on - if an I/O error occurs
I l l egal St at eExcept i on - if the medias direction is DI RECTI ON_SEND or DI RECTI ON_I NACTI VE,
if the Medi a is not in STATE_ACTI VE

getOutputStream
j ava. i o. Out put St r eamgetOutputStream( )
Returns an Out put St r eamwhere outgoing content can be written. It is only possible to invoke this method
if the media direction is set up to send content.
Returns:
an Out put St r eamto write outgoing content to
Throws:
I l l egal St at eExcept i on - if the medias direction is DI RECTI ON_RECEI VE or
DI RECTI ON_I NACTI VE,

setContentType
voi d setContentType( St r i ng cont ent Type)
See Medi a for valid content types.
Parameters:
cont ent Type - the content type
Throws:
I l l egal St at eExcept i on - if the Medi a is not in STATE_I NACTI VE
I l l egal Ar gument Except i on - if the syntax of the cont ent Type argument is invalid
See Also:
get Cont ent Type( )

getContentType
Returns:
the content type or nul l if the content type has not been set
See Also:
set Cont ent Type( St r i ng)

setListener
voi d setListener( Basi cRel i abl eMedi aLi st ener l i st ener )
Sets a listener for this Basi cRel i abl eMedi a, replacing any previous Basi cRel i abl eMedi aLi st ener . A
nul l reference is allowed and has the effect of removing any existing listener.
Parameters:
Interface BasicReliableMediaListener
Interface BasicReliableMediaListener

publ i c i nt er f ace BasicReliableMediaListener
A listener type for receiving notification of when a connection error has occurred on the stream(s).
See Also:
Basi cRel i abl eMedi a

Method Summary
Page
voi d
connectionError( Basi cRel i abl eMedi a medi a)
Notifies the application if the connection could not be established.
109
Method Detail
connectionError
voi d connectionError( Basi cRel i abl eMedi a medi a)
Notifies the application if the connection could not be established.
Parameters:
medi a - the concerned Basi cRel i abl eMedi a
Interface BasicUnreliableMedia
Media

publ i c i nt er f ace BasicUnreliableMedia
ext ends Medi a
The Basi cUnr el i abl eMedi a represents a media connection with application content transported over UDP.
setContentType
Sending application specific content

myMedi a = ( Basi cUnr el i abl eMedi a) mySessi on. cr eat eMedi a( " Basi cUnr el i abl eMedi a" ,
myMedi a. set Li st ener ( t hi s) ;
. . .
byt e[ ] myChessMove = get ChessMove( ) ;
myMedi a. send( myChessMove) ;
Receiving application specific content
The content is received and the MIDlet is notified through the method cont ent Recei ved on the
Basi cUnr el i abl eMedi aLi st ener interface. The content can be retrieved by calling the r ecei ve method.
publ i c voi d cont ent Recei ved( Basi cUnr el i abl eMedi a medi a) {
t r y {
byt e[ ] hi sChessMove = medi a. r ecei ve( ) ;
} cat ch ( I msExcept i on e) {
. . .
}
}

UPDATE_UNCHANGED

Method Summary
Page
St r i ng
getContentType( )
112
byt e[ ]
receive( )
Receives content from the remote endpoint.
111
voi d
send( byt e[ ] cont ent )
Sends content to the remote endpoint.
111
voi d
setContentType( St r i ng cont ent Type)
111
voi d
setListener( Basi cUnr el i abl eMedi aLi st ener l i st ener )
Sets a listener for this Basi cUnr el i abl eMedi a, replacing any previous
Basi cUnr el i abl eMedi aLi st ener .
112

Method Detail
receive
byt e[ ] receive( )
t hr ows j ava. i o. I OExcept i on,
I msExcept i on
Receives content from the remote endpoint. The received content can only be retrieved once.
Returns:
a byte array with the received content
Throws:
I msExcept i on - if there is no content available for retrieval
I l l egal St at eExcept i on - if the medias direction is DI RECTI ON_SEND or DI RECTI ON_I NACTI VE,

send
voi d send( byt e[ ] cont ent )
Sends content to the remote endpoint.
Parameters:
Throws:
I l l egal Ar gument Except i on - if the cont ent argument is nul l
I l l egal St at eExcept i on - if the medias direction is DI RECTI ON_RECEI VE or
DI RECTI ON_I NACTI VE,

setContentType
voi d setContentType( St r i ng cont ent Type)
Parameters:
cont ent Type - the content type
Throws:
I l l egal Ar gument Except i on - if the syntax of the cont ent Type argument is invalid
See Also:
get Cont ent Type( )

getContentType
Returns:
the content type or nul l if the content type has not been set
See Also:
set Cont ent Type( St r i ng)

setListener
voi d setListener( Basi cUnr el i abl eMedi aLi st ener l i st ener )
Sets a listener for this Basi cUnr el i abl eMedi a, replacing any previous Basi cUnr el i abl eMedi aLi st ener .
A nul l reference is allowed and has the effect of removing any existing listener.
Parameters:
Interface BasicUnreliableMediaListener
Interface BasicUnreliableMediaListener

publ i c i nt er f ace BasicUnreliableMediaListener
A listener type for receiving notification of when Basi cUnr el i abl eMedi a content is available.
See Also:
Medi a

Method Summary
Page
voi d
contentReceived( Basi cUnr el i abl eMedi a medi a)
Notifies the application when new content is available.
113
Method Detail
contentReceived
voi d contentReceived( Basi cUnr el i abl eMedi a medi a)
Notifies the application when new content is available. The content can be retrieved by calling r ecei ve on
the Basi cUnr el i abl eMedi a.
Parameters:
medi a - the concerned Basi cUnr el i abl eMedi a
Interface FramedMedia
Media

publ i c i nt er f ace FramedMedia
ext ends Medi a
The Fr amedMedi a 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]. To facilitate the establishment of the media connection, [RFC4145]
should be supported. 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 Fr amedMedi a.
Fr amedMedi a uses the FileConnection API, [J SR75], to format the locator string in sendFi l e and r ecei veFi l e.
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:
f r amedMedi a. sendFi l e( " f i l e: / / / CFCar d/ i mages/ bob. png" , " i mage/ png" , header s) ;
Headers that can be set in sendFi l e, sendByt es and retrieved in get Header are defined in the BNF for
'Other-Mime-header' in [RFC4975].
Sending small instant messages

St r i ng[ ] accept edTypes = new St r i ng[ ] {" t ext / pl ai n" };
myMedi a = ( Fr amedMedi a) mySessi on. cr eat eMedi a( " Fr amedMedi a" ,
Medi a. DI RECTI ON_SEND_RECEI VE) ;
myMedi a. set Accept edCont ent Types( accept edTypes) ;
. . .
messageI d = myMedi a. sendByt es( " You move l i ke a queen, Al i ce : - ) " . get Byt es( ) ,
" t ext / pl ai n" , nul l ) ;
Sending images as files

St r i ng[ ] accept edTypes = new St r i ng[ ] {" i mage/ png" };
myMedi a = ( Fr amedMedi a) mySessi on. cr eat eMedi a( " Fr amedMedi a" ,
myMedi a. set Accept edCont ent Types( accept edTypes) ;
. . .
header s = new St r i ng[ ] [ ] {{" Cont ent - Descr i pt i on" ,
" a pi ct ur e of a pawn" }};
messageI d = myMedi a. sendFi l e( " f i l e: / / / CFCar d/ i mages/ pawn. png" ,
" i mage/ png" , header s) ;
Receiving images and instant messages
The application is notified through the callback cont ent Recei ved on the Fr amedMedi aLi st ener 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 messageI d will not be possible. Content can be retrieved with the r ecei veByt es or
r ecei veFi l e method, regardless on how it was sent.

publ i c voi d cont ent Recei ved( Fr amedMedi a medi a,
St r i ng messageI d,
i nt si ze,
St r i ng f i l eName) {

St r i ng cont ent Type = medi a. get Cont ent Type( messageI d) ;

i f ( cont ent Type. equal s( " t ext / pl ai n" ) ) {
byt e[ ] cont ent = medi a. r ecei veByt es( messageI d) ;
. . .
/ / do somet hi ng wi t h cont ent
} el se i f ( cont ent Type. equal s( " i mage/ png" ) ) {
t r y {
medi a. r ecei veFi l e( messageI d, " <PATH>" + f i l eName) ;
} cat ch ( I OExcept i on e) {
. . .
}
}

}

UPDATE_UNCHANGED

Method Summary
Page
voi d
cancel( St r i ng messageI d)
Cancels the ongoing transfer.
118
St r i ng[ ]
getAcceptedContentTypes( )
Returns the accepted content type(s) of this media.
117
St r i ng
getContentType( St r i ng messageI d)
Returns the content type of the content that is identified by the messageI d parameter.
116
St r i ng
getHeader( St r i ng messageI d, St r i ng key)
Returns the header value from the content that is identified by the messageI d parameter.
117
byt e[ ]
receiveBytes( St r i ng messageI d)
118
voi d
receiveFile( St r i ng messageI d, St r i ng l ocat or )
Receives a file from the remote endpoint.
118
St r i ng
sendBytes( byt e[ ] cont ent , St r i ng cont ent Type, St r i ng[ ] [ ] header s)
Sends the content to the remote endpoint over a reliable connection.
116
St r i ng
sendFile( St r i ng l ocat or , St r i ng cont ent Type, St r i ng[ ] [ ] header s)
Sends a file to the remote endpoint over a reliable connection.
116
voi d
setAcceptedContentTypes( St r i ng[ ] accept edCont ent Types)
Sets the accepted content type(s) of this media.
117
voi d
setListener( Fr amedMedi aLi st ener l i st ener )
Sets a listener for this Fr amedMedi a, replacing any previous Fr amedMedi aLi st ener .
118

Method Detail
sendBytes
St r i ng sendBytes( byt e[ ] cont ent ,
St r i ng cont ent Type,
St r i ng[ ] [ ] header s)
Sends the content to the remote endpoint over a reliable connection. This method is asynchronous.
Parameters:
header s - an array of arrays, specifying key and value, nul l can be used to indicate that no extra
headers are desired
Returns:
an identifier for the content sent
Throws:
I l l egal St at eExcept i on - if the media direction is DI RECTI ON_RECEI VE or DI RECTI ON_I NACTI VE,
I l l egal Ar gument Except i on - if the cont ent argument is nul l ,
if the syntax of the cont ent Type or header s argument is invalid,
if the cont ent Type is not part of the accepted content types

sendFile
St r i ng sendFile( St r i ng l ocat or ,
St r i ng cont ent Type,
St r i ng[ ] [ ] header s)
Sends a file to the remote endpoint over a reliable connection. This method is asynchronous.
Parameters:
l ocat or - the location of the file to send
header s - an array of arrays, specifying key and value, nul l can be used to indicate that no extra
headers are desired
Returns:
an identifier for the content sent
Throws:
j ava. i o. I OExcept i on - if an I/O error occurs when operating with the file or that the file could not
be opened
I l l egal St at eExcept i on - if the media direction is DI RECTI ON_RECEI VE or DI RECTI ON_I NACTI VE,
I l l egal Ar gument Except i on - if the syntax of the cont ent Type or header s argument is invalid,
if the cont ent Type is not part of the accepted content types
Secur i t yExcept i on - if sending a file is not permitted

getContentType
St r i ng getContentType( St r i ng messageI d)
Returns the content type of the content that is identified by the messageI d parameter.
Parameters:
messageI d - an identifier for the content
Returns:
the content type
Throws:
I l l egal Ar gument Except i on - if the messageI d is not found

setAcceptedContentTypes
voi d setAcceptedContentTypes( St r i ng[ ] accept edCont ent Types)
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:
accept edCont ent Types - an array of content types accepted in this media
Throws:
I l l egal Ar gument Except i on - if the syntax of the accept edCont ent Types argument is invalid
See Also:
get Accept edCont ent Types( )

getAcceptedContentTypes
St r i ng[ ] 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:
set Accept edCont ent Types( St r i ng[ ] )

getHeader
St r i ng getHeader( St r i ng messageI d,
St r i ng key)
Returns the header value from the content that is identified by the messageI d parameter.
Parameters:
messageI d - an identifier for the content
key - the header name
Returns:
a string containing the header value or nul l if the header does not exist
Throws:
I l l egal Ar gument Except i on - if the messageI d is not found,
if the key is nul l

receiveBytes
byt e[ ] receiveBytes( St r i ng messageI d)
Parameters:
messageI d - identifies which content to receive
Returns:
a byte array containing the received content
Throws:
I l l egal Ar gument Except i on - if the messageI d is not found or if there is no completely
downloaded content corresponding to the messageI d

receiveFile
voi d receiveFile( St r i ng messageI d,
St r i ng l ocat or )
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:
messageI d - identifies which file to receive
l ocat or - sets the location where the file will be stored
Throws:
j ava. i o. I OExcept i on - if an I/O error occurs when operating with the file or the file could not be
opened
I l l egal Ar gument Except i on - if the messageI d is not found or if there is no completely
downloaded content corresponding to the messageI d
Secur i t yExcept i on - if receiving a file is not permitted

cancel
voi d cancel( St r i ng messageI d)
Cancels the ongoing transfer. This method can be called for outgoing and incoming content. If no matching
messageI d is found or if the content is already transferred, this method will not do anything.
Parameters:
messageI d - the identifier corresponding to the content to be cancelled

setListener
voi d setListener( Fr amedMedi aLi st ener l i st ener )
Sets a listener for this Fr amedMedi a, replacing any previous Fr amedMedi aLi st ener . A nul l reference is
Parameters:
Interface FramedMediaListener

publ i c i nt er f ace FramedMediaListener
A listener type for receiving notification of when Fr amedMedi a content is transferred. When content becomes
available the application is notified by a call to the cont ent Recei ved method. The application can then retrieve the
content by either using the r ecei veByt es or r ecei veFi l e method on the Fr amedMedi a interface.
See Also:
Fr amedMedi a

Method Summary
Page
voi d
connectionError( Fr amedMedi a medi a)
Notifies the application when an I/O error has occurred.
122
voi d
contentReceived( Fr amedMedi a medi a, St r i ng messageI d, i nt si ze, St r i ng f i l eName)
Notifies the application when the content is completely received.
120
voi d
contentReceiveFailed( Fr amedMedi a medi a, St r i ng messageI d)
Notifies the application that the content could not be received or that the content has been
canceled by the sending endpoint.
121
voi d
deliveryFailure( Fr amedMedi a medi a, St r i ng messageI d, i nt st at usCode, St r i ng
r easonPhr ase)
Notifies the application when the content corresponding to the messageI d has not been
successfully delivered to the remote endpoint.
121
voi d
deliverySuccess( Fr amedMedi a medi a, St r i ng messageI d)
Notifies the application when the content corresponding to the messageI d has been
successfully delivered to the remote endpoint.
121
voi d
transferProgress( Fr amedMedi a medi a, St r i ng messageI d, i nt byt esTr ansf er r ed, i nt
byt esTot al )
Notifies the application when there is progress to be reported.
121
Method Detail
contentReceived
voi d contentReceived( Fr amedMedi a medi a,
i nt si ze,
St r i ng f i l eName)
Notifies the application when the content is completely received. The content can now be retrieved by
calling r ecei veByt es or r ecei veFi l e with the corresponding messageI d on the Fr amedMedi a object.
Parameters:
medi a - the Fr amedMedi a that received the content
messageI d - identifies the content that is ready for retrieval
si ze - the size of the content in bytes
f i l eName - the file name or nul l if a file name is not associated with the messageI d

contentReceiveFailed
voi d contentReceiveFailed( Fr amedMedi a medi a,
St r i ng messageI d)
Notifies the application that the content could not be received or that the content has been canceled by the
sending endpoint. The messageI d is considered invalid after this callback and further use of this messageI d
is not possible.
Parameters:
medi a - the Fr amedMedi a that could not receive the content
messageI d - identifies the content that could not be received

transferProgress
voi d transferProgress( Fr amedMedi a medi a,
i nt byt esTr ansf er r ed,
i nt byt esTot al )
Notifies the application when there is progress to be reported. This will be invoked for both outgoing and
incoming content.
Parameters:
medi a - the Fr amedMedi a that received/sent the content
messageI d - identifies the content that is being transferred
byt esTr ansf er r ed - the number of bytes that is transferred
byt esTot al - the number of total bytes in the content, this parameter is -1 if the size is not known

deliverySuccess
voi d deliverySuccess( Fr amedMedi a medi a,
St r i ng messageI d)
Notifies the application when the content corresponding to the messageI d has been successfully delivered
to the remote endpoint. The messageI d is considered invalid after this callback and further use of this
messageI d is not possible.
This method is invoked at the endpoint that sent the content.
Parameters:
medi a - the Fr amedMedi a that sent the content
messageI d - identifies the content that has been transferred

deliveryFailure
voi d deliveryFailure( Fr amedMedi a medi a,
i nt st at usCode,
St r i ng r easonPhr ase)
Notifies the application when the content corresponding to the messageI d has not been successfully
delivered to the remote endpoint. The messageI d is considered invalid after this callback and further use of
this messageI d is not possible.
This method is invoked at the endpoint that sent the content.
See [RFC4975] for valid status codes.
Parameters:
medi a - the Fr amedMedi a that sent the content
messageI d - identifies the content that could not be transferred
st at usCode - the status code why the transaction failed
r easonPhr ase - the reason phrase

connectionError
voi d connectionError( Fr amedMedi a medi a)
Notifies the application when an I/O error has occurred.
Parameters:
medi a - the concerned Fr amedMedi a
Interface Media
Interface Media
BasicReliableMedia, BasicUnreliableMedia, FramedMedia, StreamMedia

publ i c i nt er f ace Media
This object is used to represent the media in an IMS session. A media can be seen as a pipe between the two
endpoints where content can flow in either direction or both.
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 Pl ayer that supports an
appropriate common codec to do the rendering.
Medi a are subclassed based on the transport method used.
Content Types
Content types identifies the content type of a Medi a. 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 Medi a is independent of other Medi as life cycles and has four main states: STATE_I NACTI VE,
STATE_PENDI NG, STATE_ACTI VE 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 Medi a.
The media life cycle is connected to the life cycle of the Sessi on. A transition in a Medi a 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.
Interface Media

Figure 1: The media states, except STATE_PROPOSAL

Update state
The update state is used to track changes that have been done to an active Medi a on either the originating or
terminating endpoint. If a Medi a has been accepted in a session the update state will be UPDATE_UNCHANGED.
If a Medi a is proposed to be removed or modified the get Updat eSt at e reflect the changes but the modifications
does not take place before the Sessi on has been negotiated and accepted. The modifications can however be
traced by inspecting the proposed Medi a, that can be obtained with the get Pr oposal method, until the Sessi on is
updated.
After a session update the application SHOULD call get Medi a on the Sessi on and take actions if needed.
Examples of the Media states and update states
This example shows which state and update state the Medi a 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.
publ i c voi d sessi onI nvi t at i onRecei ved( Cor eSer vi ce ser vi ce, Sessi on sessi on) {
/ / al l medi as ar e pendi ng i n a sessi on i nvi t e
medi a. get St at e( ) == STATE_PENDI NG;
/ / get Updat eSt at e i s not appl i cabl e i n t hi s st at e
}
. . .
publ i c voi d sessi onUpdat eRecei ved( Sessi on sessi on) {
/ / t hi s wi l l show t hat t he medi a i s pr oposed t o be added t o t he sessi on
medi a. get St at e( ) == STATE_PENDI NG;
/ / get Updat eSt at e i s not appl i cabl e i n t hi s st at e
. . .
/ / t hi s wi l l show t hat t he medi a i s pr oposed t o be r emoved f r omt he sessi on
medi a. get St at e( ) == STATE_ACTI VE;
medi a. get Updat eSt at e( ) == UPDATE_REMOVED;
. . .
/ / t hi s wi l l show t hat t he medi a i s pr oposed t o be modi f i ed i n a sessi on
Interface Media
medi a. get Updat eSt at e( ) == UPDATE_MODI FI ED;
medi a. get Pr oposal ( ) ; / / r et ur ns a f i ct i ous medi a t o t r ack changes
. . .
/ / t hi s wi l l show a medi a t hat i s unchanged i n t he sessi on updat e
medi a. get Updat eSt at e( ) == UPDATE_UNCHANGED;
}
This example shows how an application can inspect changes done to a media in a session update.
publ i c voi d sessi onUpdat eRecei ved( Sessi on sessi on) {
/ / i f t he f i r st medi a i n t he ar r ay i s a medi a i n STATE_ACTI VE and
/ / updat e st at e i s UPDATE_MODI FI ED

Medi a cur r ent Medi a = sessi on. get Medi a( ) [ 0] ;
Medi a changedMedi a = cur r ent Medi a. get Pr oposal ( ) ;

/ / t hen t he appl i cat i on can t r ack changes, f or exampl e
i f ( cur r ent Medi a. get Di r ect i on( ) ! = changedMedi a. get Di r ect i on( ) ) {
. . .
}
/ / and now t he appl i cat i on can deci de i f t he updat e shoul d be accept ed or
/ / r ej ect ed
sessi on. accept ( ) ;
}

Field Summary
Page
i nt
DIRECTION_INACTIVE
This mode specifies that the Medi a can not receive or send content.
126
i nt
DIRECTION_RECEIVE
This mode specifies that the Medi a can receive content.
126
i nt
DIRECTION_SEND
This mode specifies that the Medi a can send content.
126
i nt
DIRECTION_SEND_RECEIVE
This mode specifies that the Medi a is bi-directional and can both send and receive
content.
126
i nt
STATE_ACTIVE
The Medi a exists in a session and the media offer has been accepted by both parties.
127
i nt
STATE_DELETED
The Medi a has been part of an existing session but is now removed, or the Medi a has
been rejected or deleted by the IMS engine.
127
i nt
STATE_INACTIVE
The Medi a is created and added to a session.
127
i nt
STATE_PENDING
The Medi a exists in a session and a media offer has been sent to the remote endpoint.
127
i nt
STATE_PROPOSAL
The Medi a is a fictitious media and is only meant to be inspected to track changes during
a session update.
127
i nt
UPDATE_MODIFIED
This sub-state specifies that this Medi a is proposed to be modified and must be negotiated
before the modifications can be deployed.
128
i nt
UPDATE_REMOVED
This sub-state specifies that this Medi a is proposed to be removed from the session and
must be negotiated before removal can be made.
128
Interface Media
i nt
UPDATE_UNCHANGED
This sub-state specifies that this Medi a is unchanged since session establishment or the
last session update.
127

Method Summary
Page
i nt
getDirection( )
Returns the current direction of this Medi a.
128
Medi aDescr i pt or [ ]
getMediaDescriptors( )
Returns the media descriptor(s) associated with this Medi a.
128
Medi a
getProposal( )
Returns a fictitious media that is only meant to track changes that are about to be
made to the media.
129
i nt
getState( )
Returns the current state of this Medi a.
129
i nt
getUpdateState( )
Returns the current update state of this Medi a.
129
voi d
setDirection( i nt di r ect i on)
Sets the direction of this Medi a.
128
Field Detail
DIRECTION_INACTIVE
publ i c st at i c f i nal i nt DIRECTION_INACTIVE
This mode specifies that the Medi a can not receive or send content.

DIRECTION_RECEIVE
publ i c st at i c f i nal i nt DIRECTION_RECEIVE
This mode specifies that the Medi a can receive content.

DIRECTION_SEND
publ i c st at i c f i nal i nt DIRECTION_SEND
This mode specifies that the Medi a can send content.

DIRECTION_SEND_RECEIVE
publ i c st at i c f i nal i nt DIRECTION_SEND_RECEIVE
This mode specifies that the Medi a is bi-directional and can both send and receive content.

Interface Media
STATE_INACTIVE
The Medi a is created and added to a session.
The Medi a is not active and there can currently be no content transfer within this Medi a.

STATE_PENDING
The Medi a exists in a session and a media offer has been sent to the remote endpoint. A new Medi a that is
added in an incoming invite/update also resides in this state.

STATE_ACTIVE
The Medi a exists in a session and the media offer has been accepted by both parties.
The Medi a is active and content can be transferred within this Medi a.

STATE_DELETED
publ i c st at i c f i nal i nt STATE_DELETED
The Medi a has been part of an existing session but is now removed, or the Medi a has been rejected or
deleted by the IMS engine.

STATE_PROPOSAL
publ i c st at i c f i nal i nt STATE_PROPOSAL
The Medi a is a fictitious media and is only meant to be inspected to track changes during a session update.
After the session update this Medi a should be considered discarded.

UPDATE_UNCHANGED
publ i c st at i c f i nal i nt UPDATE_UNCHANGED
This sub-state specifies that this Medi a is unchanged since session establishment or the last session
update.

Interface Media
UPDATE_MODIFIED
publ i c st at i c f i nal i nt UPDATE_MODIFIED
This sub-state specifies that this Medi a is proposed to be modified and must be negotiated before the
modifications can be deployed.
The modifications can be traced by inspecting the proposed Medi a by calling get Pr oposal .

UPDATE_REMOVED
publ i c st at i c f i nal i nt UPDATE_REMOVED
This sub-state specifies that this Medi a is proposed to be removed from the session and must be
negotiated before removal can be made.
Method Detail
getMediaDescriptors
Medi aDescr i pt or [ ] getMediaDescriptors( )
Returns the media descriptor(s) associated with this Medi a.
Returns:
the media descriptor(s)

getDirection
i nt getDirection( )
Returns the current direction of this Medi a.
Returns:
the current direction of this Medi a
See Also:
set Di r ect i on( i nt )

setDirection
voi d setDirection( i nt di r ect i on)
Sets the direction of this Medi a.
If a Medi a is changed in an established Sessi on, the application has the responsibility to call updat e on the
Sessi on.
Note: If the Medi a is in STATE_ACTI VE the direction will be set on the proposal media until the Sessi on has
been updated. The proposal media can be retrieved with the get Pr oposal method on the Medi a interface.
Parameters:
di r ect i on - the direction of the Medi a
Interface Media
Throws:
I l l egal St at eExcept i on - if the Medi a is not in STATE_I NACTI VE or STATE_ACTI VE
I l l egal Ar gument Except i on - if the di r ect i on argument is invalid
See Also:
get Di r ect i on( )

getState
i nt getState( )
Returns the current state of this Medi a.
Returns:
the current state

getUpdateState
i nt getUpdateState( )
Returns the current update state of this Medi a.
Returns:
the current update state
Throws:
I l l egal St at eExcept i on - if the Medi a is not in STATE_ACTI VE

getProposal
Medi a getProposal( )
Returns a fictitious media that is only meant to track changes that are about to be made to the media.
After the Sessi on has been accepted or rejected this proposed media should be considered discarded.
Returns:
a media proposal
Throws:
I l l egal St at eExcept i on - if the Medi a is not in STATE_ACTI VE,
if the update state is not in UPDATE_MODI FI ED
Interface MediaDescriptor

publ i c i nt er f ace MediaDescriptor
The different medias in IMS are described by the Session Description Protocol (SDP). SDP provides information of
the media such as codecs, bitrates and transport addresses.
The media descriptor, for each media that is offered, starts with an "m=" field followed by the actual media
description. This field describes the media type, the transport ports, transport protocol and a media format
description.
Each media descriptor can be followed by one or many attributes. An attribute starts with an "a=" field. Since MIDlet
writers can add additional attributes as they are required, the number of available attributes will continuously
increase. This interface gives access to review and to add new attributes to the SDP. See [RFC4566] for more
detailed information about the SDP.
An SDP offer for a session with one audio media and one video media could look like this (the example shows an
SDP with two media descriptors, one marked in bold text):
v=0
o=al i ce 2890844526 2890844526 I N I P4 host . at l ant a. exampl e. com
s=
c=I N I P4 host . at l ant a. exampl e. 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=vi deo 51372 RTP/ AVP 31 32
a=r t pmap: 31 H261/ 90000
a=r t pmap: 32 MPV/ 90000
Note: If the media description is changed so that the Sessi on needs to be renegotiated, the application has the
responsibility to call updat e on the Sessi on.
See Also:
Sessi onDescr i pt or

Method Summary
Page
voi d
addAttribute( St r i ng at t r i but e)
Adds an attribute to the Medi a.
132
St r i ng[ ]
getAttributes( )
Returns all attributes for the Medi a.
133
St r i ng[ ]
getBandwidthInfo( )
Returns the proposed bandwidth to be used by the media.
131
St r i ng
getMediaDescription( )
Returns the contents of the media description field in SDP for this media.
133
St r i ng
getMediaTitle( )
Returns the title of the Medi a.
131
voi d
removeAttribute( St r i ng at t r i but e)
Removes an attribute from the Medi a.
132
voi d
setBandwidthInfo( St r i ng[ ] i nf o)
Sets the proposed bandwidth to be used by the media.
131
voi d
setMediaTitle( St r i ng t i t l e)
Sets a title to the Medi a.
131
Method Detail
setMediaTitle
voi d setMediaTitle( St r i ng t i t l e)
Sets a title to the Medi a.
Parameters:
t i t l e - the Medi a title to set
Throws:
I l l egal Ar gument Except i on - if the t i t l e argument is nul l
See Also:
get Medi aTi t l e( )

getMediaTitle
St r i ng getMediaTitle( )
Returns the title of the Medi a.
Returns:
the Medi a title or nul l if the title has not been set
See Also:
set Medi aTi t l e( St r i ng)

setBandwidthInfo
voi d setBandwidthInfo( St r i ng[ ] i nf o)
Sets the proposed bandwidth to be used by the media. All previous bandwidth info will be removed from
the media.
Example:
Medi aDescr i pt or desc;
desc. set Bandwi dt hI nf o( new St r i ng[ ] { " AS: 128" }) ;
Parameters:
i nf o - the bandwidth info to set
Throws:
I l l egal Ar gument Except i on - if the i nf o argument is nul l or if the syntax is invalid
See Also:
get Bandwi dt hI nf o( )

getBandwidthInfo
St r i ng[ ] getBandwidthInfo( )
Returns the proposed bandwidth 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:
set Bandwi dt hI nf o( St r i ng[ ] )

removeAttribute
voi d removeAttribute( St r i ng at t r i but e)
Removes an attribute from the Medi a.
The example below removes the " max- si ze: 2048000" attribute for a Fr amedMedi a.
Medi aDescr i pt or [ ] desc = f r amedMedi a. get Medi aDescr i pt or s( ) ;
desc[ 0] . r emoveAt t r i but e( " max- si ze: 2048000" ) ;
Note: If the Medi a is in STATE_ACTI VE the attribute will be removed on the proposal media until the
Sessi on has been updated. The proposal media can be retrieved with the get Pr oposal method on the
Medi a interface.
Parameters:
at t r i but e - the attribute to remove
Throws:
I l l egal Ar gument Except i on - if the at t r i but e argument is nul l ,
if the at t r i but e does not exist in the Medi a,
if the at t r i but e could not be removed

addAttribute
voi d addAttribute( St r i ng at t r i but e)
Adds an attribute to the Medi a. Adding attributes that the IMS engine can set, such as "sendonly",
"recvonly", "sendrecv", will lead to an I l l egal Ar gument Except i on.
The example below adds two attributes for a Fr amedMedi a.
Medi aDescr i pt or [ ] desc = f r amedMedi a. get Medi aDescr i pt or s( ) ;
desc[ 0] . addAt t r i but e( " max- si ze: 2048000" ) ;
desc[ 0] . addAt t r i but e( " synced" ) ;
The resulting attribute lines will be:
a=max- si ze: 2048000
a=synced
Note: If the Medi a is in STATE_ACTI VE the attribute will be set on the proposal media until the Sessi on has
been updated. The proposal media can be retrieved with the get Pr oposal method on the Medi a interface.
Parameters:
at t r i but e - the attribute to add
Throws:
I l l egal Ar gument Except i on - if the at t r i but e argument is nul l or if the syntax of the at t r i but e
argument is invalid,
if the at t r i but e already exist in the Medi a,
if the at t r i but e could not be added

getAttributes
St r i ng[ ] getAttributes( )
Returns all attributes for the Medi a. If there are no attributes, an empty string array will be returned.
Returns:
a string array containing the attributes

getMediaDescription
St r i ng getMediaDescription( )
t hr ows I l l egal St at eExcept i on
Returns the contents of the media description field in SDP for this media. Example of SDP mediadescriptor:
audi o 4000 RTP/ AVP 97 101
Returns:
the media description
Throws:
I l l egal St at eExcept i on - if the Medi a is in STATE_I NACTI VE
Interface StreamMedia
Media

publ i c i nt er f ace StreamMedia
ext ends Medi a
The St r eamMedi a represents a streaming media that can be rendered in real-time. The streaming type can be
sourced from a capturing device or from a file and can be audio, video or both.
setSource
Playback Example
Set up a bidirectional audio media
t r y {
myMedi a = ( St r eamMedi a) mySessi on. cr eat eMedi a( " St r eamMedi a" ,
myMedi a. set St r eamType( STREAM_TYPE_AUDI O) ;
myMedi a. set Sour ce( " capt ur e: / / audi o" ) ;
} cat ch ( I msExcept i on i e) { }
Wait until the session is established. The rendering player can be retrieved in, for example, the sessi onSt ar t ed
callback.

t r y {
Pl ayer pI n = myMedi a. get Recei vi ngPl ayer ( ) ;
Pl ayer pOut = myMedi a. get Sendi ngPl ayer ( ) ;
pI n. st ar t ( ) ;
pOut . st ar t ( ) ;
} cat ch ( Medi aExcept i on me) { }

Stream from a multiplexed file
t r y {
myMedi a = ( St r eamMedi a) mySessi on. cr eat eMedi a( " St r eamMedi a" ,
myMedi a. set St r eamType( STREAM_TYPE_AUDI O_VI DEO) ;
myMedi a. set Sour ce( " f i l e: / / / r oot / sampl e. mpg" ) ;
} cat ch ( I msExcept i on i e) { }
As before, the player is retrieved in the sessi onSt ar t ed callback.

t r y {
Pl ayer pOut = myMedi a. get Sendi ngPl ayer ( ) ;
pOut . st ar t ( ) ;
} cat ch ( Medi aExcept i on me) { }

Field Summary
Page
i nt
QUALITY_HIGH
Enables the platform to choose a higher quality codec during the negotiation of the media.
136
i nt
QUALITY_LOW
Enables the platform to choose a lower quality codec during the negotiation of the media.
135
i nt
QUALITY_MEDIUM
Enables the platform to choose a medium quality codec during the negotiation of the
media.
135
i nt
STREAM_TYPE_AUDIO
Indicates that the streaming will consist only of audio.
136
i nt
STREAM_TYPE_AUDIO_VIDEO
Indicates that the streaming will consist of audio and video.
136
i nt
STREAM_TYPE_VIDEO
Indicates that the streaming will consist only of video.
136

UPDATE_UNCHANGED

Method Summary
Page
j avax. mi cr oedi t i on. medi a. Pl ayer
getReceivingPlayer( )
Returns a Pl ayer initiated to render the receiving part of this Medi a.
137
j avax. mi cr oedi t i on. medi a. Pl ayer
getSendingPlayer( )
Returns a Pl ayer initiated to source the sending part of this Medi a.
137
i nt
getStreamType( )
Returns the stream type for the Medi a.
137
voi d
setPreferredQuality( i nt qual i t y)
Sets a preferred quality of the media stream.
138
voi d
setSource( St r i ng sour ce)
Sets the source to capture media from.
136
voi d
setStreamType( i nt t ype)
Sets the stream type for the Medi a.
137

Field Detail
QUALITY_LOW
publ i c st at i c f i nal i nt QUALITY_LOW
Enables the platform to choose a lower quality codec during the negotiation of the media.

QUALITY_MEDIUM
publ i c st at i c f i nal i nt QUALITY_MEDIUM
Enables the platform to choose a medium quality codec during the negotiation of the media.

QUALITY_HIGH
publ i c st at i c f i nal i nt QUALITY_HIGH
Enables the platform to choose a higher quality codec during the negotiation of the media.

STREAM_TYPE_AUDIO
publ i c st at i c f i nal i nt STREAM_TYPE_AUDIO
Indicates that the streaming will consist only of audio.

STREAM_TYPE_VIDEO
publ i c st at i c f i nal i nt STREAM_TYPE_VIDEO
Indicates that the streaming will consist only of video.

STREAM_TYPE_AUDIO_VIDEO
publ i c st at i c f i nal i nt STREAM_TYPE_AUDIO_VIDEO
Indicates that the streaming will consist of audio and video.
Method Detail
setSource
voi d setSource( St r i ng sour ce)
Sets the source to capture media from.
Supported sources:
capt ur e: / / <devi ce>
f i l e: / / <pat h>
device ="audio" / "video" / "audio_video" / dev_name
dev_name =alphanumeric
alphanumeric =1*( ALPHA / DIGIT )

See [J SR135] for more information on how to define the capture locator.
See [J SR75] for more information on how to define the file locator.
Parameters:
sour ce - the source locator URI of media to be streamed
Throws:
I l l egal Ar gument Except i on - if the syntax of the sour ce argument is invalid or not supported

setStreamType
voi d setStreamType( i nt t ype)
Sets the stream type for the Medi a. 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_AUDI O.
Note: The use case for this method is when the application adds a St r eamMedi a to a session with direction
set to DI RECTI ON_RECEI VE. In this case, the IMS engine does not know which kind of St r eamMedi a to use
in the negotiation. If the set Sour ce method conflicts with the stream type, the set Sour ce method has
priority.
Parameters:
t ype - the stream type
Throws:
I l l egal Ar gument Except i on - if the t ype argument is not a valid identifier or not supported
See Also:
get St r eamType( )

getStreamType
i nt getStreamType( )
Returns the stream type for the Medi a.
If the stream type has not been set, it will default to STREAM_TYPE_AUDI O.
Returns:
the stream type
See Also:
set St r eamType( i nt )

getReceivingPlayer
j avax. mi cr oedi t i on. medi a. Pl ayer getReceivingPlayer( )
Returns a Pl ayer initiated to render the receiving part of this Medi a. The returned Pl ayer is in the
REALI ZED state.
Returns:
a Pl ayer
Throws:
I l l egal St at eExcept i on - if the media's direction is DI RECTI ON_SEND or DI RECTI ON_I NACTI VE,

getSendingPlayer
j avax. mi cr oedi t i on. medi a. Pl ayer getSendingPlayer( )
Returns a Pl ayer initiated to source the sending part of this Medi a. The returned Pl ayer is in the
REALI ZED state.
Returns:
a Pl ayer
Throws:
I l l egal St at eExcept i on - if the media's direction is DI RECTI ON_RECEI VE or DI RECTI ON_I NACTI VE,

setPreferredQuality
voi d setPreferredQuality( i nt qual i t y)
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 QUALI TY_MEDI UM.
Parameters:
qual i t y - the preferred quality
Throws:
I l l egal Ar gument Except i on - if the qual i t y argument is invalid
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 J SR 281. For any given general IMS application, language and
platform independent, the API divides the set of requirements in two:
Application-specific: The J ava J SR 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 Ser vi ceMet hod) 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 Medi a) are related to media streams and the media oriented SDP lines. The
St r eamMedi a type is based on the RTP/AVP-profile, and the media content is handled in the IMS engine. The
Fr amed media type is based on MSRP, where the IMS engine handles the MSRP protocol, and the application
handles the content. For Basi cUnr el i abl eMedi a and Basi cRel i abl eMedi a, the application implements a protocol
on top of UDP and TCP, respectively.
Appendix A
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 Connect or . open( ) ,
There is a MIDP Push registration with a proper i mscor e locator as connector string (or some other
equivalent mechanism according to the J ava 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.
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 Connect or . 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.
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.app_ref =iari
For each icsi in p do
F +=+g.3gpp.app_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
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 J SR 281, where the +g. 3gpp. app- r ef tag has
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 <=T is defined as such:
If the feature T is already part of some member in Fs, then Fs is unchanged.
Search for a header h in Fs that is free from T.tag and has the same explicit and require flags, then add T
to h.
If the search was not successful, then create a new header h with T and add that to Fs. Mark with the
explicit and require flags associated with T.
Main algorithm:
For the Registry R
For each IMS property p in R:
If p is StreamMedia property then
If p has both Audio and Video, then Fs <=video and F <=audio
Else if Video is in p, then Fs <=video
Else If Audio is in p, then Fs <=audio
Else should not happen
Else if p is FramedMedia then
Fs <=message
Else if p is BasicMedia then
For each content type xxx/yyy in p
If xxx is application then
Fs <=application
Fs <=app_subtype =yyy (this step is optional)
Else if xxx is video then Fs <=video
Else if xxx is audio then Fs <=audio
Else if p is Event then
For each event e in p
Fs <=events=e
Else if p is a CoreService with the name cs then
For each iari in p do
Fs <=+g.3gpp.app_ref =iari;require
For each icsi in p do
Fs <=+g.3gpp.app_ref =icsi with explicit and require flags as indicated.
For each FT in p do
Fs <=FT with explicit and require flags as indicated.
Else p is some other property, and no action
Example
The myChess example IMS application used in this specification, has a Registry with the following contents
(represented in the string notation suitable for use in the Conf i gur at i on. set Regi st r y( ) call):

{ " Event " , " Pr esence" },
Appendix A
};

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.app_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
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 Cor eSer vi ce 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.
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.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++
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)

Appendix A
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 Request-Disposition is processed according to local device policy. The header is normally targeted to network
servers. Since the IMS engine behaves in some respects as a proxy for the active core services, it may take action
on the fork and parallel directives. If applied, the IMS engine can fork the request to all target cs at once, or try
them out sequentially in the scoring order, until it reaches one that accepts the request.

ConnectionState
When the initial registration has been done, the Public User Identities (SIP URI user identities) returned via the
get User I dent i t i es( ) method are taken from the P-Associated-URI header and/or via the registration event
package, according to the IMS standard. The first URI in the list is the default network chosen 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 Ser vi ceMet hod 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 get Next Request ( ) 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 Sessi on. st ar t .
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 1 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 Triggering interface method SIP method
CAPABILITIES_QUERY 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_SUBSCRIBE Subscription.subscribe() SUBSCRIBE
SUBSCRIPTION_UNSUBSCRIBE Subscription.unsubscribe() SUBSCRIBE

Table 1: Message identifiers and SIP messages to store
Consider Figure 1 below. If the application calls get Pr evi ousResponses( SESSI ON_START) at the
sessi onAl er t i ng( ) callback, the following SIP responses should be returned in an array: 183 Session Progress
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 get Pr evi ousRequest ( SESSI ON_START) at the Sessi onI nvi t at i onRecei ved( ) 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 will return the user identity of the remote endpoint. At the Mobile Originated side the 'toUserId' should
be returned. At the Mobile Terminated side the user identity should be extracted from the 'P-Asserted-Identity' if
that header exist, otherwise the 'From' header should be used.
1. SIP URI in the P-Asserted-Identity header
2. TEL URI in the P-Asserted-Identity header
3. SIP URI in the From header
Appendix A
Default user identity
The device decides on the appropriate default user identity. However the default user identity can be overriden by
the application when creating a core service. The overriden user identity must be one of the user identities that
exist in the 'P-Associated-URI' header. The get Local User I d() method on the Cor eSer vi ce interface will then
return the overridden user identity instead of the default user identity (first in the 'P-Associated-URI' header).
When sending a SIP request the default user identity, or the explicitly set user identity, should be added to the
'P-Preferred-Identity' header.
Session
RFC: 3264, An Offer/Answer Model with the Session Description Protocol (SDP)
Start a session
When calling sessi on. st ar t () the IMS engine must prepare an SDP body and send a SIP INVITE request
message to the remote endpoint. The SDP must include a media description for each media that is offered in the
session.
If the session negotiation was successful and the remote endpoints application is Push registered, the application
should be notified with the sessi onI nvi t at i onRecei ved() callback. Note that the application is not notified before
the session negotiation is complete.
Appendix A

Figure 1: Sequence for session start and terminate
Terminate a session
When calling sessi on. t er mi nat e() the IMS engine will send a SIP BYE/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 sessi on. st ar t (). The remote endpoint should respond with 200 OK for the SIP CANCEL
followed by a 487 Request Terminated on the SIP INVITE message.
SIP BYE should be sent if the session has been established.
Update a session
When calling sessi on. updat e() the IMS engine will update the previously created SDP and include media
descriptions for new media and send a SIP INVITE request message to the remote endpoint. The media has to be
renegotiated before the updated media can be used.
Appendix A
A simple session update can be made by sending a SIP UPDATE request message. This message should only be
used if the update does not have to be renegotiated.

Figure 2: Sequence for session update with SIP INVITE and SIP UPDATE
Capabilities
RFC: 3840, Indicating User Agent Capabilities in the Session Initiation Protocol (SIP)
Requesting capabilities
When calling Capabi l i t i es. quer yCapabi l i t i es() 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.

Appendix A

Figure 3: Sequence for queryCapabilities
getRemoteUserIdentities
This method will return all SIP & TEL URI:s that are found in the Contact header. For example
mai l t o: car ol @chi cago. commust not be returned.
hasCapabilities
This method checks whether the remote device includes the same capabilities as the local IMS application given an
AppId argument. If there is a match this method will return true, however it is not guaranteed that the AppId is
installed at the remote endpoint.

A way to compute the result, is to use the received Contact header as input to the contact header construction
algorithm described earlier. If the header remains unchanged, true is returned.
If the flag to include SDP is set in the quer yCapabi l i t i es( ) 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( cont ent , cont ent Type) 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 Ref er ence. r ef er ( ) 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 connect Ref er Met hod( ) 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.
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
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 subscr i pt i onNot i f y( ) callback followed by the
subscr i pt i onTer mi nat ed( ) callback.
Appendix A
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 i msDi sconnect ed( ) .
The application has an open service
The service will be closed and notified with ser vi ceCl osed( ) in the case of a Cor eSer vi ce.
The application has an open service and a service method
The corresponding service method is terminated, for example sessi onTer mi nat ed( ) ,
subscr i pt i onTer mi nat ed( ) .
The service will be closed and notified with ser vi ceCl osed( ) in the case of a Cor eSer vi ce.
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 Sessi on, sessi onTer mi nat ed( ) should
be invoked.
Loss of Media connection
Basi cUnr el i abl eMedi a - Fire and forget. I OExcept i on may be thrown if the IMS engine detects loss of
Media connection.
Basi cRel i abl eMedi a connect i onEr r or ( ) is invoked on Basi cRel i abl eMedi aLi st ener . I OExcept i on
is thrown when the application tries to read/write to streams.
Fr amedMedi a connect i onEr r or ( ) is invoked on Fr amedMedi aLi st ener . If the application still tries to
send data del i ver yFai l ur e( ) is invoked.
St r eamMedi a - Except i on is thrown from the Pl ayer .
Reestablishment of communication
When the IMS engine is able to reestablish the connection to the IMS network, the IMS engine should invoke
i msConnect ed() on the Connect i onSt at eLi st ener . The application must create and open new services, this in
not done by the IMS engine.

jsr281 Api FR v1.0

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

jsr281 Api FR v1.0

Hochgeladen von

Copyright:

Verfügbare Formate

JSR 281 IMS Services API

for Java Micro Edition

Das könnte Ihnen auch gefallen