IP Multimedia Subsystem (IMS) Services API

IP Multimedia Subsystem (IMS) Services API

for Java™ Micro Edition

Early Draft version 0.5

JSR 281 Expert Group [email protected]

Java Community Process

2

3

ERICSSON AB AND BENQ MOBILE GMBH & CO. OHG ARE WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS LICENSE AGREEMENT ("AGREEMENT"). PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY THEM, SELECT THE "DECLINE" BUTTON AT THE BOTTOM OF THIS PAGE AND THE DOWNLOADING PROCESS WILL NOT CONTINUE. Specification: JSR-281 IMS Services API ("Specification") Version: 0.5 (EDR Draft Status: Pre-FCS Public Release Release: 11/2006 Copyright 2006 Ericsson AB / BenQ Mobile GmbH & Co. OHG All rights reserved. NOTICE The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of <Specification Lead> and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement. Subject to the terms and conditions of this license, including your compliance with Paragraphs 1, 2 and 3 below, <Specification Lead> hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under <Specification Lead>'s intellectual property rights to: 1. Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Specification. 2. Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation: (i) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented; (ii) is clearly and prominently marked with the word "UNTESTED” or "EARLY ACCESS" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee’s control; and (iii) includes the following notice: "This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP." 3. Distribute applications written to the Specification to third parties for their testing and evaluation use, provided that any such application includes the following notice: "This is an application written to interoperate with an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP." The grant set forth above concerning your distribution of implementations of the Specification is contingent upon your agreement to terminate development and distribution of your implementation of early draft upon final completion of the Specification. If you fail to do so, the foregoing grant shall be considered null and void. Other than this limited license, you acquire no right, title or interest in or to the Specification or any other <Specification Lead> intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from <Specification Lead> if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification. "Licensor Name Space" means the public class or interface declarations whose names begin with "java", "javax", "com.<Specification Lead>" or their equivalents in any subsequent naming convention adopted through the Java Community Process, or any recognized successors or replacements thereof TRADEMARKS

4

No right, title, or interest in or to any trademarks, service marks, or trade names of <Specification Lead> or <Specification Lead>'s licensors is granted hereunder. Java and Java-related logos, marks and names are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. DISCLAIMER OF WARRANTIES THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY <Specification Lead>. <Specification Lead> MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product. THE SPECIFICATION COULD 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. <Specification Lead> 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. LIMITATION OF LIABILITY TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL <Specification Lead> OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF <Specification Lead> AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You will hold <Specification Lead> (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license. RESTRICTED RIGHTS LEGEND If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions). REPORT You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To the extent that you provide <Specification Lead> with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant <Specification Lead> 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. GENERAL TERMS Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply. The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee. This Agreement is the parties' entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized representative of each party. Rev. January 2006

Non-Sun/Spec/Public/EarlyAccess

Contents

5

Contents

Contents............................................................................................................................................3 Preface..............................................................................................................................................3 Revision History...............................................................................................................................3 Who Should Use This Specification ................................................................................................3 How This Specification Is Organized ..............................................................................................3 References ........................................................................................................................................3 Report and Contact...........................................................................................................................3 1 Introduction ..............................................................................................................................3

1.1 General .............................................................................................................................3 1.2 Scope ................................................................................................................................3 1.3 Purpose .............................................................................................................................3 1.4 Relationship to other JSRs ...............................................................................................3 1.5 Terms and Abbreviations .................................................................................................3 1.6 Contributors......................................................................................................................3 1.7 Document Conventions ....................................................................................................3

2 Architecture..............................................................................................................................3 2.1 General Architecture ........................................................................................................3 2.2 Specification Requirements..............................................................................................3 2.3 Package Summary ............................................................................................................3

3 General Technical Basics .........................................................................................................3 3.1 Addressing........................................................................................................................3 3.2 Application and Standardized Service identifiers ............................................................3 3.3 Routing Messages ............................................................................................................3 3.4 Registration ......................................................................................................................3 3.5 Quality of Service.............................................................................................................3 3.6 Access Networks ..............................................................................................................3 3.7 Combinational Services with IMS (CSI) .........................................................................3 3.8 Configuration ...................................................................................................................3 3.9 Behaviour on network loss...............................................................................................3

4 Core API...................................................................................................................................3 4.1 Overview ..........................................................................................................................3 4.2 IMS Management.............................................................................................................3 4.3 Services ............................................................................................................................3

Contents

6

4.4 Sessions and Session control............................................................................................3 4.5 Multimedia .......................................................................................................................3 4.6 Media Rendering ..............................................................................................................3 4.7 Events Framework............................................................................................................3 4.8 Quality of Service.............................................................................................................3 4.9 Other functionality ...........................................................................................................3

5 Service API ..............................................................................................................................3 5.1 XML Document Management API ..................................................................................3 5.2 Push-to-Talk over Cellular API........................................................................................3 5.3 IMS Presence API ............................................................................................................3

6 Core API...................................................................................................................................3 7 Service API ..............................................................................................................................3 8 Glossary....................................................................................................................................3

Preface

7

Preface

This document defines the IP Multimedia Subsystem (IMS) Services API Specification for the Java Platform, Micro Edition (JMETM).

This API specification is the result of a JSR defining an optional package, following the definition in JCP 2, version 2.6 (see http://jcp.org/en/procedures/jcp2 for details).

Revision History

Date Version Description 10-February-2006 IMS Specification First draft provided by the Specification Leads 18-July-2006 Draft version 0.2 Changes and clarifications 25-July-2006 Draft version 0.3 Changes as a consequence of F2F meeting Kista 06/06 27-September-2006 EDR version 0.4 Proposal for Early Draft Review 31-October-2006 EDR version 0.5 Early Draft Review

Who Should Use This Specification

This document is targeted at the following audiences:

The Java Community Process (JCP) expert group defining this profile

Implementers of the IMS API (JSR-281)

Application developers targeting the IMS API (JSR-281)

Network operators deploying infrastructure to support IMS API (JSR-281) enabled devices

How This Specification Is Organized

This specification consists on the following two parts:

JavaDoc API Documentation

A textual specification

There are requirements listed both in this document and the API documentation. Where there are conflicts, the requirements listed in this document override the API documentation.

References

8

References

3GPP IMS-related Specs:

[23.003] 3GPP TS 23.003: Numbering, Addressing and Identification, Release 6

[23.228] 3GPP TS 23.228: IP Multimedia Subsystem (IMS); Stage 2, Release 6, V6.11.0

[23.279] 3GPP TS 23.279: Combining Circuit Switched (CS) and IP Multimedia Subsystem (IMS), Stage 2, Release 7, V7.4.0

[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, V6.9.0

[24.279] 3GPP TR 24.279 Combining Circuit Switched (CS) and IP Multimedia Subsystem (IMS) services; Stage 3, Release 7, V7.2.0

[24.147] 3GPP 24.147 Conferencing using the IP Multimedia (IM) Core Network (CN) subsystem, Release 6, V6.3.0

[24.247] 3GPP 24.247 Messaging Service using the IP Multimedia (IM) Core Network (CN) subsystem, Release 6, V6.4.0

OMA Specs:

[PoCReq] OMA Push to Talk over Cellular Requirements, Version 1.0 – 29 Mar2005, "OMA-RD-PoC-V1_0-20050329-C.pdf"

[PoCArch] Push to talk over Cellular (PoC) - Architecture, Candidate Version 1.0 – 04 Nov 2005, "OMA-AD-PoC-V1_0-20051104-C.pdf"

[PoCXDM] Push to talk over Cellular (PoC) XDM Specification, Candidate Version 1.0 – 04 Nov 2005, " OMA-TS-PoC-XDM-V1_0-20051104-C.pdf"

[PoCUser] Push to talk over Cellular (PoC) User Plane, Candidate Version 1.0 – 04 Nov 2005, “OMA-TS_PoC-UserPlane-V1_0-20051104-C.pdf”

[XDMCore] XML Document Management (XDM) Specification, Candidate Version 1.0 – 22 Nov 2005, “OMA-TS-XDM_Core-V1_0-20051122-C.pdf”

[XDMShared] Shared XDM Specification, Candidate Version 1.0 – 22 Nov 2005, “OMA-TS-XDM_Shared-V1_0-20051122-C.pdf”

[XDMArch] XML Document Management Architecture, Candidate Version 1.0 – 06 Oct 2005 “OMA-AD-XDM-V1_0-20051006-C.pdf”

[XMDReq] XML Document Management Requirements,Candidate Version 1.0 – 17 Mar 2005, “OMA-RD-XDM-V1_0-20050317-C.pdf”

[XCAP] “The Extensible Markup Language (XML) Configuration Access protocol (XCAP)”, J.Rosenberg, June 2005, http://www.ietf.org/internet-drafts/draft-ietf-simple-xcap-07.txt

SIP Specs:

[RFC 3261] "SIP: Session Initiation Protocol"

[RFC 3265] “Session Initiation Protocol (SIP) – Specific Event Notification“

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

[RFC 3966] “The TEL URI for Telephone Numbers”

Report and Contact

9

Java Specification Requests:

[JSR-32] "JAIN SIP API Specification"

[JSR-125] "JAIN SIP Lite"

[JSR-135] "Mobile Media API"

[JSR-141] "SDP API"

[JSR-180] "SIP API for J2ME"

[JSR-186] "JAIN Presence"

[JSR-187] "JAIN Instant Messaging"

[JSR-205] "Wireless Messaging API 2.0"

[JSR-234] "Advanced Multimedia Supplements"

[JSR-304] “Mobile Telephony API version 2”

[JSR-307] “Network Mobility and Mobile Data API”

Report and Contact

Your comments on this specification are welcome and appreciated. Please send your comments to: [email protected]

Introduction

10

1 Introduction

1.1 General

The goal of this document is to put requirements on the Java IMS APIs. This will show what functionality should be exposed to (and hence what functionality should be hidden from) applications. At the starting point, there are the huge IMS-related 3GPP and OMA documents on one hand and the entire mobile system on the other hand. A methodology is needed to manage the complexity of reaching the goal. A useful way is to this is explained in the following steps:

1. Divide: Divide and break down the specifications into requirements

2. Structure: Structure the system into layers according to levels of abstractions.

3. Requirement mapping: When requirements and layers are combined it can be decided whether a requirement shall be realized in a certain layer. For each such a decision, rationale shall be given. When requirements are realized across several layers, then the solutions in each of these layers must be integrated over an interface.

For this work, these layers of architecture structure are identified:

1. Application layer

2. IMS Engine layer

3. Protocol stacks layer including the network.

The Java API is the boundary between Java applications and the IMS Engine layer.

The specifications span thousands of requirements. For a start, the [22.228] (as of release 6) identifies these major requirement (functional and non-functional) areas (here somewhat reformulated) in IMS:

1. Establish IP Multimedia sessions

2. Negotiate Quality of Service (QoS)

3. Interworking seamlessly with PS and CS networks (Internet and cellular)

4. Roaming

5. Operator control over services

6. Rapid creation of services that do not require standardization (non-functional)

7. Access network independence (non-functional)

8. Security, privacy and authentication

Combining these in a table shows which of the 3GPP requirement areas need interfaces. For clarity, the JSR is shown in a row on its own. Some non-functional requirements are also intrinsic to the API.

TABLE 1-1 Affection of 3GPP requirements to several layers Session QoS Interworking Roaming Operator Rapid Access Security Java X X - - - - X / - X JSR X X - - - X X / - X IMS X X X - X X X / - X Stack X X X X X X X X Legend: X = affected, - = not affected, X / - = maybe affected (TBD)

Introduction

11

1.2 Scope

X in Session: The user initiates IMS calls (directly or indirectly), and also decides to accept incoming calls.

X in QoS: QoS depends on the situation at hand, the user preference, and on the particular application.

in Interworking: CS and PS domain integration is not considered part of the logic of IMS service API that we are targeting here.

in Roaming: The logic of IMS services stay invariant of roaming (subject to operator and network availability constraints).

in Operator: Operator requirements do not directly affect the applications. (It does affect the underlying IMS Engine via the IMS subscriber information stored on the SIM card.)

X in Rapid: It is an intrinsic property of the API to enable rapid realization of new services. By this, intuitiveness and ease of use can be guaranteed. And it is the best way to straightforward to port existing multimedia session-related application to this API.

X / - in Access: Even though IMS application logic is independent of access network (as long as it fulfills constraints on QoS, bandwidth, latency etc), the cost of network usage is important for the end user. It is an open issue whether this is within scope of the IMS API. This issue is not unique for this JSR.

X in Security: Security is provided to protect users. Whenever reasonable, the user is given possibilities to affect security settings.

As a consequence, the mandatory Core API includes the following IMS functionality:

IMS session management/monitoring

QoS settings

Security

Access

The second part of this JSR is an optional Service API, covering the following:

Push-to-Talk over Cellular (PoC)

IMS Presence

XML Document Management (XDM)

Utilities in order to support those activities

Potential server APIs for IMS applications are not covered by JSR-281. The EG focus on the API available on the terminal side.

1.3 Purpose

JSR-281 is intended to be used by application developers who wish to build Java applications for terminals that use the IP Multimedia Subsystem (IMS), which is the standard for future mobile phone multimedia applications.

Introduction

12

1.4 Relationship to other JSRs

JSR 118/139: MIDP2.0 /CLDC 1.1 integration

JSR 118/135/234: Manage multimedia content. Recorders and Players.

JSR 120/205: Messaging. IMS includes a concept to send messages.

JSR 164/165/186/187: Presence integration

JSR 180: SIP is used in IMS

JSR 304: Mobile Telephony API version 2

JSR-307: Network Mobility and Mobile Data API

1.5 Terms and Abbreviations

TABLE 1-2 Terms and Abbreviations Term Definition

IAB Incoming Instant Personal Alert Barring

IETF Internet Engineering Task Force

IMS IP Multimedia Subsystem

ISB Incoming Session Barring

JSR Java Specification Request

J2ME Java 2 Micro Edition

OMA Open Mobile Alliance

PoC Push-to-Talk over Cellular

RFC Request For Comments

SIP Session Initiation Protocol

SIMPLE SIP for Instant Messaging and Presence Leveraging Extensions

XMPP Extensible Messaging and Presence Protocol

Alert

Application Unless otherwise indicated, a Java application (MIDlet suite) interacting with the APIs of JSR 281

Callee User(s) operating the Terminating UEs.

Caller User operating the Originating UE

Group [of participants] A predefined set of Users that is identified by a SIP URI.

Incoming session Session related to the terminating endpoint

FramedMedia Non-streamed transfer of a media object not (necessarily) in real-time e.g. by using MSRP

Participant(s) User(s) participating in a Session.

PUI Public User Identity

Originating Endpoint Endpoint that invites others to participate in a Session.

Introduction

13

Originating UA/UE UA/UE where a call is made

Outgoing session Session related to the originating endpoint

Remote [endpoint] From the originating endpoint, the Remote refers to the terminating endpoint. From the terminating, it is the originating endpoint.

Session A SIP session established by the procedures of this specification.

StreamingMedia Streamed transfer of media content in real-time, e.g. by using RTP/RTCP

Terminating Endpoint Endpoint that is invited to participate in a Session.

Terminating UA/UE UA/UE where a call is received (destination)

UA [SIP] User Agent

UE User Equipment, represents the functionality of the device.

User Any entity using the described features through the User Equipment.

1.6 Contributors

This specification was produced by the IMS Services API Expert Group (IMSEG), as a part of the Java Community Process. The following companies, listed in alphabetical order, were members of the Expert Group:

BenQ Mobile GmbH & Co. OHG1

China Mobile Communications Co. Ltd.

Cingular Wireless

Ericsson AB2

esmertec AG

IBM

Infineon Technologies AG (Comneon)

LG Electronics Inc.

Lucent Technologies

Matsushita Electric Industrial Co., Ltd.

Motorola

NEC Corporation

Nokia Corporation

Openera Technologies, Inc.

Orange France SA

Philips Electronics Ltd.

Qualphone Inc.

Research in Motion, Ltf. (RIM)

Samsung Electronics Corporation

SBC Technologies Research

1 Overall Specification Lead 2 Overall Specification Lead

Introduction

14

Siemens AG

Sirf Technology Holdings, Inc

Sony Ericsson Mobile Communications AB

Sprint

Sun Microsystems, Inc.

Telecom Italia

T-Mobile International AG & Co. KG

Vodafone

1.7 Document Conventions

1.7.1 Definitions This document uses definitions based upon those specified in RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt).

TABLE 1-3 Specification Terms 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.

1.7.2 Formatting Conventions This specification uses the following formatting conventions.

TABLE 1-4 Formatting Conventions Convention Description

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

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

Architecture

15

2 Architecture

2.1 General Architecture

This section addresses issues that both implementers and developers will encounter when implementing and developing IMS Services API.

FIGURE 2-1: JME IMS Architecture

Registration/Auth

Core API

IMS Session

StreamMedia

Player Recorder

Service API

IMS Service Enablers IMS Core

PacketMedia PoC GLM IMS

Presence

PacketMedia

Player

PoC GLM

Recorder

StreamMedia IMS Presence

e.g. Game

Non standard

PoC

Gaming Messaging

PoC

Non standard

Event framework Network

Session

Network

Standard ....

Event Framework

Basic Messaging

Basic Messaging

XDM

XDM

JSR-281

Application Layer

Stacks: SIP/SDP/RTP/RTCP/MSRP/XML/HTTP/XCAP

API Layer

Implementation Layer

Device SW Platform Layer

Functionality implementation Interface object

Architecture

16

2.2 Specification Requirements

This section lists some explicit requirements of this specification. Other requirements can be found in the Javadoc and textual parts associated to the APIs. If any requirements listed here differ from requirements listed elsewhere in the specification, the requirements here take precedence and replace the conflicting requirements.

2.2.1 Non-functional Requirements The APIs of JSR-281 SHALL be implemented content type agnostic.

The API of the Core package SHALL be implemented service independent.

The functionality exposed through the Core API SHALL be based on Release 6 of 3GPP IMS specifications.

The JSR specification contains two optional packages: Core and Service packages. A compliant implementation MUST realize at least one of these packages

2.2.2 System Requirements The IMS core SHALL manage, refresh and renew IMS registration and IMS sessions, when necessary

It SHALL be possible to specify an application to be launched at an incoming session invitation according to the type of service

Registration data for auto-invocation SHALL be provisioned

An application SHALL be able to register/de-register an application for auto-invocation at runtime

The implementation SHALL follow the existing applicable security framework of the underlying profile.

On a CLDC/MIDP2.0-device, the Java push registry SHALL be used

On a CLDC/MIDP2.0-device, the jad/jar file manifest properties SHALL be used for provisioned data

The IMS core implementation SHALL handle the IMS protocol details

The IMS core implementation SHALL keep track of session states and progress

The IMS core implementation SHALL negotiate and determine codec and media characteristics

The IMS core implementation SHALL set up network connections to make available for the media streams

IMS implementation SHALL identify the receiving application and forward session invitations and events according to the Application ID tag

IMS implementation SHALL release any resource reserved by an application when that application exits

2.3 Package Summary

Core Packages (mandatory) javax.microedition.ims This package collects classes and interfaces that enable

an application to reference and use the platform's IMS capabilities

javax.microedition.ims.core This package collects classes and interfaces that enable an application to create IMS services

javax.microedition.ims.core.media The package contains entities used to create media flows

Architecture

17

for IMS Service Packages (optional) javax.microedition.ims.service.poc This optional package defines the JSR 281 Push-to-Talk

over Cellular (PoC) API javax.microedition.ims.service.presence This optional package defines the JSR 281 Presence

API. javax.microedition.ims.service.util This optional package defines utility entities for JSR 281

service enablers. javax.microedition.ims.service.xdm This optional package defines the JSR 281 XML

Document Management (XDM) API.

General Technical Basics

18

3 General Technical Basics

3.1 Addressing

3GPP IMS mandates Private and Public user identities for IMS subscribers. The private identity is used for subscription management, and is internal to the operator and the subscriber. It is used for registation, authorization, administration and accounting purposes. A private identity is not used for routing of SIP messages. All of these purposes are considered to be managed in the JSR implementation, and the Private user identity or subscription information are not exposed in the API.

The Public User Identity forms the main identification key for the user. The User Identity/identities are used to allow the user to request communication to other users. The Public Identity is central for all IMS related tasks concerning the user, represented by this identity.

A user SHALL be able to address other user by using either email style (alphanumeric format), or a telephone style number (MSISDN or other) as a Public User Identity. The user MAY define a display name as a means to personalize what should be displayed as his “nickname” to the other users during a session.

3.2 Application and Standardized Service identifiers

This section will describe describes in detail Communication Service IDs to identify standardized services, and Application IDs to identify applications.

3.3 Routing Messages

A JSR implementation MUST support Message Routing.

Message routing is the functionality that forwards an incoming SIP message to the correct application. It extracts information from the SIP message to form a routing key and compares with the application properties. A match indicates the correct application. The application properties are configured at installation time.

When handling received messages from other applications, it has to be taken into account that there is possibly no ApplicationID at all. The routing key in this case may or may match any installed application.

The following proposal is a sketch on how an implementation could handle the described situations.

In case 1, an application has been developed on top of JSR-281. The routing key for the message is the ServiceID, which is included in the SIP message. This case can be handled straight forward (see next page).


19

FIGURE 3-1: Applications developed on top of JSR-281 – ApplicationID is routing key

In case 2, the situation is different. We have now a legacy application A1 (not implemented on top of JSR-281). There is no ApplicationID included in the SIP message. JSR-281 implementation will use the routing rules for finding the receiver application.

The routing key will now be based on the following system:

methodDomain.key, while

methodDomain represents the SIP methods belonging to the certain message type, e.g. Session, EventFramework, Message

key represents the differentiation factor within the methodDomain, e.g. for Session it will be a media description in SDP, for EventFramework it will be the eventName, and for Message it will be the MIME type

Examples may be Session.media (from “m=” in SDP), EventFramework.Event_1, Message.Text

The domain names and key names that a certain application will manage have to be included into the JAD file as the optional conmfiguration parameters, additionally to the mandatory ServiceID.

JSR-281

API

Appl_A1 Appl_A2

ApplicationID_2 ApplicationID_1

Router/ Dispacher

ApplicationID_1

JSR-281

API

Appl_A1

ApplicationID_1

INVITE(ApplicationID_1)

Appl_A1 JAD file ... ApplicationID_1 ...

INVITE (ApplicationID_1)


20

All the domains and keys are well described within this specification (see below).

FIGURE 3-2: Legacy Application (not JSR-281-based) – no ApplicationID. The created routing key matches an installed application.

In case 3, there is a legacy application A2, not implemented on top of JSR-281. Again, there is no ApplicationID included in the SIP method. And again a routing key will be created using the routing rules as described in case 2. But this time, the routing key does not match any installed application and the message is discarded.

JSR-281

API

Appl_A1 Appl_A2

ApplicationID_2 ApplicationID_1

Router/ Dispacher

routingKey

Appl_A1

Appl_A1 JAD file ... ApplicationID_1 m= m= EventFramework= EventName= ...

Message(…)


21

FIGURE 3-3: Legacy Application (not JSR-281-based) – no ApplicationID. The created routing key does not match any installed application.

3.4 Registration

The concept of Registration is central to the IMS. Through the registration procedure, the user’s identity is considered by the network as being online, and can use access a set of services meanwhile. At the same time all the applications installed on the users devices are registered using ServiceId and ApplicationID and are accessible for all other users in IMS network. For this purpose the notion of ServiceId and ApplicationId is crucial for successful registration of capabilities of the device. ServiceId represents the standardized service and is already standardized

JSR-281

API

Appl_A1 Appl_A2ApplicationID_2 ApplicationID_1

Router/ Dispacher

routingKey

Appl_A1 JAD file ... ApplicationID_1 m= m= EventFramework= EventName= ...

INVITE(SDP)

Appl_A2


22

both in 3GPP and OMA. ApplicationId is still the subject for standardization but JSR-281 chooses to use this information element to avoid future problems. Number of new applications is expected to quickly increase using high level API provided by JSR-281. Identification of these applications will be crucial both in registration and routing context.

The basic principle for registration of the services is that all the applications installed on the device will be registered by power-on. Implementation of JSR-281 will scan all the installed applications and registration will be done if at least one application is present. There are though two cases when the application will not be registered:

• User choses not to register the application (the mean for this choice has to be secured by the implementation)

• Application developer includes in configuration file (JAD in case of CLDC) the preference for the application not to be registered.

In both cases, registration is is done when a Service is created. Registrationsis of the service is maintained as long as the Service is not terminated. This allows the registration mechanism details to be hidden to the developer even if not initial registration is applied.

3.5 Quality of Service

This chapter will add more details and guidance of the underlying mechanisms for establishing Quality of Service in JSR 281 implementations.

3.6 Access Networks

The JSR 281 APIs offer the application to select the access network. This section will give more detail on this functionality.

3.7 Combinational Services with IMS (CSI)

3GPP Release 7 of CSI [24.279, 23.279] is supported in the JSR 281 APIs. CSI is a framework for combining Circuit Switch (CS) and IMS services using a CS speech or CS multimedia call in association with an IMS session. Because the references CSI-specifications of 3GPP are work in progress, the approach for inclusion of CSI in JSR 281 is a careful one, focusing on the key aspects of CSI: CSI session setup, and CSI capabilities exchange. CSI involves a necessary element of CS handling, but this is kept out of the scope of the JSR API, and is up to the application or device to set up and control the calls.

Definition: A CSI combine refers to the case when the implementation detects that a session (initiated according to the CSI specifications) and a CS call includes the same endpoints.

The API facilitates for the application to create a CSI session. In a combinational session scenario, the application can get the tel-URI of the remote end and use that to setup the call. In a combinational call scenario, the session setup may leave the remote Public User Identity null which means that the session will by default be addressed to the remote active current call.

When a CSI session is created, the implementation MUST search for a matching connected CS call on the device to combine with. If one is found, then the session records this. If no matching call is found, the implementation MUST wait for a matching connection to take place. When this happens, the application is notified of a combine. A notification occurs if a combined CS call is terminated. Until the session terminates, the implementation is in active search for matching calls.

Capability exchanges are supported in the capability class even for CSI. The CSI specifications list a number of criteria for when to make an exchange. These criteria should not be necessary for an application to handle. The JSR


23

implementation decides when a capability exchange shall actually occur with the remote. When the application queries for remote capability, it is implementation dependent whether an OPTIONS will be sent out, or if cached capabilities suffice. Either way, the returned capabilities to the application are the actual ones.

If the device is not IMS registered and gets engaged in a CS call, then the UE should make an IMS registration using a Public User Identity causing the MSISDN used in the CS call to be implicitly registered. This is implementation dependent.

More detail on the functionality will follow.

3.8 Configuration

This section will give more detail on the functionality required.

Configuration on IMS level is not within scope of this specification. Applications are configured with static provisioned properties at installation time of the supported capabilities and ApplicationID such that messages can be routed correctly and proper registrations can be performed.

It is possible to configure each application with the Public User ID the user wants it to be registered with. A default Public User ID may be provisioned if the application suite is customized and distributed via the operator. Otherwise, it is platform dependent which ID should be used for the initial registration. The Public User ID can be changed, and persists between system restarts. At application uninstall, the configured Public User IDs shall be removed.

The precise mechanisms needed for this type of registration is not yet decided.

3.9 Behaviour on network loss

If the access network coverage is lost temporarily the consequences for the applications SHOULD be kept at a minimum. The implementation shall make sure that the user experience of streaming media, for example, makes a graceful degradation while the loss of coverage is in effect. When coverage is restored, the streaming resumes.

If network connections are completely lost for a length of time (for example, resulting in an unregistration where the device IP number has changed) then streaming may not be able to be resumed. Transfer of large messages should be possible to be resumed at the point of interruption.

Core API

24

4 Core API

4.1 Overview

The Core package of the JSR comprises a service independent API that enables creation of Java applications implementing non-standardised IMS-based services. The Core API builds on requirements on the 3GPP Rel-6 specifications [23.003], [23.228], [24.229].

The Core API makes basic IMS functionality available to a Java developer. The API with its level of abstraction exposes the important functions whilst hiding details and intrinsics of IMS and underlying technologies. This facilitates rapid service creation and prototyping.

The API is useful to create a range of services ranging from a simple ones like sending a page-mode message, as well asto advanced compound services with multiple sessions and bi-directional interactive real-time media flows., A custom media with application-specific rendering and mixing functionality from the Service part of the JSR as well as from other JSRs, can also be included..

The API is also independent of particular access networks used for the IMS services, e.g. GPRS, WLAN, DSL, DUN, etc. but it provides the information about the available access networks supporting IMS and gives possibility to choose one of those. There is also a separation between the IMS signal plane (hidden for the application developer) and the IMS media plane.

4.2 IMS Management

The Core API contains a single entry point, IMS Manager, to create all types of services. IMS Manager is the highest level object aggregating all the services belonging to an application. The application identity is determined on this level.

4.3 Services

The central concept in JSR-281 is a service. API provides possibility to create any number of services composing the application. In most cases the application includes one Core services, defining any proprietary multimedia service, combined with standardized service.

Standardized service, e.g. PoC, encapsulate functionality that is well defined and standardized. A generic services is the container for aggregation of any number of communication sessions, to be created within the service and additionally offer the application a basic paging-mode communication.

4.4 Sessions and Session control

The session is a basic abstraction of point to point service communication, aggregating media connections.

The session offers possibility to invite a remote party to a multimedia service that includes various types of media, e.g. streaming audio and video (see below). The remote party has the option to accept or reject the invitation including the media offers. It is possible to perform some basic session control, like pause, resume, and terminate. The whole process of negotiation and reserving network resources is based on SDP and indicated Quality of Service etc, is hidden from the application.

A session can be manipulated in some additional ways:

• An established session can be transferred to another device.

Core API

25

• Incoming invitations can be deflected to another device.

• Sessions can be modified even after they have been established by adding, changing and removing media.

4.5 Multimedia

Any number of Media can be created within one session. Media connections are based on various types of protocols: RTP, MSRP, TCP and UDP. RTP allows streaming for, typically, but not necessarily limited to, audio and video. The MSRP type of media allows objects (like documents, texts, images, etc) to be transferred to the other party as MIME typed messages. Media can also be created based on TCP or UDP and used to transfer content type independent data. These are provided for those types of applications that want need to have control over their own data format and where the rendering logic is placed in the application.

4.6 Media Rendering

The Core API provides a media player for RTP-carried streaming audio and video. This is used for media type that the JSR implementation recognizes and can provide a codec for. In this case, the JSR implementation forwards the data stream directly to the player. No streamed data content of the media passes through the Java application. Still, the Java application can control the session and the player. For applications that use application-specific format (most probably using UDP och TCP-based media), it is possible for the Java application to access the content via a data stream supplied from the system. It can then read and process the content according to its own logic.

4.7 Events Framework

An application can upload some information to an application server on the network. This can be anything, but a common example is Presence information. Moreover, the Java application can subscribe to receive events generated from network IMS services. When such an event occurs, the application will be readily informed with details of the event.

4.8 Quality of Service

Quality of service apply to media. It is about reserving network capacity to guarantee a certain level of data throughput and minimum delay. Because of the network independency principle, the approach is based on the IP integrated services framework RSVP described in RFC 2210 - describing the data flow that the application is expected to handle, rather that specify network specific parameters. This is currently under investigation..

4.9 Other functionality

APIs exist to allow an application to:

• Send paging messages to another party.

• Query the capabilities of the remote party's device to make application-specific preferences for setting up sessions.

• An application with advanced requirements can access message bodies and headers of the signalling plane.

The JSR implementation includes a functionality to route incoming invitations to the appropriate application, that can be launched if necessary.. This is based on provisioned data (Feature Tags) about the capabilities of the installed applications. See further section 3.2

Service API

26

5 Service API

The services considered in the following section are more or less based on each other. The XML Document Management Service (XDM service) specified by OMA is a standard for managing and manipulation XML documents. As part of this standard, some specific types of documents likely to be used by different application services (e.g. PoC) are introduced [XDMShared]. As part of the OMA PoC standard, PoC specific XML documents are specified [PocXDM]; specifications for other services as Presence etc. are currently under specification.

In this requirements document, this hierarchy of abstractions is modelled by a set of APIs reflecting this hierarchy. The basis enabling API is the XDM API. It covers the functionality of OMAs XDM [XDMCore] and offers a high level API to the user in order to provide a convenient possibility to create and manage XML documents.

The Group and List Management API (currently not specified by OMA) provides mechanisms for managing generic groups, URI lists and user profiles including management of service access control lists. While this service is currently not fully specified by OMA, part of it is already covered by the Shared XDM Specification [XDMShared]. The rest of the API consists of reasonable abstractions that are very likely to be reused by various services. Basis of this service may be the OMA XDM service, which means that each group, list and user profile is represented as a XML document on the XDMS.

The PoC service requires PoC specific abstractions as PoC Groups and PoC User Access Policies. These are created by extending groups as offered by the Group and List Management API by PoC specific elements and attributes and introducing an abstraction for PoC User Access Policies.

In the future we expect that further services will expand the XDM and/or Group and List Management API. Thus, these API are specified as general as possible while offering as much comfort as needed.

5.1 XML Document Management API

This API facilitates the programmer to easily use the XDM infrastructure that has been defined by OMA. The detailed architecture of this document management infrastructure is defined in [XDMArch]. The XDM specification is based on the XML Configuration Access Protocol (XCAP), see [XCAP].

5.2 Push-to-Talk over Cellular API

Push-to-Talk over Cellular (PoC) is an IMS application that requires essential features of the IMS system. In particular, the session concept offered by the Session Initiation Protocol (SIP) is required. Even though several Java APIs exist that model SIP sessions (JSR-32 - JAIN-SIP, JSR-125 SIP Lite, JSR-180 SIP for J2ME), these are not on the high level of abstraction that we strive for in JSR-281.

The JSR-281 PoC API is intended to allow easy initiation, management and termination of PoC sessions with individual participants as well as pre-defined groups of participants. The PoC API enables dynamic modification of PoC sessions in terms of adding or removing participants.

A future extension of PoC is PoC video, a service that allows transmission of a video stream alternatively or in parallel to audio streaming. In order to enable extensions of the PoC API like PoC video, a mechanism how to add new capabilities to the PoC API is required.

In the following sections, different groups of requirements are detailed. All requirements are referring to features that applications being built upon the PoC API can use. Therefore, the notions users / participants used in the descriptions of the requirements are including those applications as well. Instead of using wording like “The PoC API SHALL provide means to enable an application to address the invited user / application by using …” the shorter and more intuitive wording “The user SHALL be able to address the invited user by using …” has been used in all cases.

Service API

27

The wording in this chapter relies on the terminology used in the OMA specifications.

5.3 IMS Presence API

This API facilitates the application programmer to create and manage IMS presentities and presence profiles, publish and subscribe for presence information as well as to specify policies regulating the access to presence information. The API should be enabled sufficiently generic such that all three different types of presentities (person, device, service) can be handled.

Core API

28

6 Core API

Package Summary Page

javax.microedition.ims This package collects classes and interfaces that enable an application to reference and use the platform's IMS capabilities.

3

javax.microedition.ims.core This package collects classes and interfaces that enable an application to create IMS services.

3

javax.microedition.ims.core.media The package contains entities used to create media flows for IMS.

3

Package javax.microedition.ims

This package collects classes and interfaces that enable an application to reference and use the platform's IMS capabilities.

See: Description

Interface Summary Page

ImsNetwork The ImsNetwork is a representation of an IMS access network. 3

ImsPlatformListener A listener type for receiving notifications of system events concerning resources such as registration state of user identities and the avaliability of access networks.

3

ImsService An ImsService is a container for dialogs and media connections. 3 Class Summary Page

ImsManager This class provide methods for observing the registration state of IMS user identities and availability of IMS access networks.

3

Exception Summary Page

IMSDocumentNotExistingExceptionAn IMSDocumentNotExistingException is thrown if a server-side document that the IMS engine tries to access does not exist.

3

IMSMalformedDateTimeException An IMSMalformedDateTimeException is thrown if a method is invoked with a malformed XML date/time parameter.

3

IMSMalformedURIException An IMSMalformedURIException is thrown if a URI supplied as an argument is malformed.

3

Core API

29

IMSObjectExistsException An IMSObjectExistsException is thrown by a factory method if an object already exists in the registry of the respective manager.

3

Package javax.microedition.ims Description

This package collects classes and interfaces that enable an application to reference and use the platform's IMS capabilities.

Since: IMS API pre-EDR

Class IMSDocumentNotExistingException javax.microedition.ims

java.lang.Object java.lang.Throwable java.lang.Exception javax.microedition.ims.IMSDocumentNotExistingException

All Implemented Interfaces: Serializable

public class IMSDocumentNotExistingException extends Exception

An IMSDocumentNotExistingException is thrown if a server-side document that the IMS engine tries to access does not exist.

Constructor Summary Page

IMSDocumentNotExistingException() Public constructor 3

IMSDocumentNotExistingException(String message) Public constructor with message parameter 3

Constructor Detail

IMSDocumentNotExistingException

public IMSDocumentNotExistingException()

Public constructor

Core API

30

IMSDocumentNotExistingException

public IMSDocumentNotExistingException(String message)

Public constructor with message parameter Parameters:

message - a text specifying the reason why the exception has been thrown

Class IMSMalformedDateTimeException javax.microedition.ims

java.lang.Object java.lang.Throwable java.lang.Exception javax.microedition.ims.IMSMalformedDateTimeException


public class IMSMalformedDateTimeException extends Exception

An IMSMalformedDateTimeException is thrown if a method is invoked with a malformed XML date/time parameter.


IMSMalformedDateTimeException() Public constructor 3

IMSMalformedDateTimeException(String message) Public constructor with message parameter 3

Constructor Detail

IMSMalformedDateTimeException

public IMSMalformedDateTimeException()

Public constructor

IMSMalformedDateTimeException

public IMSMalformedDateTimeException(String message)

Public constructor with message parameter

Core API

31

Parameters: message - a text specifying the reason why the exception has been thrown

Class IMSMalformedURIException javax.microedition.ims

java.lang.Object java.lang.Throwable java.lang.Exception java.lang.RuntimeException java.lang.IllegalArgumentException javax.microedition.ims.IMSMalformedURIException


public class IMSMalformedURIException extends IllegalArgumentException

An IMSMalformedURIException is thrown if a URI supplied as an argument is malformed.


IMSMalformedURIException() Public constructor 3

IMSMalformedURIException(String message) Public constructor with message parameter 3

Constructor Detail

IMSMalformedURIException

public IMSMalformedURIException()

Public constructor

IMSMalformedURIException

public IMSMalformedURIException(String message)



Core API

32

Class ImsManager javax.microedition.ims

java.lang.Object javax.microedition.ims.ImsManager

public class ImsManager extends Object

This class provide methods for observing the registration state of IMS user identities and availability of IMS access networks. Moreover, the ImsManager acts as a factory for creation of ImsService types.

Example of how to set up a session

An instance of the ImsManager is fetched and a core service is created from the manager. The associated PUIs are read and can be used for for example session creation later.

ImsManager manager = ImsManager.getInstance("application/com.ericsson.testMIDlet"); service = (ImsCoreService) manager.createService(ImsService.SERVICE_TYPE_CORE, null); service.setListener(this); puis = manager.getUserIdentities();

See Also: ImsService


ImsManager() 3 Method Summary Page

ImsService createService(int serviceType, String accessNetworkName) Creates a new instance of an ImsService. 3

ImsNetwork[] getAccessNetworks() Returns a list of strings representing the available access networks. 3

static ImsManager getInstance(String applicationId)

Returns the singleton ImsManager. 3

String[] getUserIdentities() Returns an array of user identities that are associated with the user. 3

boolean isRegistered(String publicUserId) Returns the registration state of a user identity. 3

void setListener(ImsPlatformListener listener) Sets a listener for platform event notifications, replacing any previous

ImsPlatformListener. 3

Core API

33

Constructor Detail

ImsManager

public ImsManager()

Method Detail

isRegistered

public boolean isRegistered(String publicUserId)

Returns the registration state of a user identity. Parameters:

publicUserId - The user identity for which to query registration state. Returns:

Returns true if the identity is currently registred, false otherwise. See Also:

ImsService

setListener

public void setListener(ImsPlatformListener listener)

Sets a listener for platform event notifications, replacing any previous ImsPlatformListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:

listener - The listener to set, or null.

createService

public ImsService createService(int serviceType, String accessNetworkName) throws IllegalArgumentException, IOException

Creates a new instance of an ImsService. The service type determines which type of service that will be returned and the application id identifies the application. By creating an ImsService an application registers its services with the system. The platform will automatically register with the network when an ImsService is created if it is not already registered. Parameters:

serviceType - The type of service enabler to use. accessNetworkName - The access network preferred for this service, or null to let the system automatically select one.

Returns: A new object implementing the ImsService interface.

Core API

34

Throws: IllegalArgumentException - If one or more of the parameters are invalid. IOException - If an I/O error occurs.

See Also: ImsService

getInstance

public static ImsManager getInstance(String applicationId)

Returns the singleton ImsManager. Parameters:

applicationId - The application id identifying the application type. Returns:

The ImsManager. See Also:

ImsService

getAccessNetworks

public ImsNetwork[] getAccessNetworks()

Returns a list of strings representing the available access networks. The values of the strings can be any valid value of the access-type part of the P-Access-Network-Info header. Defined in RFC 3455 5.4. Returns:

An array of ImsNetwork objects representing the available access networks.

getUserIdentities

public String[] getUserIdentities()

Returns an array of user identities that are associated with the user. If the P-Associated-URI header is present in the register response, the list is populated with the entries from that header. If not, the user identity used for initial registration is returned at the first position.

These user identities may be used for service registration. The first user identity in the array is the default user identity. Returns:

An array of strings representing user identities.

Interface ImsNetwork javax.microedition.ims

public interface ImsNetwork

Core API

35

The ImsNetwork is a representation of an IMS access network. This object contains information about the type and name of a network.

Method Summary Page

String getNetworkName() Returns the name of the access network. 3

String getNetworkType() Returns the type of the access network. 3

Method Detail

getNetworkType

public String getNetworkType()

Returns the type of the access network. The value of the string can be any valid value of the access-type part of the P-Access-Network-Info header. Defined in RFC 3455 5.4. Returns:

The network type.

getNetworkName

public String getNetworkName()

Returns the name of the access network. Returns:

The network name.

Class IMSObjectExistsException javax.microedition.ims

java.lang.Object java.lang.Throwable java.lang.Exception javax.microedition.ims.IMSObjectExistsException


public class IMSObjectExistsException extends Exception

An IMSObjectExistsException is thrown by a factory method if an object already exists in the registry of the respective manager.

Core API

36


IMSObjectExistsException() Public constructor 3

IMSObjectExistsException(String message) Public constructor with message parameter 3

Constructor Detail

IMSObjectExistsException

public IMSObjectExistsException()

Public constructor

IMSObjectExistsException

public IMSObjectExistsException(String message)



Interface ImsPlatformListener javax.microedition.ims

public interface ImsPlatformListener

A listener type for receiving notifications of system events concerning resources such as registration state of user identities and the avaliability of access networks.

See Also: ImsManager

Method Summary Page

void processAccessNetworkChanged() This notification is used when an event regarding the available access networks

occured. 3

void processServiceDeregistered(ImsService service) This method is used to notify that the service has been deregistered. 3

void processServiceRegistered(ImsService service) This method is used to notify that the service has been registered. 3

Core API

37

void processServiceRegistrationFailed(ImsService service) This method is used to notify that the registration failed. 3

Method Detail

processAccessNetworkChanged

public void processAccessNetworkChanged()

This notification is used when an event regarding the available access networks occured. E.g. an access network has become avaliable or unavailable. See Also:

ImsManager.getAccessNetworks()

processServiceRegistered

public void processServiceRegistered(ImsService service)

This method is used to notify that the service has been registered. Parameters:

service - the service the event concerns

processServiceDeregistered

public void processServiceDeregistered(ImsService service)

This method is used to notify that the service has been deregistered. Parameters:


processServiceRegistrationFailed

public void processServiceRegistrationFailed(ImsService service)

This method is used to notify that the registration failed. Parameters:


Interface ImsService javax.microedition.ims

All Known Subinterfaces: ImsCoreService, PoCService, PresenceService, XDMService

Core API

38

public interface ImsService

An ImsService is a container for dialogs and media connections. By creating an ImsService an application registers its services with the system. The platform will automatically register with the network when an ImsService is created if it is not already registered.

Service Types

Several kinds of services exist and these can be generalized into two groups: Standardized Services and Core Services.

Standardized Services

These services include PoC, Presence and XDM and are standardized by standardization bodies. If ImsManager.createService is called with a serviceType corresponding to a service which is standardized and implemented by the system, an object implementing such a service will be returned.

Core Services

In order to facilitate rapid service creation this IMS API features core services. Core services are not standardized and are implemented by the application. When calling ImsManager.createService with ImsService.SERVICE_TYPE_CORE an object implementing ImsCoreService is returned. The service is created through using ImsCoreService to handle different kinds of transactions, dialogs and media connections.

Service Creation

An ImsService is created by calling ImsManager.createService.

Mandatory Parameters

The following parameters are mandatory to use:

Parameter Value Example

ServiceType The service type. Any SERVICE_TYPE_-constant

The ImsManager provides a method for only supplying the mandatory parameters.

Optional Parameters

The following parameters may be used but are optional:

Parameter Value Example

Core API

39

AccessNetwork

By indicating the AccessNetwork parameter the service is registered using the specified access network. If the parameter is omitted the default access network will be used. For a successful service registration the AccessNetwork-parameter must exist in the list retrieved from ImsManager.getAccessNetworks(). In addition, the user identity that is used must not already be registered using another access network.

The string value of the parameter is defined in RFC 3455 5.4.

"3GPP-UTRAN-FDD" or "IEEE-802.11b"

The ImsManager provides a method for only supplying the mandatory and the optional parameters.

Registering Services with PushRegisty

An ImsService is registrered for auto invocation by specifying a custom URL in the MIDlet Suite Java Application Descriptor (JAD) file. The general form of a service URL is:

ims:[{target}][{params}]

The {target} is a mandatory service identifier and application reference seperated by a "/" (slash), {target} = {ApplicationId/ServiceType} The optional service parameters are supplied as URL parameters on the form ";x=y". Valid ServiceType strings are: Core, XDM, Presence and PoC.

Examples:

MIDlet-Push-1: ims://com.ericsson.pocer/PoC;[email protected];AccessNetwork=IEEE-802.11b, example.picshare.SampleApp, *

or

MIDlet-Push-1: ims://com.atlanta.aliceapp/Core;, example.picshare.SampleApp, *

which will register the applicationId com.atlanta.aliceapp, and ServiceType Core using the the default preferred user identity and access network.

See Also: PushRegistry, ImsManager

Field Summary Page

int SERVICE_TYPE_CORE This service type specifies the core service. 3

int SERVICE_TYPE_POC This service type specifies the PoC service. 3

int SERVICE_TYPE_PRESENCE This service type specifies the presence service. 3

Core API

40

int SERVICE_TYPE_XDM This service type specifies the XDM service. 3

Method Summary Page

void close() Closes this service and terminates all resources and network activity associated

with it. 3

String getAccessNetworkName() Returns the access network name used for this service. 3

String getApplicationId() Returns a string representing the application identity for this service. 3

int getServiceType() Returns an integer identifying the type of this service. 3

Field Detail

SERVICE_TYPE_CORE

public static final int SERVICE_TYPE_CORE

This service type specifies the core service.

SERVICE_TYPE_PRESENCE

public static final int SERVICE_TYPE_PRESENCE

This service type specifies the presence service.

SERVICE_TYPE_XDM

public static final int SERVICE_TYPE_XDM

This service type specifies the XDM service.

SERVICE_TYPE_POC

public static final int SERVICE_TYPE_POC

This service type specifies the PoC service.

Core API

41

Method Detail

getServiceType

public int getServiceType()

Returns an integer identifying the type of this service. Returns:

the service type

getApplicationId

public String getApplicationId()

Returns a string representing the application identity for this service. Returns:

the application identitity

getAccessNetworkName

public String getAccessNetworkName()

Returns the access network name used for this service. Returns:

A string representing the used access network name. See Also:

ImsManager.getAccessNetworks

close

public void close() throws IOException

Closes this service and terminates all resources and network activity associated with it. Throws:

IOException - If an I/O error occurs.

Package javax.microedition.ims.core

This package collects classes and interfaces that enable an application to create IMS services.

See: Description

Core API

42


ImsCapabilities The ImsCapabilities is used to query a remote IMS endpoint about its capabilities.

3

ImsCapabilitiesListener This listener type is used to notify the application about responses to capability queries.

3

ImsCoreService The ImsCoreService enables creation of the essential elements of a service.

3

ImsCoreServiceListener A listener type for receiving notifications about remotly initiated requests and events regarding service registration state.

3

ImsMessageBody An ImsMessageBody can be added to service methods. 3

ImsMessageBodyPart An ImsMessageBodyPart is the building block of a ImsMessageBody.

3

ImsNotification An ImsNotification is used for receiving and sending notifications of the state of a subscribed resource.

3

ImsNotificationListener This listener type is used to notify the application about responses and status of sent notifications.

3

ImsPageMessage An ImsPageMessage is a representation of a SIP MESSAGE. 3

ImsPageMessageListener This listener type is used to notify the application about responses and status of sent messages.

3

ImsPublication The ImsPublication is used for publishing information to a remote party.

3

ImsPublicationListener This listener is used to notify the application of status and responses of requested publications.

3

ImsServiceMethod The ImsServiceMethod defines all common methods and attributes for IMS service method types.

3

ImsSession The ImsSession is a representation of media exchange between two IMS endpoints.

3

ImsSessionListener A listener type for receiving notification on session events. 3

ImsSubscription An ImsSubscription is used for subscribing to notifications from a remote party.

3

ImsSubscriptionListener This listener type is used to notify an application about notifications regarding the subscription dialog.

3

Package javax.microedition.ims.core Description

This package collects classes and interfaces that enable an application to create IMS services.

IMS User Identities

Core API

43

Within the IMS users are identify eachother using SIP & TEL URI:s. In this specification both are referred to as Public User Identities, PUIs.

Static Structure

Figure 1: Static structure of the package.

Since: IMS API pre-EDR

Interface ImsCapabilities javax.microedition.ims.core

All Superinterfaces: ImsServiceMethod

public interface ImsCapabilities extends ImsServiceMethod

The ImsCapabilities is used to query a remote IMS endpoint about its capabilities.

Capabilities are queried by sending the SIP OPTIONS request.

Example use of ImsCapabilities

public class SimpleQuery implements ImsCapabilitesListener{

Core API

44

public void checkSupport(ImsCoreService service){ ImsCapabilities caps; try{ caps = service.createCapabilities("sip:[email protected]"); caps.setListener(this); caps.queryCapabilities(); }catch(Exception e){ //handle Exceptions } } public void processCapabilitesReceived(ImsCapabilities caps){ try{ String[] methods = caps.getRemoteContentTypeCapabilities(); Vector supportedMedia = caps.getSupportedMediaTypes(); ... // Display supported media types on display ... // User selected media type "video" ... Vector attr = getAttributesForMediaType("video"); String videoAttr = attr.elementAt(index); ... //process this information }catch(Exception e){ //handle Exceptions } } //the class also implements the other methods of ImsCapabilitesListener . . }

See Also: ImsCoreService.createCapabilities(String, String)

Method Summary Page

Vector getAttributesForMediaType(String mediaType) Returns a vector with the attributes that are supported for the specified

mediaType. 3

String[] getRemoteContentTypeCapabilities() Returns a list of encodings for message bodies that the remote party is capable

of handling. 3

Vector getSupportedMediaTypes() Returns a vector with the media types in the OPTIONS response that the remote

endpoint supports. 3

void queryCapabilities() Sends a capabilities request to a remote party. 3

void setListener(ImsCapabilitiesListener listener) Sets a listener for this service, replacing any previous ImsCapabilitiesListener. 3

Core API

45

Method Detail

queryCapabilities

public void queryCapabilities() throws IllegalStateException

Sends a capabilities request to a remote party. Throws:

IllegalStateException - If the reference is in the PENDING state.

getRemoteContentTypeCapabilities

public String[] getRemoteContentTypeCapabilities() throws IllegalStateException

Returns a list of encodings for message bodies that the remote party is capable of handling. The items in the list are MIME types such as "image/jpeg", "text/html" and "audio/wave". Returns:

An array of content types. Throws:

IllegalStateException - If the capabilities method is not in the VALID state.

getSupportedMediaTypes

public Vector getSupportedMediaTypes() throws IllegalStateException

Returns a vector with the media types in the OPTIONS response that the remote endpoint supports. Returns:

A vector with supported media types. Throws:


getAttributesForMediaType

public Vector getAttributesForMediaType(String mediaType) throws IllegalStateException

Returns a vector with the attributes that are supported for the specified mediaType. Parameters:

mediaType - The mediatype for which the attributes will be returned. Returns:

A vector with supported attribute types. Throws:


Core API

46

setListener

public void setListener(ImsCapabilitiesListener listener)

Sets a listener for this service, replacing any previous ImsCapabilitiesListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Interface ImsCapabilitiesListener javax.microedition.ims.core

public interface ImsCapabilitiesListener

This listener type is used to notify the application about responses to capability queries.

See Also: ImsCapabilities.setListener(ImsCapabilitiesListener)

Method Summary Page

void processCapabilitesFailed(ImsCapabilities capabilites) This method is used to notify that an error occured during the query to the

remote party. 3

void processCapabilitesReceived(ImsCapabilities capabilites) This method is used to notify that a response was successfully received from the

remote party. 3

Method Detail

processCapabilitesReceived

public void processCapabilitesReceived(ImsCapabilities capabilites)

This method is used to notify that a response was successfully received from the remote party. Parameters:

capabilites - The capabilities object that triggered the event.

processCapabilitesFailed

public void processCapabilitesFailed(ImsCapabilities capabilites)

This method is used to notify that an error occured during the query to the remote party.

Core API

47

Parameters: capabilites - The capabilities object that triggered the event.

Interface ImsCoreService javax.microedition.ims.core

All Superinterfaces: ImsService

public interface ImsCoreService extends ImsService

The ImsCoreService enables creation of the essential elements of a service.

An ImsCoreService serves as a factory creating transactions, dialogs and media connections through the ImsServiceMethods.

In addition, by setting a listener the service can respond to incoming IMS methods.

See Also: ImsCoreServiceListener

Method Summary Page

ImsCapabilities createCapabilities(String preferredUserId, String remotePUI) Creates a new ImsCapabilities. 3

ImsPageMessage createPageMessage(String preferredUserId, String remotePUI) Creates a new ImsPageMessage. 3

ImsPublication createPublication(String preferredUserId, String remotePUI, String event)

Creates a new ImsPublication. 3

ImsSession createSession(String preferredUserId, String remotePUI, boolean csiEnabled)

Creates a new ImsSession. 3

ImsSubscription createSubscription(String preferredUserId, String remotePUI, String event)

Creates a new ImsSubscription. 3

boolean isServiceRegistered() Checks if the service has been registered or not. 3

void setListener(ImsCoreServiceListener listener) Sets a listener for this service, replacing any previous

ImsCoreServiceListener. 3

Core API

48

Method Detail

isServiceRegistered

public boolean isServiceRegistered()

Checks if the service has been registered or not. Returns:

Returns true if the service has been successfully registrered, false otherwise.

createPageMessage

public ImsPageMessage createPageMessage(String preferredUserId, String remotePUI) throws IllegalArgumentException, IllegalStateException

Creates a new ImsPageMessage. Parameters:

preferredUserId - The preferred identity to use, or null to let the system automatically select one. remotePUI - The address of remote endpoint.

Returns: A new paging message.

Throws: IllegalArgumentException - If the given remotePUI is invalid. IllegalStateException - If the current registration status does not allow this operation.

createPublication

public ImsPublication createPublication(String preferredUserId, String remotePUI, String event) throws IllegalArgumentException, IllegalStateException

Creates a new ImsPublication. Parameters:

preferredUserId - The preferred identity to use, or null to let the system automatically select one. remotePUI - The remote PUI of the target of this publication. event - The event class associated with this publication.

Returns: A new publication.


Core API

49

createSubscription

public ImsSubscription createSubscription(String preferredUserId, String remotePUI, String event) throws IllegalArgumentException, IllegalStateException

Creates a new ImsSubscription. Parameters:

preferredUserId - The preferred identity to use, or null to let the system automatically select one. remotePUI - The remote PUI of the resource to subscribe to. event - The event class associated with this publication.

Returns: A new subscription.


createCapabilities

public ImsCapabilities createCapabilities(String preferredUserId, String remotePUI) throws IllegalArgumentException, IllegalStateException

Creates a new ImsCapabilities. Parameters:

preferredUserId - The preferred identity to use, or null to let the system automatically select one. remotePUI - The address of remote endpoint.

Returns: A new capabilities request.


createSession

public ImsSession createSession(String preferredUserId, String remotePUI, boolean csiEnabled) throws IllegalArgumentException, IllegalStateException

Creates a new ImsSession. Parameters:

preferredUserId - the preferred identity to use, or null to let the system automatically select one remotePUI - The address of remote endpoint. May be null if there is an ongoing cs phone call and csiEnabled is true.

Core API

50

csiEnabled - Indicates if the created session should have csi capabilities. Returns:

a new session Throws:

IllegalArgumentException - if the given remotePUI is invalid IllegalStateException - if the current registration status does not allow this operation

setListener

public void setListener(ImsCoreServiceListener listener)

Sets a listener for this service, replacing any previous ImsCoreServiceListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Interface ImsCoreServiceListener javax.microedition.ims.core

public interface ImsCoreServiceListener

A listener type for receiving notifications about remotly initiated requests and events regarding service registration state.

See Also: ImsCoreService.setListener(ImsCoreServiceListener)

Method Summary Page

void processPageMessageReceived(ImsCoreService service, ImsPageMessage message) This method is used to notify that a message has been received. 3

void processSessionInvitation(ImsCoreService service, ImsSession session) This method is used to notify that a session invitation has been received from a

remote party. 3

Method Detail

processPageMessageReceived

public void processPageMessageReceived(ImsCoreService service, ImsPageMessage message)

This method is used to notify that a message has been received. Parameters:

service - The service the message regards.

Core API

51

message - A representation of the received message.

processSessionInvitation

public void processSessionInvitation(ImsCoreService service, ImsSession session)

This method is used to notify that a session invitation has been received from a remote party.

Within the scope of this method the implementing object should acknowledge the invitation by invoking either accept or reject on the ImsSession object. Parameters:

service - The service associated with this publication. session - The session.

See Also: ImsSession.accept(), ImsSession.reject(), ImsSession.redirect(String)

Interface ImsMessageBody javax.microedition.ims.core

public interface ImsMessageBody

An ImsMessageBody can be added to service methods. Each ImsMessageBody can contain a number of ImsMessageBodyPart.

An ImsMessageBodyPart can contain different kinds of data, e.g. text or a XML document.

See Also: ImsServiceMethod.openRequestBody(), ImsServiceMethod.openResponseBody()

Method Summary Page

ImsMessageBodyPart createBodyPart() Creates a new ImsMessageBodyPart and adds it to this

ImsMessageBody. 3

ImsMessageBodyPart[] getBodyParts() Returns all message body parts of the message body. 3

Method Detail

getBodyParts

public ImsMessageBodyPart[] getBodyParts()

Core API

52

Returns all message body parts of the message body. Returns:

All ImsMessageBodyPart of the message body.

createBodyPart

public ImsMessageBodyPart createBodyPart()

Creates a new ImsMessageBodyPart and adds it to this ImsMessageBody.

Interface ImsMessageBodyPart javax.microedition.ims.core

public interface ImsMessageBodyPart

An ImsMessageBodyPart is the building block of a ImsMessageBody. Each ImsMessageBody can contain a number of ImsMessageBodyParts.

An ImsMessageBodyPart can contain different kinds of data, e.g. text, an image or an audio clip.

Method Summary Page

String getCharset() Returns the charset of the message part if the type is text. 3

byte[] getContent() Returns the actual data of the message part. 3

int getLength() Returns the length of a message part. 3

String getType() Returns the type of the message part. 3

void setCharset(String charset) Sets the charset of a text message part. 3

void setContent(byte[] data) Sets the actual data of the message part. 3

void setType(String type) Sets the type of the message part. 3

Method Detail

getCharset

public String getCharset()

Core API

53

Returns the charset of the message part if the type is text. Returns:

The charset of an text message part. See Also:

setCharset

getLength

public int getLength()

Returns the length of a message part. Returns:

The length of a message part.

getType

public String getType()

Returns the type of the message part. Returns:

The type of the message part. See Also:

setType

setType

public void setType(String type)

Sets the type of the message part. Parameters:

type - The type of message part. See Also:

getType()

getContent

public byte[] getContent()

Returns the actual data of the message part. Returns:

The actual data of the message part. See Also:

setContent(byte[])

Core API

54

setCharset

public void setCharset(String charset)

Sets the charset of a text message part. Parameters:

charset - The charset of the message part. See Also:

getCharset()

setContent

public void setContent(byte[] data)

Sets the actual data of the message part. Parameters:

data - The actual data of the message part. See Also:

getContent()

Interface ImsNotification javax.microedition.ims.core


public interface ImsNotification extends ImsServiceMethod

An ImsNotification is used for receiving and sending notifications of the state of a subscribed resource.

See Also: ImsSubscriptionListener.processSubscriptionEvent(ImsSubscription, ImsNotification), ImsSessionListener.processSessionTransferNotification(ImsSession, ImsNotification)

Method Summary Page

void send() Sends the notification. 3

void setListener(ImsNotificationListener listener) Sets a listener for this ImsNotification. 3

Core API

55

Method Detail

send

public void send() throws IllegalStateException

Sends the notification. Throws:

IllegalStateException - If this ImsNotification is not associated with a "server-ImsSubscription".

setListener

public void setListener(ImsNotificationListener listener)

Sets a listener for this ImsNotification. Parameters:

listener - The listener to set.

Interface ImsNotificationListener javax.microedition.ims.core

public interface ImsNotificationListener

This listener type is used to notify the application about responses and status of sent notifications.

See Also: ImsNotification.setListener(ImsNotificationListener)

Method Summary Page

void processNotificationDelivered(ImsNotification notification) This method is used to notify that the notification was successfully delivered. 3

void processNotificationDeliveryFailed(ImsNotification notification) This method is used to notify that the notification was not successfully delivered. 3

Method Detail

processNotificationDelivered

public void processNotificationDelivered(ImsNotification notification)

This method is used to notify that the notification was successfully delivered.

Core API

56

Parameters: notification - The notification this event concerns.

processNotificationDeliveryFailed

public void processNotificationDeliveryFailed(ImsNotification notification)

This method is used to notify that the notification was not successfully delivered. Parameters:

notification - The notification this event concerns.

Interface ImsPageMessage javax.microedition.ims.core


public interface ImsPageMessage extends ImsServiceMethod

An ImsPageMessage is a representation of a SIP MESSAGE.

Common usage of the ImsPageMessage is simple instant messages or exchange of small amounts of data.

Example usage of ImsPageMessage

public class IconMessager implements ImsPageMessageListener{ public void sendIcon(ImsCoreService service, byte[] icon){ ImsPageMessage page; try{ page = service.createPageMessage(null, "sip:[email protected]"); page.setListener(this); page.addRequestHeader("IconIncluded","yes"); page.send(icon, "image/gif"); }catch(Exception e){ //handle Exceptions } } public void processPageMessageSent(ImsPageMessage page){ try{ String hasIcon = page.getResponseHeader("IconIncluded"); if(hasIcon.equals("yes")) { //process this information icon = message.getContent(); } //process this information }catch(Exception e){ //handle Exceptions } }

Core API

57

//the class also implements the other method of ImsPageMessageListener . . }

See Also: ImsCoreService.createPageMessage(String, String), ImsCoreServiceListener.processPageMessageReceived(ImsCoreService,ImsPageMessage)

Method Summary Page

byte[] getContent() Extracts the contents from the first body part of this ImsPageMessage. 3

String getContentType() Returns the value of the Content-Type header of this ImsPageMessage. 3

void send(byte[] content, String contentType) Sends the message. 3

void setListener(ImsPageMessageListener listener) Sets a listener for this service, replacing any previous ImsPageMessageListener. 3

Method Detail

send

public void send(byte[] content, String contentType) throws IllegalStateException

Sends the message. Parameters:

content - A byte array containing the content to send in this message. contentType - A string containing the MIME type of the content to send.

Throws: IllegalStateException - If the message is in the PENDING state.

setListener

public void setListener(ImsPageMessageListener listener)

Sets a listener for this service, replacing any previous ImsPageMessageListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Core API

58

getContent

public byte[] getContent()

Extracts the contents from the first body part of this ImsPageMessage. Returns:

The array containing the content.

getContentType

public String getContentType()

Returns the value of the Content-Type header of this ImsPageMessage. Returns:

The content MIME type.

Interface ImsPageMessageListener javax.microedition.ims.core

public interface ImsPageMessageListener

This listener type is used to notify the application about responses and status of sent messages.

See Also: ImsPageMessage.setListener(ImsPageMessageListener)

Method Summary Page

void processMessageDelivered(ImsPageMessage message) This method is used to notify that the message was successfully delivered. 3

void processMessageDeliveryFailed(ImsPageMessage message) This method is used to notify that the message was not successfully delivered. 3

Method Detail

processMessageDelivered

public void processMessageDelivered(ImsPageMessage message)

This method is used to notify that the message was successfully delivered. Parameters:

message - The message this event concerns.

Core API

59

processMessageDeliveryFailed

public void processMessageDeliveryFailed(ImsPageMessage message)

This method is used to notify that the message was not successfully delivered. Parameters:

message - The message this event concerns.

Interface ImsPublication javax.microedition.ims.core


public interface ImsPublication extends ImsServiceMethod

The ImsPublication is used for publishing information to a remote party.

The ImsPublication uses the SIP PUBLISH method for publishing event information. The published event will be refreshed periodically until unpublish is called. Updates of the published event may be achieved by modifying the properies of the ImsPublication and then calling publish again.

Example usage of ImsPublication

public class MyPublisher implements ImsPublicationListener{ public void myPublishEvent(ImsCoreService service, byte[] event){ ImsPublication pub; ImsMessageBodyPart part; try{ pub = service.createPublication("sip:[email protected]"); pub.setListener(this); part = pub.openRequestBody.createBodyPart(); part.setContent(event); pub.publish(); // start the publication }catch(Exception e){ //handle Exceptions } } public void processPublishDelivered(ImsPublication pub){ // check additional information if needed } //the class also implements the other methods of ImsCapabilitesListener . . }

See Also: ImsCoreService.createPublication(String, String, String)

Core API

60

Method Summary Page

String getEvent() Returns the event corresponding to this publication. 3

void publish() Sends a publication request to the remote party. 3

void setEvent(String event) Sets the event associated with this publication. 3

void setListener(ImsPublicationListener listener) Sets a listener for this service, replacing any previous ImsPublicationListener. 3

void unpublish() A call to this method will trigger an expiration of the previous publication. 3

Method Detail

publish

public void publish() throws IllegalStateException

Sends a publication request to the remote party. I.e. a request carrying information about a local event or status is sent. Throws:

IllegalStateException - If the publication is in the PENDING state.

unpublish

public void unpublish() throws IllegalStateException

A call to this method will trigger an expiration of the previous publication. Throws:

IllegalStateException - If the publication is not in the VALID state.

setListener

public void setListener(ImsPublicationListener listener)

Sets a listener for this service, replacing any previous ImsPublicationListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Core API

61

setEvent

public void setEvent(String event) throws IllegalStateException

Sets the event associated with this publication. This event must be set before the publication request is sent. Parameters:

event - The event to publish. Throws:

IllegalStateException - If the publication is in the PENDING state. See Also:

getEvent

getEvent

public String getEvent()

Returns the event corresponding to this publication. Returns:

The event this publication is about. See Also:

setEvent

Interface ImsPublicationListener javax.microedition.ims.core

public interface ImsPublicationListener

This listener is used to notify the application of status and responses of requested publications.

See Also: ImsPublication.setListener(ImsPublicationListener)

Method Summary Page

void processPublishDelivered(ImsPublication publication) This method is used to notify that a publication request was successfully

delivered. 3

void processPublishDeliveryFailed(ImsPublication publication) This method is used to notify that a publication request was not successfully

delivered. 3

Core API

62

Method Detail

processPublishDelivered

public void processPublishDelivered(ImsPublication publication)

This method is used to notify that a publication request was successfully delivered. Parameters:

publication - The concerned publication.

processPublishDeliveryFailed

public void processPublishDeliveryFailed(ImsPublication publication)

This method is used to notify that a publication request was not successfully delivered. Parameters:

publication - The concerned publication.

Interface ImsServiceMethod javax.microedition.ims.core

All Known Subinterfaces: ImsCapabilities, ImsNotification, ImsPageMessage, ImsPublication, ImsSession, ImsSubscription

public interface ImsServiceMethod

The ImsServiceMethod defines all common methods and attributes for IMS service method types.

Service Method Types

Subtypes of an ImsServiceMethod can be created by using factory methods in the ImsCoreService. To learn more about using the different service methods please refer to the specialised types such as ImsCapabilities.

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 of the SIP methods, such as manipulating headers and body.

Service Method Transactions

The simplest form of communication in the IMS consists of two SIP messages, an inital request sent to a remote party and then an answer message or response. This interaction is commonly known as a transaction. Figure 1, shows an example transaction.

Core API

63

Figure 1: A simple transaction. The transaction model is asynchronous in its nature and this is reflected here by the usage of listeners to trace events. By using the setListener method, in each respective service method subinterface, a listener is attached to a service method. This listener will be notified with responses to the sent requests within a transaction.

The ImsServiceMethod subinterfaces encapsulate transactions. Some interface methods trigger transactions and some interface methods are used to fetch the response data.

Service Method Operation

The transaction life cycle within the ImsServiceMethod can be divided into three internal states: INVALID, PENDING and VALID.

Figure 2: The transaction states within a service method. Figure 2. show an illustration of the internal transaction states.

Invalid

A transaction resides in the INVALID state when it the service method has just been created a no request at all has been sent. The transaction may also reside in this state after a network error/timeout has occurred. However, from a transaction perspective a transaction with a response error code of e.g 404 is not invalid.

In this state the body and the headers of the request may be modified. The transaction state of service method transits to PENDING after a request triggering interface method is called.

Core API

64

In the INVALID state no response data is available.

Pending

The PENDING state is a temporary state in which the transaction resides during the interval between the sending of the request and the time when the response is received. The transaction state transits to VALID when a response is received from the remote party. The response may report any status code.

If a network error occurs or no response is received within a timeout interval the transaction transits to the INVALID state.

Valid

In the VALID state the application may get information about the result of the request by checking header values and body contents. The subinterfaces also provide interface methods for easier access to relevant information.

The transaction state may transit to PENDING pending if a request triggering interface method is called.

Service Method Properties

The ImsServiceMethod interface provides common functionality of adding and reading user defined headers as well as writing and reading the body of the methods.

An example of usage of the properties is shown in ImsPageMessage.

See Also: ImsCapabilities, ImsPageMessage, ImsNotification, ImsPublication, ImsSession, ImsSubscription

Method Summary Page

void addRequestHeader(String key, String value) Adds a header value, either on a new header or just appending a new value

to an already existing header. 3

void addResponseHeader(String key, String value) Adds a header value, either on a new header or just appending a new value


String getRemotePUI() Returns the public user identity of the remote party of this service method. 3

String getRequestHeader(String key) Returns the value of the header. 3

int getResponseCode() Returns the status code of the response. 3

String getResponseHeader(String key) Returns the value of the header. 3

Core API

65

String getResponsePhrase() Returns the reason phrase of the response. 3

ImsCoreService getService() Returns the ImsCoreService this service method is associated with. 3

boolean isOriginated() Returns whether or not this transaction was orignated by the local party. 3

ImsMessageBody openRequestBody() Returns the ImsMessageBody of this transaction. 3

ImsMessageBody openResponseBody() Returns the ImsMessageBody of the response. 3

void removeRequestHeader(String key) Removes the specified request header. 3

void removeResponseHeader(String key) Removes the specified response header. 3

void setRequestHeader(String key, String value) Adds a header value, either on a new header or just appending a new value


void setResponseHeader(String key, String value) Adds a header value, either on a new header or just appending a new value


Method Detail

removeRequestHeader

public void removeRequestHeader(String key) throws IllegalStateException, IllegalArgumentException

Removes the specified request header. If several headers with the same name exist the topmost will be removed. Parameters:

key - The key of the header to remove. Throws:

IllegalStateException - If the transaction is in the PENDING state. IllegalArgumentException - If the header cannot be removed.

addRequestHeader

public void addRequestHeader(String key, String value) throws IllegalArgumentException, IllegalStateException

Adds a header value, either on a new header or just appending a new value to an already existing header.

Core API

66

Parameters: key - The header name. value - The header value.

Throws: IllegalStateException - If the transaction is in the PENDING state. IllegalArgumentException - If the header cannot be added.

setRequestHeader

public void setRequestHeader(String key, String value) throws IllegalArgumentException, IllegalStateException

Adds a header value, either on a new header or just appending a new value to an already existing header. Parameters:

key - The header name. value - The header value.


getRequestHeader

public String getRequestHeader(String key) throws IllegalArgumentException, IllegalStateException

Returns the value of the header. Parameters:

key - The name of the header to get. Returns:

The value of the header. Throws:

IllegalStateException - If the transaction is in the PENDING state. IllegalArgumentException - If the header does not exist or is not accessible.

openRequestBody

public ImsMessageBody openRequestBody() throws IllegalStateException

Returns the ImsMessageBody of this transaction. Returns:

The ImsMessageBody of this service method. Throws:

IllegalStateException - If the transaction is in the PENDING state.

Core API

67

removeResponseHeader

public void removeResponseHeader(String key) throws IllegalStateException, IllegalArgumentException

Removes the specified response header. If several headers with the same name exist the topmost will be removed. Parameters:

key - The key of the header to remove. Throws:

IllegalStateException - If the transaction is in the PENDING state. IllegalArgumentException - If the header cannot be removed.

getResponseHeader

public String getResponseHeader(String key) throws IllegalArgumentException, IllegalStateException

Returns the value of the header. Parameters:

key - The name of the header. Returns:

The value of the response header. Throws:

IllegalStateException - If the transaction is not in the VALID state. IllegalArgumentException - If the header does not exist or is not accessible.

addResponseHeader

public void addResponseHeader(String key, String value) throws IllegalArgumentException, IllegalStateException




Core API

68

setResponseHeader

public void setResponseHeader(String key, String value) throws IllegalArgumentException, IllegalStateException




openResponseBody

public ImsMessageBody openResponseBody() throws IllegalStateException

Returns the ImsMessageBody of the response. Returns:

The ImsMessageBody. Throws:

IllegalStateException - If the transaction is not in the VALID state.

getResponseCode

public int getResponseCode() throws IllegalStateException

Returns the status code of the response. Returns:

The response code. Throws:

IllegalStateException - If this transaction is not in the VALID state.

getResponsePhrase

public String getResponsePhrase() throws IllegalStateException

Returns the reason phrase of the response. Returns:

The reason phrase. Throws:

IllegalStateException - If this transaction is not in the VALID state.

Core API

69

getRemotePUI

public String getRemotePUI() throws IllegalStateException

Returns the public user identity of the remote party of this service method. Returns:

The remote PUI. Throws:

IllegalStateException - If the transaction is in the PENDING state.

isOriginated

public boolean isOriginated()

Returns whether or not this transaction was orignated by the local party. Returns:

Returns true if the transaction was created locally, false otherwise.

getService

public ImsCoreService getService()

Returns the ImsCoreService this service method is associated with. Returns:

The ImsCoreService associated with this service method.

Interface ImsSession javax.microedition.ims.core


public interface ImsSession extends ImsServiceMethod

The ImsSession is a representation of media exchange between two IMS endpoints. A ImsSession can be created either locally through calling ImsCoreService.createSession, or by a remote user, in which case the session will be passed as a parameter to ImsCoreServiceListener.processSessionInvitation.

The ImsSession uses the SIP methods INVITE and UPDATE and is automatically refreshed. An ImsSession is able to carry media of the type ImsMedia. ImsMedia objects represent a media connection and not the media/data itself.

Core API

70

The IMS media connections are negotiated trough 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

Figure 1: The session states. An ImsSession has six states: INITIATED, PROCEEDING, ESTABLISHED, UPDATE_PENDING, NEGOTIATING and TERMINATED.

The state transitions are described below. The purpose of the life-cycle states is to ensure that the handling of the session is kept synchronized between the local party and the remote party. The ImsSession life cycle will also determine 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 & Termination. The scenarios are explained from two perspectives: the Mobile Originated-perspective represents the initiator of an action. The counterpart is the Mobile Terminated-perspective representing the other side of the session which will receive events of the initiators actions. In general terms an action at one side will generate an call to a listener method on the other side of the session.

Mobile Originated Session Establishment

This section describes how an ImsSession is created, initialized and finally started.

Initiated

Core API

71

When an ImsSession is created, through a call to ImsCoreService.createSession, it will enter INITIATED. After creation, media can be added to the session using the method addMedia.

An ImsSession transits to:

• PROCEEDING when start is called.

Proceeding

When start is called the ImsSession enters PROCEEDING. Once this state is entered the communication with the remote party starts and a session invitation with the first media offer is sent.

Within PROCEEDING the listener event processSessionAlerting may be received.


• ESTABLISHED if the remote party accepts the session invitation. If the remote party accepts the invitation the listener method processSessionStarted will be called.

• TERMINATED if the remote party rejects the session invitation. If the remote party rejects the invitation the listener method processSessionStartFailed will be called.

Mobile Terminated Session Establishment

This section describes how an ImsSession invitation is received and the actions needed to respond to an invitation.

Initiated

INITIATED is irrelevant to a receiving terminal because as soon as it is notified of an invitation the session is already in PROCEEDING.

Proceeding

When a session invitation reaches the terminating application it resides in PRECEEDING.


• ESTABLISHED if accept is called. • TERMINATED if reject is called.

Mobile Originated Session Renegotiation

Established

An ImsSession enters ESTABLISHED when an invitation has been accepted by the remote party or a new session offer has been either accepted or rejected. If the session offer was accepted the session is updated according to the new offer. If the offer is rejected the session keeps its old state.

Core API

72


• UPDATE_PENDING when media has been added, removed or modified by the application. • NEGOTIATING when the hold or resume methods have been called. • TERMINATED if the close-method is called.

Update Pending

An ImsSession enters UPDATE_PENDING when either of the methods addMedia, removeMedia are called or a media object associated with the session is modified.


• NEGOTIATING when the update method is called. • ESTABLISHED if the cancelUpdate method is called thus canceling any modifications.

Negotiating

An ImsSession assumes NEGOTIATING through a call to update, hold or resume.

An ImsSession transits back to ESTABLISHED when the listener method:

• processSessionUpdated is called, meaning that the remote party accepted the new session offer.

• processSessionUpdateFailed is called, but here meaning that the remote party rejected the update and the session thus keeps its old settings.

• processSessionHold is called, meaning that the session is now on hold. • processSessionHoldFailed is called, meaning that the request to hold the session failed. • processSessionResume is called, meaning that the session is now resumed. • processSessionResumeFailed is called, meaning that the request to resume the session

failed.

Terminated

TERMINATED is the last state in the life cycle of an ImsSession.

Mobile Terminated Session Renegotiation

Established

When a session invitation is accepted though calling accept the ImsSession enters ESTABLISHED.


• NEGOTIATING when the ImsSessionListener is notified of a session update event through a call to its processSessionUpdateRequest-method. An update of the session includes modifications and removal of current media as well as adding new media.

• TERMINATED if when the listener method processSessionTerminated is called due to remote party termination of the session.

Core API

73

Negotiating

If the other party has offered changes to the ImsSession the state will change to NEGOTIATING.


• ESTABLISHED if the accept-method of the ImsSession is called, thus the media offer is accepted.

• ESTABLISHED if the reject-method is called but in this case the session will keep its original settings.

Terminated

TERMINATED is the last state in the life cycle of an ImsSession.

See Also: ImsMedia, ImsCoreService.createSession(String, String, boolean)

Field Summary Page

int CSI_STATE_CS_CONNECTED This state specifies that this is a csi enabled session with a connected cs phone

call. 3

int CSI_STATE_CS_DISCONNECTED This state specifies that this is a csi enabled session with no connected cs phone

call. 3

int CSI_STATE_NOT_ENABLED This state specifies that this is not a csi enabled session. 3

int STATE_ESTABLISHED This state specifies that the session is established. 3

int STATE_INITIATED This state specifies that the session is not started. 3

int STATE_NEGOTIATING This state specifies that the session is negotiating. 3

int STATE_PROCEEDING This state specifies that the session has been started. 3

int STATE_TERMINATED This state specifies that the session has been terminated. 3

int STATE_UPDATE_PENDING This state specifies that the session is pending an update. 3

Method Summary Page

void accept() By calling this method the invitation for the session is accepted. 3

Core API

74

void cancelUpdate() Removes any session modifications that have not yet been

synchronized with the remote party. 3

ImsBasicReliableMedia createBasicReliableMedia(String contentType, int direction) Creates an ImsBasicReliableMedia object and adds it to this

session. 3

ImsBasicUnreliableMedia createBasicUnreliableMedia(String contentType, int direction) Creates an ImsBasicUnreliableMedia object and adds it to this

session. 3

ImsFramedMedia createFramedMedia(String[] acceptedContentTypes, int direction)

Creates an ImsFramedMedia object and adds it to this session. 3

ImsStreamMedia createStreamMedia(String locator) Creates an ImsStreamMedia object from a locator and adds it to

this session. 3

int getCsiState() Returns the current csi state of this session. 3

Vector getMedia() Returns the media objects which are a part of this session. 3

ImsQosProfile getQoS() Returns the current QoS (Quality of Service) used for this session. 3

String getRemoteSipUri() Returns the sip uri of the remote party. 3

String getRemoteTelUri() Returns the tel uri of the remote party. 3

int getState() Returns the current state of this session. 3

void hold() Hold session. 3

boolean isCsVideoCapable() Indicates if this sessions participants both support cs video calls. 3

boolean isCsVoiceCapable() Indicates if this sessions participants both support cs voice calls. 3

boolean isWithheldCallerId() Returns true if the local user identity is withheld. 3

void redirect(String publicUserId) Redirects this session invitation to another PUI. 3

void reject() Rejects this session. 3

void removeMedia(ImsMedia media) Remove media from this session. 3

void resume() Resume session. 3

Core API

75

void setListener(ImsSessionListener listener) Sets a listener for events and state change notifications, replacing

any previous ImsSessionListener. 3

void setWithheldCallerId(boolean withhold) Sets whether or not to withhold the local user identity. 3

void start() Start session. 3

void terminate() Terminate or cancel session. 3

void transfer(String publicUserId) Transfers an ongoing session to another PUI. 3

void update() Synchronizes the session modifications with the remote party that

an application has done. 3

Field Detail

STATE_INITIATED

public static final int STATE_INITIATED

This state specifies that the session is not started.

STATE_PROCEEDING

public static final int STATE_PROCEEDING

This state specifies that the session has been started.

STATE_NEGOTIATING

public static final int STATE_NEGOTIATING

This state specifies that the session is negotiating.

STATE_ESTABLISHED

public static final int STATE_ESTABLISHED

This state specifies that the session is established.

Core API

76

STATE_TERMINATED

public static final int STATE_TERMINATED

This state specifies that the session has been terminated.

STATE_UPDATE_PENDING

public static final int STATE_UPDATE_PENDING

This state specifies that the session is pending an update.

CSI_STATE_NOT_ENABLED

public static final int CSI_STATE_NOT_ENABLED

This state specifies that this is not a csi enabled session.

CSI_STATE_CS_DISCONNECTED

public static final int CSI_STATE_CS_DISCONNECTED

This state specifies that this is a csi enabled session with no connected cs phone call.

CSI_STATE_CS_CONNECTED

public static final int CSI_STATE_CS_CONNECTED

This state specifies that this is a csi enabled session with a connected cs phone call.

Method Detail

getCsiState

public int getCsiState()

Returns the current csi state of this session. Returns:

The csi state of this session.

Core API

77

getRemoteTelUri

public String getRemoteTelUri() throws IllegalStateException

Returns the tel uri of the remote party. Returns:

The remote party tel uri. Throws:

IllegalStateException - If the csi state is CSI_STATE_NOT_ENABLED.

getRemoteSipUri

public String getRemoteSipUri() throws IllegalStateException

Returns the sip uri of the remote party. Returns:

The remote party sip uri. Throws:


isCsVoiceCapable

public boolean isCsVoiceCapable() throws IllegalStateException

Indicates if this sessions participants both support cs voice calls. Returns:

Returns true if both participants support cs voice calls, false otherwise. Throws:


isCsVideoCapable

public boolean isCsVideoCapable() throws IllegalStateException

Indicates if this sessions participants both support cs video calls. Returns:

Returns true if both participants support cs video calls, false otherwise. Throws:


setListener

public void setListener(ImsSessionListener listener)

Core API

78

Sets a listener for events and state change notifications, replacing any previous ImsSessionListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


update

public void update() throws IllegalStateException

Synchronizes the session modifications with the remote party that an application has done. Modifications include adding of media, removal of media, and change of existing media (e.g. directionality). None of these takes effect until this method is called Throws:

IllegalStateException - If the session is not in the UPDATE_PENDING state.

cancelUpdate

public void cancelUpdate() throws IllegalStateException

Removes any session modifications that have not yet been synchronized with the remote party. Modifications include adding of media, removal of media, and change of existing media (e.g. directionality). Throws:

IllegalStateException - If the session is not in the UPDATE_PENDING state.

isWithheldCallerId

public boolean isWithheldCallerId()

Returns true if the local user identity is withheld. Returns:

Returns true if the user identity is withheld, false otherwise.

setWithheldCallerId

public void setWithheldCallerId(boolean withhold)

Sets whether or not to withhold the local user identity. Parameters:

withhold - A boolean with the value true if the local user identity should be presented to the remote, false otherwise.

Core API

79

start

public void start() throws IllegalStateException

Start session. When this method is called the remote party is invited to the session. Throws:

IllegalStateException - If the session is not in the INITIATED state.

terminate

public void terminate()

Terminate or cancel session. A session that has been started should always be terminated using this method. By calling this function a negotiated session is terminated.

hold

public void hold() throws IllegalStateException

Hold session. All media flows in the session are put on hold. Resources for the session are still reserved. The local device stops sending data on a media, and Hold message is sent to the remote to inform it that the session is on Hold. Throws:

IllegalStateException - If the session is not in the ESTABLISHED state.

resume

public void resume() throws IllegalStateException

Resume session. If this session has been put on hold on the local device, then a call to this method resumes the session. A Resume message is sent to the remote to inform that sending data on the media is continued. Then the local device resumes sending data. Throws:


getState

public int getState()

Returns the current state of this session. Returns:

The current state of this session.

Core API

80

createBasicUnreliableMedia

public ImsBasicUnreliableMedia createBasicUnreliableMedia(String contentType, int direction) throws IllegalStateException, IllegalArgumentException, IOException

Creates an ImsBasicUnreliableMedia object and adds it to this session.

Calling this method will transit the session's state to UPDATE_PENDING to indicate that session object does not reflect the negotiated session. If the session has not yet been established, start should be called to start the session. If the session has been established, update should be called to renegotiate the session.

Pending updates may be cancelled by calling cancelUpdate.

The contentType is the MIME Type of the data transferred in this media. The MIME Type for ImsBasicUnreliableMedia must be a subclass of "application", e.g. "application/xml".

The direction parameter describes in which direction this media is flowing. It can have one of the following values: DIRECTION_INACTIVE, DIRECTION_RECEIVE, DIRECTION_SEND or DIRECTION_SEND_RECEIVE.

Parameters: contentType - The content type of the media. direction - The direction of the media.

Throws: IllegalStateException - If the session is not in ESTABLISHED, INITIATED or UPDATE_PENDING states. IllegalArgumentException - If the contentType parameter is not a subclass of "application" or if the direction parameter is not one of the above. IOException - Can be thrown as a result of a failing network read/write operation

createBasicReliableMedia

public ImsBasicReliableMedia createBasicReliableMedia(String contentType, int direction) throws IllegalStateException, IllegalArgumentException, IOException

Creates an ImsBasicReliableMedia object and adds it to this session.



Core API

81

The contentType is the MIME Type of the data transferred in this media. The MIME Type for ImsBasicUnreliableMedia must be a subclass of "application", e.g. "application/xml".

The direction parameter describes in which direction this media is flowing. It can have one of the following values: DIRECTION_INACTIVE, DIRECTION_RECEIVE, DIRECTION_SEND or DIRECTION_SEND_RECEIVE.

Parameters: contentType - The content type of the media. direction - The direction of the media.

Throws: IllegalStateException - If the session is not in ESTABLISHED, INITIATED or UPDATE_PENDING states. IllegalArgumentException - If the contentType parameter is not a subclass of "application" or if the direction parameter is not one of the above.

createStreamMedia

public ImsStreamMedia createStreamMedia(String locator) throws IllegalStateException, IllegalArgumentException, IOException

Creates an ImsStreamMedia object from a locator and adds it to this session. Examples of different locators: capture://audio capture://video file:///tmp/abc.mp3



Parameters: locator - The media identified by a locator.

Throws: IllegalStateException - If the session is not in ESTABLISHED, INITIATED or UPDATE_PENDING states. IllegalArgumentException - If the contentType parameter is not a subclass of "application" or if the direction parameter is not one of the above.

createFramedMedia

public ImsFramedMedia createFramedMedia(String[] acceptedContentTypes, int direction) throws IllegalStateException, IllegalArgumentException, IOException

Core API

82

Creates an ImsFramedMedia object and adds it to this session.



The acceptedContentTypes is an array of MIME types of the data accepted in this media.

Parameters: acceptedContentTypes - An array of content types accepted in this media. direction - The direction of the media.

Throws: IllegalStateException - If the session is not in ESTABLISHED, INITIATED or UPDATE_PENDING states. IllegalArgumentException - If one or more of the parameters are not valid.

removeMedia

public void removeMedia(ImsMedia media) throws IllegalArgumentException, IllegalStateException

Remove media from this session.

Calling this method will transit the session's state to UPDATE_PENDING. When the application has made all the modifications it wants to the session start should be called to start the session. If the session is already established update should be called.

Pending updates may be cancelled by calling cancelUpdate. Parameters:

media - The media to remove from the session. Throws:

IllegalArgumentException - If the media is not already a part of the session. IllegalStateException - If the session is not in ESTABLISHED, INITIATED or UPDATE_PENDING states.

getMedia

public Vector getMedia()

Returns the media objects which are a part of this session. Returns:

An vector of one or more ImsMedia or null.

Core API

83

accept

public void accept() throws IllegalStateException

By calling this method the invitation for the session is accepted. Throws:

IllegalStateException - If the session is not in PROCEEDING or NEGOTIATING states.

redirect

public void redirect(String publicUserId) throws IllegalStateException

Redirects this session invitation to another PUI. Parameters:

publicUserId - A PUI to redirect the session to. Throws:


transfer

public void transfer(String publicUserId) throws IllegalStateException

Transfers an ongoing session to another PUI. Parameters:

publicUserId - A PUI to transfer the session to. Throws:


reject

public void reject() throws IllegalStateException

Rejects this session. A session may be reject if the invitation is received and found unacceptable to the application or if the session is update in such a way that it is no longer wanted by the application. Throws:


getQoS

public ImsQosProfile getQoS()

Core API

84

Returns the current QoS (Quality of Service) used for this session. The result is a composition of the QoS values for all medias of the session. The returned profile represents the combined Quality of Service for all media in this session. Returns:

The current QoS for this session.

Interface ImsSessionListener javax.microedition.ims.core

public interface ImsSessionListener

A listener type for receiving notification on session events. When an event is generated for an ImsSession the application is notified by having one of the methods called on the ImsSessionListener.

See Also: ImsSession.setListener(ImsSessionListener)

Method Summary Page

void processCsiCsCallConnected(ImsSession session) This method is used to notify that a cs phone call has been connected. 3

void processCsiCsCallDisconnected(ImsSession session) This method is used to notify that a cs phone call has been disconnected. 3

void processSessionAlerting(ImsSession session) This notification is used to notify that the remote parties terminal is alerting the

user of this session. 3

void processSessionHold(ImsSession session) This notification is used to notify that the session has been put on hold. 3

void processSessionHoldFailed(ImsSession session) This notification is used to notify that the session could not be put on hold. 3

void processSessionResumed(ImsSession session) This notification is used to notify that the session has been resumed. 3

void processSessionResumeFailed(ImsSession session) This notification is used to notify that the session could not be resumed. 3

void processSessionStarted(ImsSession session) This notification is used to notify that the session is now established. 3

void processSessionStartFailed(ImsSession session) This notification is used to notify that the session could not be started. 3

void processSessionTerminated(ImsSession session) This method is used to notify an application that the remote party terminated the

session or the registration state changed in such a way that the session could no longer stay etablished.

3

Core API

85

void processSessionTransferFailed(ImsSession session) This method is used to notify that a session transfer failed. 3

void processSessionTransferNotification(ImsSession session, ImsNotification notify)

This method is used to notify that a notification message regarding a session transfer has been received.

3

void processSessionTransferred(ImsSession session) This method is used to notify that a session has been successfully transferred. 3

void processSessionTransferRequest(ImsSession session, String transferTo) This method is used to notify that the remote party has requested that the session

should be transferred to a new location. 3

void processSessionUpdateAccepted(ImsSession session) This notification is used to notify that the remote party accepted the session

update request that was previously sent. 3

void processSessionUpdateFailed(ImsSession session) This notification is used to notify that the remote party rejected the session

update request that was previously sent. 3

void processSessionUpdateRequest(ImsSession session) This notification is used to notify that the remote party requests an update of the

sessions settings. 3

Method Detail

processSessionTerminated

public void processSessionTerminated(ImsSession session)

This method is used to notify an application that the remote party terminated the session or the registration state changed in such a way that the session could no longer stay etablished. Parameters:

session - The session that generated the event.

processSessionUpdateRequest

public void processSessionUpdateRequest(ImsSession session)

This notification is used to notify that the remote party requests an update of the sessions settings. Parameters:


processSessionUpdateAccepted

public void processSessionUpdateAccepted(ImsSession session)

Core API

86

This notification is used to notify that the remote party accepted the session update request that was previously sent. Parameters:


processSessionUpdateFailed

public void processSessionUpdateFailed(ImsSession session)

This notification is used to notify that the remote party rejected the session update request that was previously sent. Parameters:


processSessionAlerting

public void processSessionAlerting(ImsSession session)

This notification is used to notify that the remote parties terminal is alerting the user of this session. Parameters:


processSessionStarted

public void processSessionStarted(ImsSession session)

This notification is used to notify that the session is now established. Parameters:


processSessionStartFailed

public void processSessionStartFailed(ImsSession session)

This notification is used to notify that the session could not be started. Parameters:


processSessionHold

public void processSessionHold(ImsSession session)

This notification is used to notify that the session has been put on hold.

Core API

87

Parameters: session - The session that generated the event.

processSessionHoldFailed

public void processSessionHoldFailed(ImsSession session)

This notification is used to notify that the session could not be put on hold. Parameters:


processSessionResumed

public void processSessionResumed(ImsSession session)

This notification is used to notify that the session has been resumed. Parameters:


processSessionResumeFailed

public void processSessionResumeFailed(ImsSession session)

This notification is used to notify that the session could not be resumed. Parameters:


processSessionTransferred

public void processSessionTransferred(ImsSession session)

This method is used to notify that a session has been successfully transferred. Parameters:


processSessionTransferFailed

public void processSessionTransferFailed(ImsSession session)

This method is used to notify that a session transfer failed. Parameters:


Core API

88

processSessionTransferNotification

public void processSessionTransferNotification(ImsSession session, ImsNotification notify)

This method is used to notify that a notification message regarding a session transfer has been received. Parameters:

session - The session the event concerns. notify - The notification.

processSessionTransferRequest

public void processSessionTransferRequest(ImsSession session, String transferTo)

This method is used to notify that the remote party has requested that the session should be transferred to a new location. Parameters:

session - The session that generated the event. transferTo - The user identity to transfer to.

processCsiCsCallConnected

public void processCsiCsCallConnected(ImsSession session)

This method is used to notify that a cs phone call has been connected. Parameters:


processCsiCsCallDisconnected

public void processCsiCsCallDisconnected(ImsSession session)

This method is used to notify that a cs phone call has been disconnected. Parameters:


Interface ImsSubscription javax.microedition.ims.core


Core API

89

public interface ImsSubscription extends ImsServiceMethod

An ImsSubscription is used for subscribing to notifications from a remote party. It can also be used as a subscription server so remote parties can subscribe for noticiations from this party.

The ImsSubscription is based on the SIP SUBSCRIBE method. The subscription will be refreshed periodically until terminate is called. Updates of the subscription may be achieved by modifying the properies of the ImsSubscription and then calling subscribe again.

The subscribed events can be identified by three pieces of information: remotePUI, event type and optionally the message body. The remotePUI denotes the source node of the subscribed events. The event type contains a token and optionally an id parameter. If the event token defines a behaviour associated with the message body, those semantics apply.

Subscription client scenario

To establish a subscription to a remote party's events, an ImsSubscription has to be created. The event to subscribe to must be set and the subscription is started by a call to start. If the remote party accepts the request, he will immediately send a notification with the current status of the event.

See Also: ImsCoreService.createSubscription(String, String, String)

Method Summary Page

String getEvent() Returns the event that this subscription is about. 3

void setListener(ImsSubscriptionListener listener) Sets a listener. 3

void start() Starts a new subscription through sending a SUBSCRIBE request. 3

void terminate() Terminates this subscription by sending a SUBSCRIBE request set to expire

immediately. 3

Method Detail

start

public void start() throws IllegalStateException

Starts a new subscription through sending a SUBSCRIBE request.

Core API

90

Throws: IllegalStateException - If the subscription is in the PENDING state.

terminate

public void terminate() throws IllegalStateException

Terminates this subscription by sending a SUBSCRIBE request set to expire immediately. Throws:

IllegalStateException - If the subscription is in the PENDING state.

setListener

public void setListener(ImsSubscriptionListener listener)

Sets a listener. Parameters:


getEvent

public String getEvent()

Returns the event that this subscription is about. Returns:

The subscribed event.

Interface ImsSubscriptionListener javax.microedition.ims.core

public interface ImsSubscriptionListener

This listener type is used to notify an application about notifications regarding the subscription dialog.

See Also: ImsSubscription.setListener(ImsSubscriptionListener)

Method Summary Page

void processSubscriptionEvent(ImsSubscription subscription, ImsNotification notification)

This method is used for notifying the application about received notifications. 3

Core API

91

void processSubscriptionStarted(ImsSubscription subscription) This method is used for notifying the application that a subscription was

successfully started. 3

void processSubscriptionStartFailed(ImsSubscription subscription) This method is used for notifying the application that a subscription setup failed. 3

void processSubscriptionTerminated(ImsSubscription subscription) This method is used for notifying the application that a subscription was

terminated. 3

Method Detail

processSubscriptionStarted

public void processSubscriptionStarted(ImsSubscription subscription)

This method is used for notifying the application that a subscription was successfully started. Parameters:

subscription - The subscription this event concerns.

processSubscriptionTerminated

public void processSubscriptionTerminated(ImsSubscription subscription)

This method is used for notifying the application that a subscription was terminated. Parameters:


processSubscriptionStartFailed

public void processSubscriptionStartFailed(ImsSubscription subscription)

This method is used for notifying the application that a subscription setup failed. Parameters:


processSubscriptionEvent

public void processSubscriptionEvent(ImsSubscription subscription, ImsNotification notification)

This method is used for notifying the application about received notifications. Parameters:

subscription - The subscription this notification concerns. notification - The notification.

Core API

92

Package javax.microedition.ims.core.media

The package contains entities used to create media flows for IMS.

See: Description


ImsBasicReliableMedia The ImsBasicReliableMedia represent a media connection with application data transported over TCP.

3

ImsBasicReliableMediaListener A listener type for receiving notification of when ImsBasicReliableMedia objects are received.

3

ImsBasicUnreliableMedia The ImsBasicUnreliableMedia represent a media connection with application data transported over UDP.

3

ImsBasicUnreliableMediaListener A listener type for receiving notification of when ImsBasicUnreliableMedia objects are received.

3

ImsFramedMedia The ImsFramedMedia represents a media connection on which data is delivered in packets.

3

ImsFramedMediaListener A listener type for receiving notification of when ImsFramedMedia objects are received.

3

ImsMedia The ImsMedia object is used to represent the media in an IMS session.

3

ImsMediaContent This is a container for data used in ImsFramedMedia, ImsBasicUnreliableMedia and ImsBasicReliableMedia.

3

ImsMediaDescriptor The different media in IMS are described by the Session Description Protocol (SDP).

3

ImsMediaListener A listener type for receiving notification on media events.

3

ImsMsrpMedia The ImsMsrpMedia represents a media connection on which data is delivered in packets.

3

ImsMsrpMediaListener A listener type for receiving notification of when media objects are received.

3

ImsQosProfile An ImsQosProfile represent Qos related parameters associated to a Media.

3

ImsRtpMedia

The ImsRtpMedia represents a media connection based on the RTP/RTCP protocols containing streaming media such as audio or video that can be rendered in realtime.

3

Core API

93

ImsStreamMedia

The ImsStreamMedia represents a media connection based on the RTP/RTCP protocols containing streaming media such as audio or video that can be rendered in realtime.

3

ImsTcpMedia The ImsTcpMedia represent a media connection with application data transported through TCP.

3

ImsUdpMedia The ImsUdpMedia represent a media connection with application data transported through UDP.

3

Class Summary Page

ImsQosTokenBucketTspec An ImsQosTokenBucketTspec is a representation of the Token Bucket Specification as used in RSVP.

3

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 ImsBasicReliableMedia javax.microedition.ims.core.media

All Superinterfaces: ImsMedia

Core API

94

public interface ImsBasicReliableMedia extends ImsMedia

The ImsBasicReliableMedia represent a media connection with application data transported over TCP. The ImsBasicReliableMedia interface is very similar to the ImsBasicUnreliableMedia interface with the difference that the latter uses UDP for data transport.

Sending application specific data

myMedia = mySession.createBasicReliableMedia("application/myFpsGame", ImsMedia.DIRECTION_SEND); myMedia.setListener(this); mySession.start(); ... ImsMediaContent content = myMedia.createMediaContent(myGameData); myMedia.send(content);

Receiving application specific data, alternative 1

The content is received and the MIDlet is notified through the method processContentReceived in the ImsBasicReliableMediaListener interface.

public void processContentReceived(ImsBasicReliableMedia media, ImsMediaContent mediaContent) { if (mediaContent != null) { myGameData = mediaContent.getMediaContent(); } }


The MIDlet calls the receive method and blocks until there is data available on the connection.

ImsMediaContent content = myMedia.receive(); myGameData = content.getMediaContent();

Method Summary Page

ImsMediaContent createMediaContent(byte[] content) Creates an ImsMediaContent to be sent to the remote party. 3

ImsMediaContent receive() Receives data from the remote party. 3

void send(ImsMediaContent mediaContent) Sends data to the remote party. 3

void setListener(ImsBasicReliableMediaListener listener) Sets a listener for media event notifications, replacing any previous

ImsBasicReliableMediaListener. 3

Core API

95

Method Detail

receive

public ImsMediaContent receive() throws IOException

Receives data from the remote party. This method blocks until content data is received. Returns:

A ImsMediaContent object with the received data. Throws:


send

public void send(ImsMediaContent mediaContent) throws IOException

Sends data to the remote party. The ImsMediaContent must be created with a call to ImsBasicUnreliableMedia.createContent. Parameters:

mediaContent - An ImsMediaContent object containing the data to be sent. Throws:


createMediaContent

public ImsMediaContent createMediaContent(byte[] content) throws IOException, IllegalArgumentException

Creates an ImsMediaContent to be sent to the remote party. Parameters:

content - The content to be sent. Returns:

A new ImsMediaContent to be sent to the remote party. Throws:

IOException - If an I/O error occurs. IllegalArgumentException - If one or more of the parameters are invalid.

setListener

public void setListener(ImsBasicReliableMediaListener listener)

Sets a listener for media event notifications, replacing any previous ImsBasicReliableMediaListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Core API

96

Interface ImsBasicReliableMediaListener javax.microedition.ims.core.media

All Superinterfaces: ImsMediaListener

public interface ImsBasicReliableMediaListener extends ImsMediaListener

A listener type for receiving notification of when ImsBasicReliableMedia objects are received. When media becomes available the application is notified by having the processContentReceived method called on the ImsBasicReliableMediaListener that has been set on the ImsBasicReliableMedia.

See Also: ImsMedia

Method Summary Page

void processConnectionClosed(ImsBasicReliableMedia media) This method is called when the remote party has closed its connection for the

media. 3

void processContentReceived(ImsBasicReliableMedia media, ImsMediaContent mediaContent)

This method is called when a media object is received. 3

Method Detail

processContentReceived

public void processContentReceived(ImsBasicReliableMedia media, ImsMediaContent mediaContent)

This method is called when a media object is received. Parameters:

media - The ImsBasicReliableMedia that received the data. mediaContent - An ImsMediaContent object containing the received content.

processConnectionClosed

public void processConnectionClosed(ImsBasicReliableMedia media)

This method is called when the remote party has closed its connection for the media.

Core API

97

Parameters: media - The media whos connection has been closed.

Interface ImsBasicUnreliableMedia javax.microedition.ims.core.media


public interface ImsBasicUnreliableMedia extends ImsMedia

The ImsBasicUnreliableMedia represent a media connection with application data transported over UDP. The ImsBasicUnreliableMedia interface is very similar to the ImsBasicReliableMedia interface with the difference that the latter uses TCP for data transport.

Sending application specific data

myMedia = mySession.createBasicUnreliableMedia("application/myFpsGame", ImsMedia.DIRECTION_SEND); myMedia.setListener(this); mySession.start(); ... ImsMediaContent content = myMedia.createMediaContent(myGameData); myMedia.send(content);


The content is received and the MIDlet is notified through the method processContentReceived in the ImsBasicUnreliableMediaListener interface.

public void processContentReceived(ImsBasicUnreliableMedia media, ImsMediaContent mediaContent) { if (mediaContent != null) { myGameData = mediaContent.getMediaContent(); } }



ImsMediaContent content = myMedia.receive(); myGameData = content.getMediaContent();

Method Summary Page

ImsMediaContent createMediaContent(byte[] content) Creates an ImsMediaContent to be sent to the remote party. 3


Core API

98

void send(ImsMediaContent mediaContent) Sends data to the remote party. 3

void setListener(ImsBasicUnreliableMediaListener listener) Sets a listener for media event notifications, replacing any previous

ImsBasicUnreliableMediaListener. 3

Method Detail

receive



An ImsMediaContent object with the received data. Throws:


send

public void send(ImsMediaContent mediaContent) throws IOException

Sends data to the remote party. The ImsMediaContent must be created with a call to ImsBasicUnreliableMedia.createContent. Parameters:

mediaContent - An ImsMediaContent object containing the data to be sent. Throws:


createMediaContent

public ImsMediaContent createMediaContent(byte[] content) throws IOException, IllegalArgumentException

Creates an ImsMediaContent to be sent to the remote party. Parameters:

content - The content to be sent Returns:

A new ImsMediaContent to be sent to the remote party. Throws:

IOException - If an I/O error occurs. IllegalArgumentException - If one or more of the parameters are invalid.

Core API

99

setListener

public void setListener(ImsBasicUnreliableMediaListener listener)

Sets a listener for media event notifications, replacing any previous ImsBasicUnreliableMediaListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Interface ImsBasicUnreliableMediaListener javax.microedition.ims.core.media


public interface ImsBasicUnreliableMediaListener extends ImsMediaListener

A listener type for receiving notification of when ImsBasicUnreliableMedia objects are received. When media becomes available the application is notified by having the processContentReceived method called on the ImsBasicUnreliableMediaListener that has been set on the ImsBasicUnreliableMedia.

See Also: ImsMedia

Method Summary Page

void processContentReceived(ImsBasicUnreliableMedia media, ImsMediaContent mediaContent)

This method is called when a media object is received. 3

Method Detail


public void processContentReceived(ImsBasicUnreliableMedia media, ImsMediaContent mediaContent)

This method is called when a media object is received. Parameters:

media - The ImsBasicUnreliableMedia object that received the data. mediaContent - An ImsMediaContent object containing the received content.

Core API

100

Interface ImsFramedMedia javax.microedition.ims.core.media


public interface ImsFramedMedia extends ImsMedia

The ImsFramedMedia represents a media connection on which data is delivered in packets. It can be used for e.g. instant massages, serialized data objects or files. The media is transported with MSRP over TCP.

Sending instant messages

String[] acceptedTypes = new String[] {"text/plain"}; myMedia = mySession.createFramedMedia(acceptedTypes, ImsMedia.DIRECTION_SEND_RECEIVE); mySession.start(); ... ImsMediaContent content = myMedia.createMediaContent("Hello Alice!", "text/plain"); myMedia.setListener(this); myMedia.send(content, ImsFramedMedia.REQUEST_SUCCESS_REPORT_YES, ImsFramedMedia.REQUEST_FAILURE_REPORT_YES);

Sending images

String[] acceptedTypes = new String[] {"image/png"}; myMedia = mySession.createFramedMedia(acceptedTypes, ImsMedia.DIRECTION_SEND_RECEIVE); mySession.start(); ... byte[] buff = readFromFile("///media/images/bob.png"); ImsMediaContent content = myMedia.createMediaContent(buff, "image/png"); myMedia.setListener(this); myMedia.send(content, ImsFramedMedia.REQUEST_SUCCESS_REPORT_YES, ImsFramedMedia.REQUEST_FAILURE_REPORT_YES);

Receiving images and instant messages, alternative 1

The content is received and the MIDlet is notified through the method processContentReceived in the ImsFramedMediaListener interface.

public void processContentReceived(ImsFramedMedia media, ImsMediaContent mediaContent) { if (mediaContent != null) { if (mediaContent.getMediaContentType().equals("image/png")) { Image image = Image.createImage(mediaContent.getMediaContent(), 0, mediaContent.getMediaContent().length); Alert alertSplash = new Alert("Image Received", null, image, AlertType.INFO); alertSplash.setTimeout(Alert.FOREVER); alertSplash.addCommand(CMD_ALERT_OK); alertSplash.setCommandListener(this); display.setCurrent(alertSplash); } else if (mediaContent.getMediaContentType().equals("text/plain")) { String mess = new String(mediaContent.getMediaContent()); logOnDisplay(mess); }

Core API

101

} }

Receiving images and instant messages, alternative 2


ImsMediaContent content = myMedia.receive(); if (content.getContentType().equals("image/png")) { Image image = Image.createImage(content.getMediaContent(), 0, content.getMediaContent().length); Alert alertSplash = new Alert("Image Received", null, image, AlertType.INFO); alertSplash.setTimeout(Alert.FOREVER); alertSplash.addCommand(CMD_ALERT_OK); alertSplash.setCommandListener(this); display.setCurrent(alertSplash); } else if (mediaContent.getMediaContentType().equals("text/plain")) { String mess = new String(content.getMediaContent()); logOnDisplay(mess); }

Field Summary Page

int REQUEST_FAILURE_REPORT_NO Indicates that the sender do not want to receive a report upon faulty delivery of

a message. 3

int REQUEST_FAILURE_REPORT_PARTIAL Indicates that the sender do not want to receive a report upon faulty delivery of

a message. 3

int REQUEST_FAILURE_REPORT_YES Indicates that the sender want to receive a report upon faulty delivery of a

message. 3

int REQUEST_SUCCESS_REPORT_NO Indicates that the sender do not want to receive a report upon successful

delivery of a message. 3

int REQUEST_SUCCESS_REPORT_YES Indicates that the sender want to receive a report upon successful delivery of a

message. 3

Method Summary Page

void cancel(ImsMediaContent mediaContent) Cancels the ongoing transfer. 3

ImsMediaContent createMediaContent(byte[] content, String contentType) Creates an ImsMediaContent to be sent to the remote party. 3


void send(ImsMediaContent mediaContent, int requestSuccessReport, int requestFailureReport)

Sends the content to the remote party over a reliable connection. 3

Core API

102

void setListener(ImsFramedMediaListener listener) Sets a listener for media event notifications, replacing any previous

ImsFramedMediaListener. 3

Field Detail

REQUEST_SUCCESS_REPORT_YES

public static final int REQUEST_SUCCESS_REPORT_YES

Indicates that the sender want to receive a report upon successful delivery of a message.

REQUEST_SUCCESS_REPORT_NO

public static final int REQUEST_SUCCESS_REPORT_NO

Indicates that the sender do not want to receive a report upon successful delivery of a message.

REQUEST_FAILURE_REPORT_YES

public static final int REQUEST_FAILURE_REPORT_YES

Indicates that the sender want to receive a report upon faulty delivery of a message.

REQUEST_FAILURE_REPORT_NO

public static final int REQUEST_FAILURE_REPORT_NO

Indicates that the sender do not want to receive a report upon faulty delivery of a message.

REQUEST_FAILURE_REPORT_PARTIAL

public static final int REQUEST_FAILURE_REPORT_PARTIAL


Core API

103

Method Detail

createMediaContent

public ImsMediaContent createMediaContent(byte[] content, String contentType) throws IOException, IllegalArgumentException

Creates an ImsMediaContent to be sent to the remote party. The content type must be one of the accepted content types for this ImsFramedMedia that was indicated when the media was created. Parameters:

content - The content to be sent. contentType - The MIME type of the content.

Returns: A new ImsMediaContent to be sent to the remote party.

Throws: IOException - If an I/O error occurs. IllegalArgumentException - If one or more of the parameters are invalid.

send

public void send(ImsMediaContent mediaContent, int requestSuccessReport, int requestFailureReport) throws IllegalStateException, IllegalArgumentException, IOException

Sends the content to the remote party over a reliable connection.

Parameters: mediaContent - An ImsMediaContent object containing the data to be sent. requestSuccessReport - Indicates if the receiver should send a report upon a successful delivery. requestFailureReport - Indicates if the receiver should send a report upon a failed delivery.

Throws: IllegalStateException - If the media is not accepted in an etablished session. IllegalArgumentException - If one or more of the parameters are invalid. IOException - If an I/O error occurs.

cancel

public void cancel(ImsMediaContent mediaContent) throws IllegalStateException

Cancels the ongoing transfer. Parameters:

mediaContent - The ImsMediaContent object to be cancelled.

Core API

104

Throws: IllegalStateException - If the media is not accepted in an etablished session.

setListener

public void setListener(ImsFramedMediaListener listener)

Sets a listener for media event notifications, replacing any previous ImsFramedMediaListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


receive



A ImsMediaContent object with the received data. Throws:


Interface ImsFramedMediaListener javax.microedition.ims.core.media


public interface ImsFramedMediaListener extends ImsMediaListener

A listener type for receiving notification of when ImsFramedMedia objects are received. When media becomes available the application is notified by having the processContentReceived method called on the ImsFramedMediaListener that has been set on the ImsFramedMedia.

See Also: ImsMedia

Method Summary Page

void processContentReceived(ImsFramedMedia media, ImsMediaContent mediaContent) This method is called when an object is received from the MSRP media. 3

Core API

105

void processDeliveryFailure(ImsFramedMedia media, ImsMediaContent mediaContent, int responseCode, boolean timeout)

This method is called when the sending of an object failed. 3

void processDeliverySuccess(ImsFramedMedia media, ImsMediaContent mediaContent) This method is called when data has been successfully sent using the MSRP

media. 3

void processTransferProgress(ImsFramedMedia media, ImsMediaContent mediaContent, int percentTransferred)

This method is invoked when there is progress to be reported. 3

Method Detail


public void processContentReceived(ImsFramedMedia media, ImsMediaContent mediaContent)

This method is called when an object is received from the MSRP media. Parameters:

media - The ImsFramedMedia that received the data. mediaContent - An ImsMediaContent object containing the received content.

processTransferProgress

public void processTransferProgress(ImsFramedMedia media, ImsMediaContent mediaContent, int percentTransferred)

This method is invoked when there is progress to be reported. This method works only if the parameter requestSuccessReport is set in the corresponding send method. Please note that the ImsMediaContent objects content is not completely transferred. Parameters:

media - The ImsFramedMedia that received the data. mediaContent - An ImsMediaContent object containing the content that is being transferred. percentTransferred - The percentage of the transfer that is completed.

processDeliverySuccess

public void processDeliverySuccess(ImsFramedMedia media, ImsMediaContent mediaContent)

This method is called when data has been successfully sent using the MSRP media. This method will only be called if the parameter requestSuccessReport is set in the corresponding send. Parameters:

media - The ImsFramedMedia that sent the data. mediaContent - An ImsMediaContent object containing the content that has been transferred.

Core API

106

processDeliveryFailure

public void processDeliveryFailure(ImsFramedMedia media, ImsMediaContent mediaContent, int responseCode, boolean timeout)

This method is called when the sending of an object failed. This method will only be called if the parameter requestFailureReport is set in the corresponding send. Parameters:

media - The ImsFramedMedia that sent the data. mediaContent - An ImsMediaContent object containing the content that has not been transferred. responseCode - The reason why the transaction failed. timeout - Indicates if the transaction failed becase of an timeout.

Interface ImsMedia javax.microedition.ims.core.media

All Known Subinterfaces: ImsBasicReliableMedia, ImsBasicUnreliableMedia, ImsFramedMedia, ImsMsrpMedia, ImsRtpMedia, ImsStreamMedia, ImsTcpMedia, ImsUdpMedia

public interface ImsMedia

The ImsMedia object is used to represent the media in an IMS session. A media can be seen as a pipe between the two endpoints where data can flow in either direction or both.

When a calling terminal creates a session, a number of media objects are included. When the session is established, the IMS engine creates a media offer based on properties of the included media, and sends it to the remote. If the call is accepted, the remote terminal has a sufficient amount of information to allow it to create equal media objects. In this way, both ends get the same view of the media transfer.

The directionality of the media transfer, the content and the content type are specified in the object. Data sent out from the local terminal through the media is available as an output stream.

A common and useful scenario for IMS applications is to stream video and audio to render in realtime. To support efficient implementations here, an application can pass the stream to a platform-supplied standard Player object that supports an appropriate common codec to do the rendering.

For application-specific media formats where the rendering capability is part of the application logic (e.g. in multi-player games), it is possible for the application to supply Quality-of-Service (QoS) specification of the media, and a media description and associate that with the media object.

Media objects are subclassed according based on the transport method used.

Core API

107

The life cycle of a media follows the life cycle of the ImsSession to which it is part of.

When the associated ImsSession resides in the PROCEEDING or NEGOTIATING state the methods accept and reject may be used to accept or reject the media offer.

See Also: ImsMediaListener

Field Summary Page

int DIRECTION_INACTIVE This mode specifies that media is inactive. 3

int DIRECTION_RECEIVE This mode specifies that media is received. 3

int DIRECTION_SEND This mode specifies that the media is sent. 3

int DIRECTION_SEND_RECEIVE This mode specifies that media is bi-directional. 3

int STATE_ACTIVE The media is negotiated and "in use" 3

int STATE_DELETED The media has been a part of an existing session, but is now deleted by one of

the parties. 3

int STATE_INACTIVE The media is a part of an existing session, but is now held by one of the parties. 3

int STATE_NEGOTIATED The media exists in an established session and the media offer has been

accepted by both parties. 3

int STATE_NOT_NEGOTIATED The media is created in a non established session. 3

int STATE_PENDING_UPDATE The media has been added to an established seesion or some of the media

properties has been changed, but there has been no renegotiation. 3

int STATE_REJECTED The media exists in an established session and the media offer has been

rejected by one of the parties. 3

Method Summary Page

void accept() At session setup, the terminating side calls this method to accept this

media. 3

String getContentType() Returns the current content type of the media. 3

Core API

108

int getDirection() Returns the current direction of the media. 3

ImsMediaDescriptor getMediaDescriptor() Returns the media descriptor associated with this media object. 3

ImsQosProfile getQoS() Returns the QoS setting for this media. 3

int getState() Returns the current state of the media. 3

void hold() Place this media on hold. 3

boolean isActive() Determines if the media object is capable of transferring data. 3

boolean isHold() Determines if the media is in a hold state. 3

void reject() Reject this media. 3

void resume() A media placed on hold is resumed. 3

void setDirection(int direction) Sets the direction of the media. 3

Field Detail

DIRECTION_INACTIVE

public static final int DIRECTION_INACTIVE

This mode specifies that media is inactive.

DIRECTION_RECEIVE

public static final int DIRECTION_RECEIVE

This mode specifies that media is received.

DIRECTION_SEND

public static final int DIRECTION_SEND

This mode specifies that the media is sent.

Core API

109

DIRECTION_SEND_RECEIVE

public static final int DIRECTION_SEND_RECEIVE

This mode specifies that media is bi-directional.

STATE_NOT_NEGOTIATED

public static final int STATE_NOT_NEGOTIATED

The media is created in a non established session. An inivtation with a media offer has not been sent.

The media is not active and there can currently be no data transfer within this media.

STATE_NEGOTIATED

public static final int STATE_NEGOTIATED

The media exists in an established session and the media offer has been accepted by both parties.

The media is active and data transfer within this media is in progress.

STATE_REJECTED

public static final int STATE_REJECTED

The media exists in an established session and the media offer has been rejected by one of the parties.

The media is inactive and there will be no data transferred within this media.

STATE_PENDING_UPDATE

public static final int STATE_PENDING_UPDATE

The media has been added to an established seesion or some of the media properties has been changed, but there has been no renegotiation. A session update has to be performed.

If the media is added: the media inactive and there is no data transferred within this media. If the media is changed: the media is still active and data is transferred according to the last negotiation.

Core API

110

STATE_DELETED

public static final int STATE_DELETED

The media has been a part of an existing session, but is now deleted by one of the parties.

The media is inactive and there will be no more data transferred within this media.

STATE_INACTIVE

public static final int STATE_INACTIVE

The media is a part of an existing session, but is now held by one of the parties.

The media is active but there will be no data transferred within this media.

STATE_ACTIVE

public static final int STATE_ACTIVE

The media is negotiated and "in use"

Method Detail

isActive

public boolean isActive()

Determines if the media object is capable of transferring data. Returns:

true if the media is active, false otherwise

isHold

public boolean isHold()

Determines if the media is in a hold state. Returns:

true if the media is hold, false otherwise.

getQoS

public ImsQosProfile getQoS()

Returns the QoS setting for this media.

Core API

111

Returns: The current QoS setting.

hold

public void hold() throws IllegalStateException

Place this media on hold. Both endpoints stops the media flows. Throws:


resume

public void resume() throws IllegalStateException

A media placed on hold is resumed. The media flow is not resumed before the processMediaResumed method has been invoked. Note that the other party may not accept to resume the media flow. Throws:


accept

public void accept() throws IllegalStateException

At session setup, the terminating side calls this method to accept this media. Media can then start flowing. Throws:

IllegalStateException - If the session is not in the PROCEEDING or NEGOTIATING state.

reject

public void reject() throws IllegalStateException

Reject this media. The media is no longer active. No media will flow, and no resources are used. Throws:

IllegalStateException - If the session is not in the PROCEEDING or NEGOTIATING state.

Core API

112

getMediaDescriptor

public ImsMediaDescriptor getMediaDescriptor()

Returns the media descriptor associated with this media object. Returns:

the media descriptor associated with this media object

getDirection

public int getDirection()

Returns the current direction of the media. Returns:

the current direction of the media See Also:

setDirection

setDirection

public void setDirection(int direction)

Sets the direction of the media. Parameters:

direction - the direction of the media See Also:

getDirection

getContentType


Returns the current content type of the media. Returns:

the current content type of the media

getState


Returns the current state of the media. Returns:

the current state of the media

Core API

113

Interface ImsMediaContent javax.microedition.ims.core.media

public interface ImsMediaContent

This is a container for data used in ImsFramedMedia, ImsBasicUnreliableMedia and ImsBasicReliableMedia.

The ImsMediaContent is created by factory methods in the different media interfaces and is associated with the media in which it was created. The ImsMediaContent object can only be used within the media object that created it.

See the usage of ImsMediaContent in the descriptions of the different media types.

See Also: ImsBasicReliableMedia, ImsBasicUnreliableMedia, ImsFramedMedia

Method Summary Page

byte[] getMediaContent() Get the content data. 3

String getMediaContentType() Get the content data MIME type. 3

Method Detail

getMediaContent

public byte[] getMediaContent()

Get the content data. Returns:

content data

getMediaContentType

public String getMediaContentType()

Get the content data MIME type. Returns:

content type

Core API

114

Interface ImsMediaDescriptor javax.microedition.ims.core.media

public interface ImsMediaDescriptor

The different media in IMS are described by the Session Description Protocol (SDP). SDP provides information of the media such as codecs, bitrates and transport addresses.

When one party of an IMS session would like to start a new session containing media, or extend an existing session with new media, he has to formulate a SDP offer. A SDP offer contains e.g. a range of available codecs that client supports and which port the media will be available from. The remote party can choose an appropriate codec and state which port he will supply the media at in his response to the SDP offer.

An SDP description is denoted by the MIME content type "application/sdp" and is divided into three different parts: session description, time description and media description. The third part, media description, is available for reviewing and editing thru this class, ImsMediaDescriptor.

The media decription part of the SDP 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.

The media description 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 continously increase. The ImsMediaDescriptor class gives access to review and add new attributes to 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=audio 49170 RTP/AVP 0 8 97 a=rtpmap:0 PCMU/8000 a=rtpmap:8 PCMA/8000 a=rtpmap:97 iLBC/8000 m=video 51372 RTP/AVP 31 32 a=rtpmap:31 H261/90000 a=rtpmap:32 MPV/90000

NOTE: This class should only be needed when an application needs to setup the SDP to describe application-specific media.

NOTE: If the media description is changed so that the ImsSession needs to be renegotiated, the application is responsible to call update in the ImsSession.

Core API

115

Method Summary Page

void appendAttribute(String attribute) Adds a new attribute at the end of the SDP for the media. 3

String getAttribute(int index) Returns the attribute at index. 3

Vector getAttributes() Returns all attributes as a Vector object. 3

String getMediaDescription() Returns the contents of the media description field in SDP for this media. 3

int getNumberOfAttributes() Returns the number of attributes in the SDP. 3

void insertAttribute(String attribute, int index) Inserts a new attribute into the SDP at index. 3

void updateAttribute(String attribute, int index) Updates the attribute at index to a new value, replacing previous value. 3

Method Detail

insertAttribute

public void insertAttribute(String attribute, int index)

Inserts a new attribute into the SDP at index. Parameters:

attribute - The new attribute to insert. index - Position of the new attribute.

updateAttribute

public void updateAttribute(String attribute, int index)

Updates the attribute at index to a new value, replacing previous value. Parameters:

attribute - The new attribute value. index - Position of the attribute to update.

appendAttribute

public void appendAttribute(String attribute)

Adds a new attribute at the end of the SDP for the media. Parameters:

attribute - The new attribute to append.

Core API

116

getNumberOfAttributes

public int getNumberOfAttributes()

Returns the number of attributes in the SDP. Returns:

Number of attributes represented in this media.

getAttribute

public String getAttribute(int index)

Returns the attribute at index. Parameters:

index - Index of the attribute to return. Returns:

Value of the attributes at the index

getAttributes

public Vector getAttributes()

Returns all attributes as a Vector object. The elements in the vector has the same order as the attributes. Returns:

A vector containing all attributes.

getMediaDescription

public String getMediaDescription()

Returns the contents of the media description field in SDP for this media. Example of SDP mediadescriptor: m=audio 4000 RTP/AVP 97 101 Returns:

The media description.

Interface ImsMediaListener javax.microedition.ims.core.media

All Known Subinterfaces: ImsBasicReliableMediaListener, ImsBasicUnreliableMediaListener, ImsFramedMediaListener, ImsMsrpMediaListener

public interface ImsMediaListener

Core API

117

A listener type for receiving notification on media events.

See Also: ImsMedia

Method Summary Page

void processMediaActivated(ImsMedia media) This method is used to notify that the media object is deactivated. 3

void processMediaDeactivated(ImsMedia media) This method is used to notify that the media object is deactivated. 3

void processMediaHold(ImsMedia media) This method is used to notify that the media object has been put on hold. 3

void processMediaResumed(ImsMedia media) This method is used to notify that the media object has been resumed. 3

Method Detail

processMediaDeactivated

public void processMediaDeactivated(ImsMedia media)

This method is used to notify that the media object is deactivated. Parameters:

media - The media this event refers to.

processMediaActivated

public void processMediaActivated(ImsMedia media)

This method is used to notify that the media object is deactivated. Parameters:


processMediaHold

public void processMediaHold(ImsMedia media)

This method is used to notify that the media object has been put on hold. Parameters:


Core API

118

processMediaResumed

public void processMediaResumed(ImsMedia media)

This method is used to notify that the media object has been resumed. Parameters:


Interface ImsMsrpMedia javax.microedition.ims.core.media


public interface ImsMsrpMedia extends ImsMedia

The ImsMsrpMedia represents a media connection on which data is delivered in packets. It can be used for e.g. serialized data objects or files.

Example use of ImsMsrpMedia

Create a new media object. It will automatically be attached to the session.

ImsMsrpMedia myMedia = mySession.createMsrpMedia(acceptedContentTypes, dir); myMsrpMedia.setListener(this); mySession.update();

Wait for the remote party to accept the added media, listen for the processSessionUpdateAccepted event. Then choose which content to send in this ImsMsrpMedia and indicate which kind of delivery reports you are interrested in.

String messageId = myMsrpMedia.send(content, "image/jpeg", REQUEST_SUCCESS_REPORT_YES, REQUEST_FAILURE_REPORT_YES);

If the content is too big to hold in a data buffer in RAM, there is a send method that reads the content from a stream instead. The user can easily create a stream from e.g. a file or another data source.

FileConnection fconn = (FileConnection)Connector.open(fileName); fconn.create(); InputStream is = fconn.openInputStream(); String messageId = myMsrpMedia.send(is, "image/jpeg", REQUEST_SUCCESS_REPORT_YES, REQUEST_FAILURE_REPORT_YES);

There can be a number of transfer progress events processTransferProgress with a messagId matching messageId returned from the send method during the transfer. When the transfer is complete there will be an processDeliverySuccess event generated.

This instance of ImsMsrpMedia can also be used for exchanging simple text messages like this:

Core API

119

String messText = "Hi Alice! Are you free for lunch today?"; String messId = myMedia.send(messText.getBytes(), "text/plain", REQUEST_SUCCESS_REPORT_YES, REQUEST_FAILURE_REPORT_YES);

Incoming media transfers will be detected in the processContentReceived method in the associated ImsMsrpMediaListener. The incoming media object can e.g. be displayed on the screen, played through the speaker or saved to the file system.

Field Summary Page

int REQUEST_FAILURE_REPORT_NO Indicates that the sender do not want to receive a report upon faulty delivery of

a message. 3

int REQUEST_FAILURE_REPORT_PARTIAL Indicates that the sender do not want to receive a report upon faulty delivery of

a message. 3

int REQUEST_FAILURE_REPORT_YES Indicates that the sender want to receive a report upon faulty delivery of a

message. 3

int REQUEST_SUCCESS_REPORT_NO Indicates that the sender do not want to receive a report upon successful

delivery of a message. 3

int REQUEST_SUCCESS_REPORT_YES Indicates that the sender want to receive a report upon successful delivery of a

message. 3

Method Summary Page

void cancel(String messageId) Cancels the ongoing transfer. 3

String send(byte[] content, String contentType, int requestSuccessReport, int requestFailureReport)


String send(InputStream content, String contentType, int requestSuccessReport, int requestFailureReport)


void setListener(ImsMsrpMediaListener listener) Sets a listener for media event notifications, replacing any previous

ImsSessionListener. 3

Field Detail

REQUEST_SUCCESS_REPORT_YES

public static final int REQUEST_SUCCESS_REPORT_YES

Core API

120

Indicates that the sender want to receive a report upon successful delivery of a message.

REQUEST_SUCCESS_REPORT_NO

public static final int REQUEST_SUCCESS_REPORT_NO

Indicates that the sender do not want to receive a report upon successful delivery of a message.

REQUEST_FAILURE_REPORT_YES

public static final int REQUEST_FAILURE_REPORT_YES

Indicates that the sender want to receive a report upon faulty delivery of a message.

REQUEST_FAILURE_REPORT_NO

public static final int REQUEST_FAILURE_REPORT_NO


REQUEST_FAILURE_REPORT_PARTIAL

public static final int REQUEST_FAILURE_REPORT_PARTIAL


Method Detail

send

public String send(byte[] content, String contentType, int requestSuccessReport, int requestFailureReport) throws IllegalStateException, IllegalArgumentException, IOException


The content is supplied in a data buffer together with a MIME type describing its contents. The content type must be one of the accepted content types for this ImsMsrpMedia that was indicated when the media was created.

Core API

121

Parameters: content - the content to send to the remote party contentType - the type of the content to send requestSuccessReport - indicates if the receiver should send a report upon a successful delivery requestFailureReport - indicates if the receiver should send a report upon a failed delivery

Returns: a string identifying the particular message

Throws: IllegalStateException - if the media is not accepted in an etablished session IllegalArgumentException - if one or more of the parameters are invalid IOException - if an I/O error occurs.

send

public String send(InputStream content, String contentType, int requestSuccessReport, int requestFailureReport) throws IllegalStateException, IllegalArgumentException, IOException


The content is supplied in an InputStream together with a MIME type describing its contents. The content type must be one of the accepted content types for this ImsMsrpMedia that was indicated when the media was created. Parameters:

content - the content to send to the remote party contentType - the type of the content to send requestSuccessReport - indicates if the receiver should send a report upon a successful delivery requestFailureReport - indicates if the receiver should send a report upon a failed delivery

Returns: a string identifying the particular message

Throws: IllegalStateException - if the media is not accepted in an etablished session IllegalArgumentException - if one or more of the parameters are invalid IOException - if an I/O error occurs.

cancel

public void cancel(String messageId) throws IllegalStateException

Cancels the ongoing transfer. Parameters:

messageId - the id of the message to cancel Throws:

IllegalStateException - if the media is not accepted in an etablished session

Core API

122

setListener

public void setListener(ImsMsrpMediaListener listener)

Sets a listener for media event notifications, replacing any previous ImsSessionListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Interface ImsMsrpMediaListener javax.microedition.ims.core.media


public interface ImsMsrpMediaListener extends ImsMediaListener

A listener type for receiving notification of when media objects are received. When media becomes available the application is notified by having the notifyObjectReceived method called on the ImsMsrpMediaListener that has been set on the ImsMsrpMedia.

See Also: ImsMedia

Method Summary Page

void processContentReceived(ImsMsrpMedia media, byte[] content, String contentType)

This method is called when an object is received from the MSRP media. 3

void processDeliveryFailure(ImsMsrpMedia media, String messageId, int responseCode, boolean timeout)

This method is called when the sending of an object failed. 3

void processDeliverySuccess(ImsMsrpMedia media, String messageId) This method is called when data has been successfully sent using the MSRP

media. 3

void processTransferProgress(ImsMsrpMedia media, String messageId, int percentTransferred)

This method is invoked when there is progress to be reported. 3

Core API

123

Method Detail


public void processContentReceived(ImsMsrpMedia media, byte[] content, String contentType)

This method is called when an object is received from the MSRP media. Parameters:

media - the ImsMsrpMedia that received the data content - contains the data for the received object contentType - the type of the data

processTransferProgress

public void processTransferProgress(ImsMsrpMedia media, String messageId, int percentTransferred)

This method is invoked when there is progress to be reported. This method works only if the parameter requestSuccessReport is set in the corresponding send. Parameters:

media - the ImsMsrpMedia that received the data messageId - the id of the data part that is in progress percentTransferred - the progress of the transfer

processDeliverySuccess

public void processDeliverySuccess(ImsMsrpMedia media, String messageId)

This method is called when data has been successfully sent using the MSRP media. This method will only be called if the parameter requestSuccessReport is set in the corresponding send. Parameters:

media - the ImsMsrpMedia that sent the data messageId - the id of the data part that is sent

processDeliveryFailure

public void processDeliveryFailure(ImsMsrpMedia media, String messageId, int responseCode, boolean timeout)

This method is called when the sending of an object failed. This method will only be called if the parameter requestFailureReport is set in the corresponding send.

Core API

124

Parameters: media - the ImsMsrpMedia that sent the data messageId - the id of the data part that has failed

Interface ImsQosProfile javax.microedition.ims.core.media

public interface ImsQosProfile

An ImsQosProfile represent Qos related parameters associated to a Media. This type holds the specification of the media flow characteristics using the same language as that of RSVP of IntServ. Note that this does not necessarily imply that RSVP has to be supported in the implementation. There may be a mapping to some other QoS mechanism, such as DSCP of DiffServ.

See 3GPP TS 23.107, 3GPP TS 23.207 and 3GPP TS 23.060 for more information.

Field Summary Page

int SERVICE_TYPE_CONTROLLED_LOAD This is according the service type "controlled load" according to RFC 2211. 3

int SERVICE_TYPE_GUARANTEED This is according to the service type "guaranteed" according to RFC 2212. 3

int SERVICE_TYPE_UNDEFINED The service type (according to RFC 2210) is undefined. 3

int TRAFFIC_CLASS_BACKGROUND The background traffic class. 3

int TRAFFIC_CLASS_CONVERSATIONAL The conversational traffic class. 3

int TRAFFIC_CLASS_INTERACTIVE The interactive traffic class. 3

int TRAFFIC_CLASS_STREAMING The streaming traffic class. 3

int TRAFFIC_CLASS_UNSPECIFIED No traffic class is specified. 3

Method Summary Page

int getMaximumPacketSize() Returns the maximum packets size. 3

int getMinimumPolicedUnit() Returns the minimum policed unit. 3

Core API

125

int getPeakTrafficRate() Returns the peak traffic rate. 3

int getRate() Return the current rate. 3

int getServiceType() Get the service type indicated in this class. 3

int getSize() Returns the depth of the token bucket. 3

int getTrafficClass() Returns the current traffic class of the media. 3

void setMaximumPacketSize(int maximumPacketSize) Sets the maximum packet size. 3

void setMinimumPolicedUnit(int minimumPolicedUnit) Sets the minimum policed unit. 3

void setPeakTrafficRate(int peakTrafficRate) Sets the peak traffic rate. 3

void setRate(int rate) Sets the rate. 3

void setServiceType(int serviceType) Sets the service type according to RFC 2210, RFC 2211 or RFC 2212. 3

void setSize(int size) Sets the depth of the token bucket. 3

void setTrafficClass(int trafficClass) Sets the traffic class of the media. 3

Field Detail

TRAFFIC_CLASS_UNSPECIFIED

public static final int TRAFFIC_CLASS_UNSPECIFIED

No traffic class is specified. The system will choose an appropriate value based on the media.

TRAFFIC_CLASS_CONVERSATIONAL

public static final int TRAFFIC_CLASS_CONVERSATIONAL

The conversational traffic class. The data traffic is assumed to be relatively non-bursty. Voice data is a typical example.

Core API

126

TRAFFIC_CLASS_STREAMING

public static final int TRAFFIC_CLASS_STREAMING

The streaming traffic class. The data traffic is assumed to be relatively non-bursty. Streaming video is a typical example.

TRAFFIC_CLASS_INTERACTIVE

public static final int TRAFFIC_CLASS_INTERACTIVE

The interactive traffic class. This class is optimised for transport of human or machine interaction with remote equipment, e.g. web browsing. The data traffic characteristics are unknown, but may be bursty. Web browsing is a typical example.

TRAFFIC_CLASS_BACKGROUND

public static final int TRAFFIC_CLASS_BACKGROUND

The background traffic class. This class is optimised for machine-to-machine communication that is not delay sensitive, e.g. messaging services. Email is a typical example.

SERVICE_TYPE_UNDEFINED

public static final int SERVICE_TYPE_UNDEFINED

The service type (according to RFC 2210) is undefined.

SERVICE_TYPE_CONTROLLED_LOAD

public static final int SERVICE_TYPE_CONTROLLED_LOAD

This is according the service type "controlled load" according to RFC 2211.

SERVICE_TYPE_GUARANTEED

public static final int SERVICE_TYPE_GUARANTEED

This is according to the service type "guaranteed" according to RFC 2212.

Core API

127

Method Detail

getServiceType

public int getServiceType()

Get the service type indicated in this class. Returns:

The service type of this ImsQosProfile.

setServiceType

public void setServiceType(int serviceType)

Sets the service type according to RFC 2210, RFC 2211 or RFC 2212. Parameters:

serviceType - The service type to apply to this ImsQosProfile.

getTrafficClass

public int getTrafficClass()

Returns the current traffic class of the media. Returns:

The current traffic class of the media. See Also:

setTrafficClass

setTrafficClass

public void setTrafficClass(int trafficClass)

Sets the traffic class of the media. This shall be done when the media object is created. Parameters:

trafficClass - The traffic class to set. See Also:

getTrafficClass

getMaximumPacketSize

public int getMaximumPacketSize()

Returns the maximum packets size. Returns:

The maximum packet size.

Core API

128

See Also: setMaximumPacketSize(int)

setMaximumPacketSize

public void setMaximumPacketSize(int maximumPacketSize)

Sets the maximum packet size. Parameters:

maximumPacketSize - The maximum packet size to set. See Also:

getMaximumPacketSize()

getMinimumPolicedUnit

public int getMinimumPolicedUnit()

Returns the minimum policed unit. Returns:

The minimum policed unit. See Also:

setMinimumPolicedUnit(int)

setMinimumPolicedUnit

public void setMinimumPolicedUnit(int minimumPolicedUnit)

Sets the minimum policed unit. Parameters:

minimumPolicedUnit - The minimum policed unit to set. See Also:

getMinimumPolicedUnit()

getPeakTrafficRate

public int getPeakTrafficRate()

Returns the peak traffic rate. Returns:

The peak traffic rate. See Also:

setPeakTrafficRate(int)

setPeakTrafficRate

public void setPeakTrafficRate(int peakTrafficRate)

Core API

129

Sets the peak traffic rate. Parameters:

peakTrafficRate - The peak traffic rate to set. See Also:

getPeakTrafficRate()

getRate

public int getRate()

Return the current rate. Returns:

The current rate. See Also:

setRate(int)

setRate

public void setRate(int rate)

Sets the rate. Parameters:

rate - The new current rate. See Also:

getRate()

getSize

public int getSize()

Returns the depth of the token bucket. Returns:

The depth of the token bucket. See Also:

setSize(int)

setSize

public void setSize(int size)

Sets the depth of the token bucket. Parameters:

size - The new depth of the token bucket. See Also:

getSize()

Core API

130

Class ImsQosTokenBucketTspec javax.microedition.ims.core.media

java.lang.Object javax.microedition.ims.core.media.ImsQosTokenBucketTspec

public class ImsQosTokenBucketTspec extends Object

An ImsQosTokenBucketTspec is a representation of the Token Bucket Specification as used in RSVP. An application defines this to describe a media seen as a data flow. See RFC 2215.

Field Summary Page

int b Token bucket size 3

int m Minimum policed unit 3

int M Biggest packet size 3

int p Peak traffic rate in datagrams per second 3

int r Token bucket rate 3


ImsQosTokenBucketTspec() 3

Field Detail

r

public int r

Token bucket rate

b

public int b

Token bucket size

Core API

131

p

public int p

Peak traffic rate in datagrams per second

m

public int m

Minimum policed unit

M

public int M

Biggest packet size

Constructor Detail

ImsQosTokenBucketTspec

public ImsQosTokenBucketTspec()

Interface ImsRtpMedia javax.microedition.ims.core.media


public interface ImsRtpMedia extends ImsMedia

The ImsRtpMedia represents a media connection based on the RTP/RTCP protocols containing streaming media such as audio or video that can be rendered in realtime.

Playback Example

Play sourced video (viewfinder)

try { ImsRtpMedia media = new ImsRtpMedia("capture://video"); session.addMedia(media); // Create a Player that displays the outgoing live video.

Core API

132

Player p = media.getOutputPlayer(); p.realize(); p.start(); } catch (IOException ioe) { } } catch (MediaException me) { }

Play received audio

try { //get incoming media ImsRtpMedia media = (ImsRtpMedia) session.getMedia()[0]; // Create a Player that displays the live video input. Player p = media.getInputPlayer(); p.realize(); p.start(); } catch (IOException ioe) { } } catch (MediaException me) { }

Method Summary Page

Player getInputPlayer() Returns a player for rendering the input stream. 3

Player getOutputPlayer() Returns a player for the output stream. 3

Method Detail

getOutputPlayer

public Player getOutputPlayer()

Returns a player for the output stream. This player may be useful for i.e. rendering a viewfinder. Returns:

a player object

getInputPlayer

public Player getInputPlayer()

Returns a player for rendering the input stream. Returns:

a player object

Core API

133

Interface ImsStreamMedia javax.microedition.ims.core.media


public interface ImsStreamMedia extends ImsMedia

The ImsStreamMedia represents a media connection based on the RTP/RTCP protocols containing streaming media such as audio or video that can be rendered in realtime.

Playback Example

Play sourced video (viewfinder)

try { ImsStreamMedia myMedia = mySession.createStreamMedia("capture://video"); // Create a Player that displays the outgoing live video. Player p = Manager.createPlayer(myMedia.getDataSource()); ... p.realize(); p.start(); } catch (IOException ioe) { } } catch (MediaException me) { }

Play received audio

try { //get incoming media ImsStreamMedia myMedia = (ImsStreamMedia)session.getMedia().elementAt(myStreamMediaIndex); // Create a Player that plays the incoming audio. Player p = Manager.createPlayer(myMedia.getDataSource()); ... p.realize(); p.start(); } catch (IOException ioe) { } } catch (MediaException me) { }

Method Summary Page

DataSource getDataSource() Returns a data source for rendering an incoming media stream or a viewfinder

for an outgoing media stream. 3

void setListener(ImsMediaListener listener) Sets a listener for media event notifications, replacing any previous

ImsMediaListener. 3

Core API

134

Method Detail

getDataSource

public DataSource getDataSource()

Returns a data source for rendering an incoming media stream or a viewfinder for an outgoing media stream.

The data source will is used when creating a Player. Returns:

a DataSource object

setListener

public void setListener(ImsMediaListener listener)

Sets a listener for media event notifications, replacing any previous ImsMediaListener. A null reference is allowed and has the effect of removing any existing listener. Parameters:


Interface ImsTcpMedia javax.microedition.ims.core.media


public interface ImsTcpMedia extends ImsMedia

The ImsTcpMedia represent a media connection with application data transported through TCP.

Interface ImsUdpMedia javax.microedition.ims.core.media


public interface ImsUdpMedia extends ImsMedia

Core API

135

The ImsUdpMedia represent a media connection with application data transported through UDP. Datagram objects are used for sending and receiving data, they provides a simple way to read and write binary data. Example of how to send data: try { Datagram dg = myUdpMedia.newDatagram(100); dg.writeUTF("Hello world!"); myUdpMedia.send(dg); } catch

(IOException e) { e.printStackTrace(); } Example of how to receive data: try { Datagram dg = myUdpMedia.receive(100); if (dg != null) { System.out.println("Received media data

= " + dg.readUTF()); } } catch (Exception ex) { ex.printStackTrace(); } Please note that the call to receive block until a datagram is received.

Method Summary Page

Datagram newDatagram(int size) Creates a datagram to be sent to the remote party. 3

Datagram receive(int size) Receives data from the remote party. 3

void send(Datagram dg) Sends data to the remote party. 3

Method Detail

receive

public Datagram receive(int size) throws IOException

Receives data from the remote party. This method blocks until a datagram is received. If the received data is longer than the value of size, data is truncated. Parameters:

size - The expected size of the received data Returns:

A Datagram with the received data Throws:

IOException

send

public void send(Datagram dg) throws IOException

Sends data to the remote party. The datagram must be created with a call to ImsUdpMedia.newDatagram. Parameters:

dg - A datagram containing the data to be sent. Throws:

IOException See Also:

newDatagram(int)

Core API

136

newDatagram

public Datagram newDatagram(int size) throws IOException

Creates a datagram to be sent to the remote party. Parameters:

size - The size of the created datagram Returns:

A new Datagram to be sent to the remote party Throws:

IOException See Also:

send(Datagram)

Service API

137

7 Service API

This document specifies a high-level Java API for the major service enablers for the IP Multimedia Subsystem (IMS). The service enablers considered in this document are:

• the XDM service enabler facilitating handling of various kinds of XDM documents; • the Presence service enabler providing abstractions for presenities, subscriptions and other

presence-related entities; • the Push-to-Talk over Cellular (PoC) service enabler offering management of several

kinds of PoC sessions;

The document structure reflects these parts: For each of these service enablers a separate package has been introduced. A set of utility entities including IMS specific exceptions, elements of policies and XML documents as well as a synchronization interface that are commonly used in all three service enabler packages are provided in another package. Standardization documents upon which the designs are based are listed in the introductory section of each package.

Package Summary Page

javax.microedition.ims.service.poc This package defines the JSR 281 Push-to-Talk over Cellular (PoC) API.

3

javax.microedition.ims.service.presence This package defines the JSR 281 Presence API. 3

javax.microedition.ims.service.util This package defines utility entities for JSR 281 service enablers.

3

javax.microedition.ims.service.xdm This package defines the JSR 281 XML Document Management (XDM) API.

3

Package javax.microedition.ims.service.poc

This package defines the JSR 281 Push-to-Talk over Cellular (PoC) API.

See: Description


PoCActivityListener

Interface PoCActivityListener provides methods for notification of Talk Burst activity on the respective session even if Talk Bursts of that particular PoC session or even all PoC sessions are blocked at the PoC server on user's request.

3

PoCAdhocSession Interface PoCAdhocSession that extends interface PoCSession provides methods for manipulation of ad-hoc sessions with one or more individual users.

3

Service API

138

PoCAttributeListener Interface PoCAttributeListener that has to be implemented by the PoC application and provides methods for notification of changes of global attributes of the PoC engine.

3

PoCChatSession Interface PoCChatSession that extends interface PoCSession provides methods for manipulation of PoC chat sessions with open or restricted groups.

3

PoCGroup Interface PoCGroup provides access to attributes PoC used for establishment of PoC chat sessions or PoC prearranged sessions.

3

PoCParticipantListener Interface PoCParticipantListener provides methods for notification of participant information updates.

3

PoCPrearrangedSession Interface PoCPrearrangedSession that extends interface PoCSession provides methods for manipulation of prearranged sessions with predefined groups of users.

3

PoCService Interface PoCService is an extension of IMSService that acts as a factory for all instances of sessions, groups, policies und rules owned by a particular public user ID.

3

PoCServiceListener Interface PoCServiceListener that has to be implemented by the PoC application provides methods for notification of incoming session requests, instant personal alerts or group advertisments.

3

PoCSession Interface PoCSession specifies all methods common to all three flavours of PoC sessions.

3

PoCSessionListener

Interface PoCSessionListener provides methods for notification of all kinds of events regarding initiation and termination of PoC sessions, joining or leaving PoC sessions and invitation of additional participants.

3

PoCTBController

Interface PoCTBController provides methods for issuing Talk Burst requests, querying the state of queued Talk Burst requests, cancelling Talk Burst requests, releasing a Talk Burst, setting a Talk Burst Control listener and obtaining information on the state of a Talk Burst.

3

PoCTBControlListener Interface PoCTBControlListener provides methods for notification of Talk Burst Control events and for reception of information about the status of the Talk Burst Request Queue.

3

PoCUserAccessPolicy Interface PoCUserAccessPolicy allows handling of a Poc User Access Rules document.

3

PoCUserAccessRule Interface PoCUserAccessRule allows specification of a PoC user access rule.

3

Package javax.microedition.ims.service.poc Description

This package defines the JSR 281 Push-to-Talk over Cellular (PoC) API.

Service API

139

The PoC API is intended to allow applications / application programmers easy initiation, control and termination of PoC sessions with individual participants as well as pre-defined groups of participants. The PoC API enables dynamic modification of PoC sessions in terms of adding participants.

The PoC API supports three different flavors of PoC Sessions: Chat Mode, Prearranged Mode and Ad-hoc Mode. The three modes are explained in more detail in the following subsections.

Chat Mode

Chat mode is a flavor of PoC communication that is based on permanently active chat sessions that are initiated by the PoC server exclusively and terminated only due to maintenance reasons. Access to such sessions is controlled via predefined groups. Two kinds of groups are used:

• Open groups: allow access for every user provided that the user is not on the reject list of that group.

• Restricted groups: allow access only for users that are on the member list of that group.

An authorized user can join and leave a chat session at any time. Any participant of a chat session can invite another user that is authorized to participate in the session. The maximum number of allowed participants can be restricted by the PoC administrator.

Prearranged Mode

Prearranged mode is a flavor of PoC communication that is based on prearranged groups. Any member of such a group can initiate a prearranged session by inviting the group. If at least one of the group members accepts the invitation, the prearranged session is established. In the 1-to-many communication model all parties are equal; a Talk Burst issued by any party is sent to all other parties. In the 1-to-many-to-1 communication model, the initiator of the prearranged session who must be a Distinguished Participant with special authorization is privileged; a Talk Burst issued by the distinguished participant is sent to all other parties whereas a Talk Burst issued by an ordinary participant is sent only to the Distinguished Participant. Any group member can join an ongoing prearranged session and leave a prearranged session at any time. In the 1-to-many communication model, a prearranged session is terminated by the PoC server if all but one participant have left the session. Even if the session initiator leaves the session it is continued if two or more parties are still participating in the session. In the 1-to-many-to-1 communication model, a prearranged session is terminated if the session initiator who is a Distinguished Participant leaves the session. In the 1-to-many communication model, any participant of a prearranged session can invite another party that is a member of the prearranged group to participate in the session. In the 1-to-many-to-1 communication model, only the initiator of the session can invite other parties. The maximum number of allowed participants can be restricted by the PoC administrator.

Ad-hoc Mode

Ad-hoc mode is a flavor of PoC communication that does not use any predefined groups. Rather, at initiation of an ad-hoc session, a number of individual users are invited to participate. If at least one of the invited users accepts the invitation, the ad-hoc session is established. It is possible to invite only one single user or several users. Users that have been invited to participate but have

Service API

140

rejected the invitation or have previously disconnected from the session can join later if the ad-hoc session is still ongoing. Only the initiator of the ad-hoc session can invite additional users to the session. Any party can disconnect from the ad-hoc session at any time. If the initiator leaves the ad-hoc session, it is instantly terminated. The maximum number of allowed participants can be restricted by the PoC administrator.

Static Structure

The following diagrams illustrate the architecture of the PoC API.

Figure 1: Overview over the major entities (except listeners)

Service API

141

Figure 2: Listeners and their association to other entities

Service API

142

Figure 3: PoC Factory (class PoCManager) and its products

Package Specification

Related IETF and OMA specifications

• OMA Group Management Requirements, Candidate Version 1.0, 30.09.2004, OMA-RD_GM-V1_0-20040930-C.pdf

• OMA Push to Talk over Cellular Requirements Version 1.0, 29.03.2005, OMA-RD-PoC-V1_0-20050329-C.pdf

• OMA Push to talk Over Cellular Control Plane, Candidate Version 1.0, 27.01.2006, OMA-TS-PoC-ControlPlane-V1_0-20060127-C.pdf

• OMA Push to talk Over Cellular User Plane, Candidate Version 1.0, 27.01.2006, OMA-TS_PoC-UserPlane-V1_0-20060127-C.pdf

• OMA Push to talk over Cellular Architecture, Candidate Version 1.0, 27.01.2006, OMA-AD_PoC-V1_0-20060127-C.pdf

Service API

143

Interface PoCActivityListener javax.microedition.ims.service.poc

public interface PoCActivityListener

Interface PoCActivityListener provides methods for notification of Talk Burst activity on the respective session even if Talk Bursts of that particular PoC session or even all PoC sessions are blocked at the PoC server on user's request. The methods are being invoked by the PoC engine upon reception of a Talk Burst activity notification. A PoCActivityListener is registered at a session instance by invoking method setActivityListener Upon invocation of that method, the Poc engine sends a subscription for Talk Burst activity notifications for the respective session to the PoC server. The subscription can be cancelled by invoking method setActivityListener of the respective session instance with the listener parameter set to null.

Method Summary Page

void processActivity(PoCSession session, String userURI) Notifies talk burst activity occuring in the session the listener is registered with. 3

Method Detail

processActivity

public void processActivity(PoCSession session, String userURI)

Notifies talk burst activity occuring in the session the listener is registered with. Parameters:

session - the PoC session where the reported talk burst activity occurs userURI - the URI of the user that is generating the talk burst activity

Interface PoCAdhocSession javax.microedition.ims.service.poc

All Superinterfaces: PoCSession

public interface PoCAdhocSession extends PoCSession

Interface PoCAdhocSession that extends interface PoCSession provides methods for manipulation of ad-hoc sessions with one or more individual users. Instances of PoCAdhocSession are created by the PoCService upon invocation of the method createAdhocSession() by the application or upon an incoming invitation to participate in an ad-

Service API

144

hoc session sent by the initiator of that session. In case of ad-hoc sessions, the inviting party and the invited parties represent different roles throughout the session that can be clearly distinguished in terms the choices they have in the different phases of the session. Therefore, different state machines for caller and callee state are required.

Caller terminal

The following diagram shows the state machine for an ad-hoc session instance on the inviting party’s terminal.

Service API

145

An PoCAdhocSession instance always starts in sub state DISCONNECTED of state OPERATIONAL. A transition to state CONNECTED can be effected in the following way: An 'invite' request issued by the application puts the session into the transient state INVITING from which a transition to state CONNECTED is made if an 'Invite accepted' notification is generated is returned by the PoC server to indicate that the session setup request has been accepted. An 'Invite rejected' notification is generated if the session setup request has been rejected by the PoC server, putting the session back to DISCONNECTED state. A pending invitation can be cancelled by the application through a 'cancel' request that also puts the system back to state DISCONNECTED.

Service API

146

The party that has successfully initiated an ad-hoc session (thus being in state CONNECTED) can invite further participants. If the session has been terminated by the PoC server, reception of a session termination notification causes a transition to state TERMINATED. The application can indicate that the session instance is no longer required by issuing a close request that also causes a transition to state TERMINATED. Transitions to state TERMINATED can be effected from all sub states of state OPERATIONAL. Being in state TERMINATED indicates that the session instance can be garbage collected or reused if necessary.

Callee terminal

The following diagram shows the states for an ad-hoc session instance on the invited party’s terminal.

Service API

147

As already explained above an PoCAdhocSession instance always starts in sub state DISCONNECTED of state OPERATIONAL. A transition to state CONNECTED can be effected in two different ways:

• A 'join' request issued by the application puts the session into the transient state JOINING from which a transition to state CONNECTED is made upon reception of a 'Join accepted' notification. A 'Join rejected' notification puts the session back to DISCONNECTED state. A 'join' request can only be issued if an application has been connected to the ad-hoc session previously or has rejected an invitation to participate in the ad-hoc session and the session

Service API

148

is still ongoing. The reason for this restriction is that ad-hoc sessions, as opposed to other types of PoC sessions, are not associated with permanently defined groups but are characterized by a transient group ID that the PoC server defines on short notice when an ad-hoc session is initiated. This transient group ID is only valid until the ad-hoc session is terminated.

• If the PoC engine receives an incoming invitation to participate in an ad-hoc session, it triggers a transition from state DISCONNECTED to state INVITED if manual answer mode is set, or directly to state CONNECTED if automatic answer mode is set. The ad-hoc session instance has to be generated by the PoC engine before making that transition. When manual answer mode is set, the application must either accept the invitation effecting a transition from state INVITED to state CONNECTED or reject the invitation effecting a transition to state DISCONNECTED. If the invitation has been cancelled by the inviting party, the invited party receives a "Cancel notification" that puts the session directly into state TERMINATED.

An application participating in an ad-hoc session can indicate that the session instance is no longer required by issuing a close request that also causes a transition to state TERMINATED. Transitions to state TERMINATED can be effected from all sub states of state OPERATIONAL. Being in state TERMINATED indicates that the session instance can be garbage collected or reused if necessary.

Field Summary Page

int ROLE_CALLEE Constant representing the role "Callee". 3

int ROLE_CALLER Constant representing the role "Caller". 3

Method Summary Page

void accept() This method allows accepting an invitation to participate in a ad-hoc session. 3

void cancel() This method is used to cancel a pending session initiation. 3

String[] getInvitees() This method returns the users that have been invited to participate in the session. 3

int getRole() This method returns the role that the user has in the session. 3

void invite(boolean manualAnswerOverrideFlag) This method is used to initiate an ad-hoc session with the users associated with

the session instance. 3

void inviteUser(String userURI, boolean manualAnswerOverrideFlag) This method is used to invite another party for the ad-hoc session. 3

void reject() This method allows rejecting an invitation to participate in an ad-hoc session. 3

Service API

149

Field Detail

ROLE_CALLER

public static final int ROLE_CALLER

Constant representing the role "Caller".

ROLE_CALLEE

public static final int ROLE_CALLEE

Constant representing the role "Callee".

Method Detail

getInvitees

public String[] getInvitees()

This method returns the users that have been invited to participate in the session. These users are not necessarily all participating in the ad-hoc session, but each of those that do not currently participate has the option to join the ad-hoc session as long as it is active. NOTE: This method only works as described for the caller (ROLE_CALLER); if any callee (ROLE_CALLEE) invokes that method, null is returned. Returns:

String[] containing the URIs of all participants

getRole

public int getRole()

This method returns the role that the user has in the session. The user may either be the caller (ROLE_CALLER)or a callee (ROLE_CALLEE). Returns:

int specifying the role of the user

invite

public void invite(boolean manualAnswerOverrideFlag) throws IllegalStateException, SecurityException

This method is used to initiate an ad-hoc session with the users associated with the session instance. The session invitation is forwarded to the PoC server by the native PoC engine on the device. The server sends invitations to participate in the ad-hoc session to all specified

Service API

150

users. The method takes one parameter: the manual answer override flag is used to indicate that the manual answer mode of the receiving party should be ignored (if the user has sufficient rights). Parameters:

manualAnswerOverrideFlag - used to set the Manual Override Mode (true = override settings if possible)

Throws: IllegalStateException - if session instance is not in state DISCONNECTED SecurityException - if permission is not granted

inviteUser

public void inviteUser(String userURI, boolean manualAnswerOverrideFlag) throws IllegalStateException, IMSMalformedURIException, SecurityException

This method is used to invite another party for the ad-hoc session. Only the initiator of the ad-hoc ses-sion is permitted to invoke this method. The method takes two parameters: the URI specifies which user should be invited; the manual answer override flag is used to indicate that the manual answer mode of the receiving party should be ignored (if the user has sufficient rights). Parameters:

userURI - URI of the user that is invited manualAnswerOverrideFlag - used to set the Manual Override Mode (true = override settings if possible)

Throws: IllegalStateException - if the inviting user is not the initiator of the ad-hoc session or if session instance is not in state CONNECTED IMSMalformedURIException - if URI is malformed SecurityException - if permission is not granted

accept

public void accept() throws IllegalStateException, SecurityException

This method allows accepting an invitation to participate in a ad-hoc session. Throws:

IllegalStateException - if session is not in state INVITED SecurityException - if permission is not granted

reject

public void reject() throws IllegalStateException, SecurityException

Service API

151

This method allows rejecting an invitation to participate in an ad-hoc session. Throws:


cancel

public void cancel() throws IllegalStateException, SecurityException

This method is used to cancel a pending session initiation. Throws:

IllegalStateException - if session is not in state INVITING SecurityException - if permission is not granted

Interface PoCAttributeListener javax.microedition.ims.service.poc

public interface PoCAttributeListener

Interface PoCAttributeListener that has to be implemented by the PoC application and provides methods for notification of changes of global attributes of the PoC engine. All methods provide information on the current status of the respective attribute. In addition, the methods provide an error code that contains error information if an attempt to change the respective attribute was not successful. If the change attempt was successful or if the notification is sent to an application that did not trigger the attempt, the error is set to null. A PoCAttributeListener is registered at the PoCService instance by invoking method setAttributeListener

Method Summary Page

void processForegroundSessionChanged(boolean marked, String error, PoCSession session)

Delivers notification regarding changes of the marking of a session as foreground session.

3

void processLockingChanged(boolean locked, String error, PoCSession session) Delivers notification regarding changes of locking to a session. 3

void processMuteStateChanged(boolean muted, String error) Delivers notification regarding changes of the mute state. 3

void processPrimarySessionChanged(boolean marked, String error, PoCSession session)

Delivers notification regarding changes of the marking of a session as primary session.

3

Service API

152

void processSessionBarringChanged(boolean personalAlert, boolean sessionRequest, String error)

Delivers notification regarding changes of the barring of Instant Personal Alerts (IPA).

3

Method Detail

processMuteStateChanged

public void processMuteStateChanged(boolean muted, String error)

Delivers notification regarding changes of the mute state. This is a global attribute of the PoC engine shared by all applications using the engine. Parameters:

muted - mute state (true if muted, false otherwise) error - error message regarding last attempt to change the mute state (null if attempt was successful or if notification is sent to an application that did not trigger the attempt)

processSessionBarringChanged

public void processSessionBarringChanged(boolean personalAlert, boolean sessionRequest, String error)

Delivers notification regarding changes of the barring of Instant Personal Alerts (IPA). This is a global attribute of the PoC engine shared by all applications using the engine. Parameters:

personalAlert - true if personal alert is barred, false otherwise sessionRequest - true if session request is barred; false otherwise error - error message regarding the last attempt to change the barring of instant personal alerts (null if the attempt was successful or if notification is sent to an application that did not trigger the attempt)

processPrimarySessionChanged

public void processPrimarySessionChanged(boolean marked, String error, PoCSession session)

Delivers notification regarding changes of the marking of a session as primary session. This is a global attribute of the PoC engine shared by all applications using the engine. Parameters:

marked - flag indicating if any session is currently marked as primary error - error message regarding the last attempt to change the marking of the session as primary session (null if the attempt was successful or if notification is sent to an application that did not trigger the attempt) session - the session currently marked as primary session ( null if none is marked or if the session that is marked does not belong to the application)

Service API

153

processForegroundSessionChanged

public void processForegroundSessionChanged(boolean marked, String error, PoCSession session)

Delivers notification regarding changes of the marking of a session as foreground session. This is a global attribute of the PoC engine shared by all applications using the engine. Parameters:

marked - flag indicating if any session is currently marked as foreground session error - error message regarding the last attempt to change the marking of the session as forground session (null if the attempt was successful or if notification is sent to an application that did not trigger the attempt) session - the session that is currently marked as foreground session (null if none is marked or if the session that is currently marked as foreground session does not belong to the application)

processLockingChanged

public void processLockingChanged(boolean locked, String error, PoCSession session)

Delivers notification regarding changes of locking to a session. This is a global attribute of the PoC engine shared by all applications using the engine. Parameters:

locked - flag indicating if any session is currently locked to error - error message regarding the last attempt to lock to the session (null if the attempt was successful or if notification is sent to an application that did not trigger the attempt) session - the session that is currently locked to (null if none is locked to or if the session that is currently locked to does not belong to the application)

Interface PoCChatSession javax.microedition.ims.service.poc


public interface PoCChatSession extends PoCSession

Interface PoCChatSession that extends interface PoCSession provides methods for manipulation of PoC chat sessions with open or restricted groups. Instances of PoCChatSession are created by the PoC service (PoCService) upon invocation of the method createChatSession() by the application or upon an incoming invitation to participate in a chat session sent by another

Service API

154

participant of that session.

A PoCChatSession instance always starts in sub state DISCONNECTED of state OPERATIONAL. A chat session is always initiated by the PoC Server; a PoC User cannot initiate chat sessions but can only join a chat session or leave a chat session. Thus, a transition from state DISCONNECTED to state CONNECTED can be effected only in one way: A join request issued by the application puts the session into the transient state JOINING from which a transition to state CONNECTED is made upon reception of a "Join accepted" notification. A "Join rejected" notification puts the session back to DISCONNECTED state. A join request is rejected by the PoC server if the authorization policy specified for that group does not allow the user to join the session; otherwise the join reuqest is accepted. The application can indicate that the session instance is no longer required by issuing a

Service API

155

close request that causes a transition to state TERMINATED. Transitions to state TERMINATED can be effected from all sub states of state OPERATIONAL. Being in state TERMINATED indicates that the session instance can be garbage collected or reused if necessary.

Field Summary Page

int TYPE_OPEN Constant representing session type OPEN. 3

int TYPE_RESTRICTED Constant representing session type RESTRICTED. 3

Method Summary Page

int getType() This method returns the type of the chat group. 3

Field Detail

TYPE_RESTRICTED

public static final int TYPE_RESTRICTED

Constant representing session type RESTRICTED.

TYPE_OPEN

public static final int TYPE_OPEN

Constant representing session type OPEN.

Method Detail

getType

public int getType()

This method returns the type of the chat group. Specified by:

getType in interface PoCSession Returns:

int type of chat group (TYPE_RESTRICTED or TYPE_OPEN)

Service API

156

Interface PoCGroup javax.microedition.ims.service.poc

All Superinterfaces: Group, Synchronizable

public interface PoCGroup extends Group

Interface PoCGroup provides access to attributes PoC used for establishment of PoC chat sessions or PoC prearranged sessions. A PoC Group accepts only entries and external members. As the XDM Shared Group document as well as the PoC XDM document both describe PoC groups in the same way, interface PoCGroup has been set as an alias to interface Group). More detailed documentation can be found there.

Field Summary Page

int TYPE_CHAT_OPEN Constant representing an open chat group type 3

int TYPE_CHAT_RESTRICTED Constant representing a restricted chat group type 3

int TYPE_PREARRANGED Constant representing an prearranged group type 3

Method Summary Page

int getGroupType() This method returns the type of the PoC group 3

void setGroupType(int type) This method sets the type of the PoC group 3

Field Detail

TYPE_CHAT_OPEN

public static final int TYPE_CHAT_OPEN

Constant representing an open chat group type

TYPE_CHAT_RESTRICTED

public static final int TYPE_CHAT_RESTRICTED

Constant representing a restricted chat group type

Service API

157

TYPE_PREARRANGED

public static final int TYPE_PREARRANGED

Constant representing an prearranged group type

Method Detail

setGroupType

public void setGroupType(int type)

This method sets the type of the PoC group Parameters:

type - of the group

getGroupType

public int getGroupType()

This method returns the type of the PoC group Returns:

type of the group

Interface PoCParticipantListener javax.microedition.ims.service.poc

public interface PoCParticipantListener

Interface PoCParticipantListener provides methods for notification of participant information updates. The methods are being invoked by the PoC engine upon reception of a participant information update. A PoCParticipantListener is registered at a PocSession instance by invoking method setParticipantListener. Upon invocation of that method, the Poc engine sends a subscription for participant information updates for the respective session to the PoC server. The subscription can be cancelled by invoking method setParticipantListener of the respective session instance with the listener parameter set to null.

Method Summary Page

void processUpdate(PoCSession session, String userURI, boolean joined) Notifies changes regarding participation of a user in the PoC session the listener

is registered with. 3

Service API

158

Method Detail

processUpdate

public void processUpdate(PoCSession session, String userURI, boolean joined)

Notifies changes regarding participation of a user in the PoC session the listener is registered with. Parameters:

session - the PoC session which the participant information update applies to userURI - the URI of the user that the participant information update applies to joined - a flag indicating whether the user joined or left the PoC session (true if the user joined, false otherwise)

Interface PoCPrearrangedSession javax.microedition.ims.service.poc


public interface PoCPrearrangedSession extends PoCSession

Interface PoCPrearrangedSession that extends interface PoCSession provides methods for manipulation of prearranged sessions with predefined groups of users. Instances of PoCPrearrangedSession are created by the PoC service (PoCService) upon invocation of the method createPrearrangedSession() by the application or upon an incoming invitation to participate in a prearranged session sent by another participant of that session. The state machine for a prearranged session is shown in PoCSession. Participation of user in a prearranged session is rejected by the PoC server if the authorization policy fo the respective PoC group does not authorize the user to particpate.

Field Summary Page

int MODEL_ONE_TO_MANY 1-to-many session model constant. 3

int MODEL_ONE_TO_MANY_TO_ONE 1-to-many-to-1 session model constant. 3

int ROLE_DISTINGUISHED Constant decribing the role "Distinguished Participant". 3

int ROLE_ORDINARY Constant decribing the role "Ordinary Participant". 3

Service API

159

Method Summary Page

void accept() This method allows accepting an invitation to participate in a prearranged

session. 3

void cancel() This method is used to cancel a pending session initiation. 3

int getModel() This method is used to query the session model of the current session. 3

int getRole() This method returns the role that the user has in the session. 3

void invite(int sessionModel, boolean manualAnswerOverrideFlag) This method is used to initiate a prearranged session (either a 1-to-many or a 1-

to-many-to-1 session) with members of the group associated with the session instance.

3

void inviteUser(String userURI, boolean manualAnswerOverrideFlag) This method is used to invite a user to participate in an ongoing prearranged

session. 3

void reject() This method allows rejecting an invitation to participate in a prearranged session. 3

Field Detail

MODEL_ONE_TO_MANY

public static final int MODEL_ONE_TO_MANY

1-to-many session model constant.

MODEL_ONE_TO_MANY_TO_ONE

public static final int MODEL_ONE_TO_MANY_TO_ONE

1-to-many-to-1 session model constant.

ROLE_DISTINGUISHED

public static final int ROLE_DISTINGUISHED

Constant decribing the role "Distinguished Participant".

Service API

160

ROLE_ORDINARY

public static final int ROLE_ORDINARY

Constant decribing the role "Ordinary Participant".

Method Detail

getModel

public int getModel()

This method is used to query the session model of the current session. The return value indicates whether the session is a 1-to-many or 1-to-many-to-1 prearranged session. Returns:

int the session model (MODEL_ONE_TO_MANY or MODEL_ONE_TO_MANY_TO_ONE)

getRole

public int getRole()

This method returns the role that the user has in the session. The user may either be the Distinguished Participant (ROLE_DISTINGUISHED)or an Ordinary Participant (ROLE_ORDINARY)user. When using session model MODEL_ONE_TO_MANY_TO_ONE exactly one participant of the session will be a Distinguished Participant; all other participants of the session will be Ordinary Participants. In session model MODEL_ONE_TO_MANY all particpants are Ordinary Participants. Returns:

int specifying the role of the user

invite

public void invite(int sessionModel, boolean manualAnswerOverrideFlag) throws IllegalStateException, IllegalArgumentException, SecurityException

This method is used to initiate a prearranged session (either a 1-to-many or a 1-to-many-to-1 session) with members of the group associated with the session instance. The method takes two parameters: the session model parameter specifies whether a 1-to-many or 1-to-many-to-1 session should be initiated; the manual answer override flag indicates that if manual answer mode has been set by the receiving party it should be ignored (if the user has sufficient rights). Parameters:

sessionModel - one of the two possible session models (MODEL_ONE_TO_MANY or MODEL_ONE_TO_MANY_TO_ONE) manualAnswerOverrideFlag - if true manual answer mode will be overridden

Service API

161

Throws: IllegalStateException - if session instance is not in state DISCONNECTED IllegalArgumentExceptionException - if session model constant is not valid SecurityException - if permission is not granted

inviteUser

public void inviteUser(String userURI, boolean manualAnswerOverrideFlag) throws IllegalStateException, IMSMalformedURIException, SecurityException

This method is used to invite a user to participate in an ongoing prearranged session. In 1-to-many communication mode, any participant of the prearranged session may invite another user, whereas in 1-to-many-to-1 communication mode, only the Distinguished Participant may invite another user. The method takes two parameters: the URI specifies which user should be invited; the manual answer override flag indicates that the manual answer mode setting of the receiving party should be ignored (if the user has sufficient rights). The invitation is rejected if the invited party is listed in the reject list of the group or if the invited party rejects the invitation. Parameters:

userURI - URI of the user that is invited manualAnswerOverrideFlag - if set to true manual answer mode will be overridden

Throws: IllegalStateException - if session instance is not in state CONNECTED or if in 1-to-many-t-1 mode an Ordinary Participant tries to invite another user IMSMalformedURIException - if URI is malformed SecurityException - if permission is not granted

accept

public void accept() throws IllegalStateException, SecurityException

This method allows accepting an invitation to participate in a prearranged session. Throws:


reject

public void reject() throws IllegalStateException, SecurityException

This method allows rejecting an invitation to participate in a prearranged session.

Service API

162

Throws: IllegalStateException - if session is not in state INVITED SecurityException - if permission is not granted

cancel

public void cancel() throws IllegalStateException, SecurityException

This method is used to cancel a pending session initiation. Throws:

IllegalStateException - if session is not in state INVITING SecurityException - if permission is not granted

Interface PoCService javax.microedition.ims.service.poc


public interface PoCService extends ImsService

Interface PoCService is an extension of IMSService that acts as a factory for all instances of sessions, groups, policies und rules owned by a particular public user ID. PoCService also acts as a registry for those entities. It is created via the createService() method of IMSManager if the proper application ID for the PoC service is used.

Method Summary Page

void barSessions(boolean personalAlert, boolean sessionRequest) Method to bar and unbar personal alerts and incoming sessions. 3

PoCAdhocSession createAdhocSession(String groupURI) Creates an ad-hoc PoC group session in DISCONNECTED state. 3

PoCAdhocSession createAdhocSession(String[] userURIs) Creates an ad-hoc PoC group session in DISCONNECTED state. 3

PoCChatSession createChatSession(String groupURI) Creates a chat PoC group session in DISCONNECTED state. 3

PoCGroup createGroup(String groupURI, String docURI, int type) Creates a PoC group instance on the client. 3

PoCPrearrangedSession createPrearrangedSession(String groupURI) Creates a prearranged PoC group session in DISCONNECTED state. 3

Service API

163

String[] getConfigParameterNames() Returns the names of available configuration parameters to be used

with method getConfigParameterValue(). 3

String getConfigParameterValue(String name) Returns the value of the configuration parameter specified by name. 3

PoCSession getForegroundSession() Returns the PoC session marked as foreground session. 3

PoCGroup getGroup(String documentURI) Returns the PoC group instance associated with the specified

document URI. 3

PoCGroup[] getGroups() Returns a list of all PoC groups that are locally available on the client

for the public user ID associated with the service. 3

PoCSession getLockedSession() Returns the PoC session that the device is currently locked to. 3

PoCSession getPrimarySession() Returns the PoC session marked as primary session. 3

PoCSession getSession(String groupURI) Returns the PoC session instance associated with the specified group

URI. 3

PoCSession[] getSessions() Returns a list of all PoC sessions that are in OPERATIONAL state. 3

PoCUserAccessPolicy getUserAccessPolicy() Returns the PoC user access policy for the public user ID associated

with the service. 3

boolean isAllMuted() Returns true if device is muted, false otherwise. 3

boolean isPersonalAlertBarred() Returns the true if incoming Instant Personal Alerts are barred. 3

boolean isSessionRequestBarred() Returns the true if incoming session requests are barred. 3

void lockToSession(PoCSession session) Locks to a PoC session (global state of the PoC engine). 3

void muteAll(boolean muted) Method is used to mute all PoC sessions on the device. 3

void sendGroupAdvertisement(String recipientURI, String groupURI, String groupName, String description)

Sends a PoC group advertisement to a user or a group. 3

void sendInstantPersonalAlert(String recipientURI, String subject, String message)

This method allows sending of a personal alert to another user. 3

void setAttributeListener(PoCAttributeListener listener) Registers an attribute listener. 3

Service API

164

void setForegroundSession(PoCSession session) Marks a PoC session to be used for sending talk bursts (global state

of the PoC engine). 3

void setPrimarySession(PoCSession session) Marks a PoC session as primary session (global state of the PoC

engine). 3

void setServiceListener(PoCServiceListener listener) Registers a session listener. 3

Method Detail

createGroup

public PoCGroup createGroup(String groupURI, String docURI, int type) throws IMSMalformedURIException, IMSObjectExistsException, IllegalArgumentException, SecurityException

Creates a PoC group instance on the client. If a corresponding PoC Group document exists on the XDM Server, an update request is issued, causing a transition to state UPDATING as specified for interface Synchronizable. If the respective PoC Group document does not exist in the server, a request to create an empty PoC Group document is issued. While that request is being processed on the server, the PoC group instance waits for confirmation of completion of the request. As soon as that confirmation arrives, a transition to state STABLE is performed and method processSynchronized() is invoked (see SynchronizationListener). Parameters:

groupURI - URI of the PoC group docURI - URI of the XDM document type - type of the PoC group (may be one of PocGroup.TYPE_CHAT_OPEN, PocGroup.TYPE_CHAT_RESTRICTED, PocGroup.TYPE_PREARRANGED

Returns: Instance of class PoCGroup

Throws: IMSMalformedURIException - if any URI is malformed IMSObjectExistsException - if a group instance for the URI already exists IllegalArgumentException - if type is invalid SecurityException - if permission is not granted

createChatSession

public PoCChatSession createChatSession(String groupURI) throws IMSMalformedURIException, IMSObjectExistsException

Creates a chat PoC group session in DISCONNECTED state.

Service API

165

Parameters: groupURI - URI of the chat group to be invited for the PoC session

Returns: instance of class PoCChatSession

Throws: IMSMalformedURIException - if any URI is malformed IMSObjectExistsException - if a session object for the group URI already exists

createPrearrangedSession

public PoCPrearrangedSession createPrearrangedSession(String groupURI) throws IMSMalformedURIException, IMSObjectExistsException

Creates a prearranged PoC group session in DISCONNECTED state. Parameters:

groupURI - URI of the prearranged group to be invited for the PoC session Returns:

instance of class PoCPrearrangedSession Throws:

IMSMalformedURIException - if any URI is malformed IMSObjectExistsException - if a session object for the URI already exists

createAdhocSession

public PoCAdhocSession createAdhocSession(String groupURI) throws IMSMalformedURIException, IMSObjectExistsException

Creates an ad-hoc PoC group session in DISCONNECTED state. Parameters:

groupURI - the ID of the transient group associated with an ongoing ad-hoc PoC group session

Returns: instance of class PoCAdhocSession

Throws: IMSMalformedURIException - if any URI is malformed IMSObjectExistsException - if a session instance for the URI already exists

createAdhocSession

public PoCAdhocSession createAdhocSession(String[] userURIs) throws IMSMalformedURIException

Creates an ad-hoc PoC group session in DISCONNECTED state. Parameters:

userURIs - list of users to be invited to the ad-hoc PoC session Returns:

instance of class PoCAdhocSession

Service API

166

Throws: IMSMalformedURIException - if any of the user URIs is malformed

sendGroupAdvertisement

public void sendGroupAdvertisement(String recipientURI, String groupURI, String groupName, String description) throws IMSMalformedURIException, SecurityException

Sends a PoC group advertisement to a user or a group. Parameters:

recipientURI - URI of the user or group the advertisement is sent to groupURI - URI of the group to be advertised groupName - name of the group to be advertised description - description of the group to be advertised

Throws: IMSMalformedURIException - if any of the URIs is malformed SecurityException - if permission not granted

sendInstantPersonalAlert

public void sendInstantPersonalAlert(String recipientURI, String subject, String message) throws IMSMalformedURIException, SecurityException

This method allows sending of a personal alert to another user. It is NOT possible to send a personal alert to the URI of a group; if done so it will be ignored. Parameters:

recipientURI - URI of the user the instant personal alert is sent to subject - subject of the instant personal alert, may be set to null message - message text of the instant personal alert, may be set to null

Throws: IMSMalformedURIException - if any URI is malformed SecurityException - if permission is not granted

muteAll

public void muteAll(boolean muted) throws SecurityException

Method is used to mute all PoC sessions on the device. This is an asynchronous operation; therefore, feeedback from the server is provided via call back method processMuteStateChanged). Parameters:

muted - mute state (true if muted, false otherwise)

Service API

167

Throws: SecurityException - if permission is not granted

isAllMuted

public boolean isAllMuted()

Returns true if device is muted, false otherwise. Returns:

trueif devices is muted, false otherwise

isPersonalAlertBarred

public boolean isPersonalAlertBarred()

Returns the true if incoming Instant Personal Alerts are barred. Returns:

trueif incoming Instant Personal Alerts are barred, false otherwise

isSessionRequestBarred

public boolean isSessionRequestBarred()

Returns the true if incoming session requests are barred. Returns:

trueif incoming session requests are barred, false otherwise

barSessions

public void barSessions(boolean personalAlert, boolean sessionRequest) throws SecurityException

Method to bar and unbar personal alerts and incoming sessions. This is an asynchronous operation; therefore, feeedback from the server is provided via call back method processSessionBarringChanged). Parameters:

personalAlert - true if personal alert should be barred; if this parameter is set to false and personal alert is currently barred it will be unbarred sessionRequest - true if session request should be barred if this parameter is set to false and incoming session is currently barred it will be unbarred


Service API

168

setPrimarySession

public void setPrimarySession(PoCSession session) throws IllegalStateException, SecurityException

Marks a PoC session as primary session (global state of the PoC engine). Only one session can be marked as primary session at a time. A primary session is always preferred from any other PoC session: When a talk burst arrives for a primary session, playout of that talk burst disrupts playout of any other talk burst. If a session is used as primary the session that has been previously marked as primary is automatically unmarked. If the session parameter is set to null, no session is used as primary session. This is an asynchronous operation; therefore, feeedback from the server is provided via call back method processPrimarySessionChanged). Parameters:

session - PoC session to be used as primary session Throws:

IllegalStateException - if PoC session is not in connected state SecurityException - if permission is not granted

getPrimarySession

public PoCSession getPrimarySession()

Returns the PoC session marked as primary session. If no session associated with the application is currently marked as primary, null is returned. Returns:

session currently marked as primary session

setForegroundSession

public void setForegroundSession(PoCSession session) throws IllegalStateException, SecurityException

Marks a PoC session to be used for sending talk bursts (global state of the PoC engine). That session is called foreground session. Only one session can be marked AS foreground session at a time. If a session is marked as foreground session the session that has been previously marked is automatically unmarked. If the session parameter is set to null, the session currently marked as foreground session is unmarked. This is an asynchronous operation; therefore, feeedback from the server is provided via call back method processForegroundSessionChanged). Parameters:

session - PoC session to be marked as foreground session Throws:

IllegalStateException - if the PoC session is not in connected state SecurityException - if permission is not granted

Service API

169

getForegroundSession

public PoCSession getForegroundSession()

Returns the PoC session marked as foreground session. If no session associated with the application is currently marked as foreground session null is returned. Returns:

session currently marked as foreground session

lockToSession

public void lockToSession(PoCSession session) throws IllegalStateException, SecurityException

Locks to a PoC session (global state of the PoC engine). As long as the lock is retained talk bursts are sent and received only via that session. All other sessions are muted. Other markings of sessions (as primary session, as foreground session) are ignored as long as the lock is being retained. Only one session can be locked to at a time. If a session is being locked to the session that has been previously locked to is automatically unlocked. If the session parameter is set to null, an existing lock to a session is released. This is an asynchronous operation; therefore, feeedback from the server is provided via call back method processLockingChanged). Parameters:

session - PoC session to be locked to Throws:

IllegalStateException - if PoC session is not in connected state SecurityException - if permission is not granted

getLockedSession

public PoCSession getLockedSession()

Returns the PoC session that the device is currently locked to. If no session associated with the application is currently locked to, null is returned. Returns:

PoC session currently locked to

getGroup

public PoCGroup getGroup(String documentURI) throws IMSMalformedURIException, SecurityException

Returns the PoC group instance associated with the specified document URI. If no such group instance exists, null is returned. Parameters:

documentURI - documentURI identifying the group document

Service API

170

Returns: PoC group or null if group does not exist

Throws: IMSMalformedURIException - if document URI is malformed SecurityException - if permission is not granted

getGroups

public PoCGroup[] getGroups()

Returns a list of all PoC groups that are locally available on the client for the public user ID associated with the service. Returns:

list of all PoC locally available groups

getSession

public PoCSession getSession(String groupURI) throws IMSMalformedURIException

Returns the PoC session instance associated with the specified group URI. If no such session instance exists, null is returned. Parameters:

groupURI - URI identifying the session group Returns:

PoC session Throws:

IMSMalformedURIException - if group URI is malformed

getSessions

public PoCSession[] getSessions()

Returns a list of all PoC sessions that are in OPERATIONAL state. Returns:

list of all PoC sessions

getUserAccessPolicy

public PoCUserAccessPolicy getUserAccessPolicy() throws SecurityException

Returns the PoC user access policy for the public user ID associated with the service. If no policy document exists on the server, an empty default policy document is returned. Upon comittment of this policy document using Synchronizable.submit(), a respective document is created on the server.

Service API

171

Returns: PoC user access policy


setAttributeListener

public void setAttributeListener(PoCAttributeListener listener)

Registers an attribute listener. If another attribute listener had been registered previoulsy, it is overwritten. Parameters:

listener - instance of PocAttributeListener

setServiceListener

public void setServiceListener(PoCServiceListener listener)

Registers a session listener. If another session listener had been registered previoulsy, it is overwritten. Parameters:

listener - instance of PoCServiceListener

getConfigParameterNames

public String[] getConfigParameterNames()

Returns the names of available configuration parameters to be used with method getConfigParameterValue(). For details see OMA-POC-AC-20050805-C.txt and PoC DM MO(?) Returns:

list of configuration parameter names

getConfigParameterValue

public String getConfigParameterValue(String name)

Returns the value of the configuration parameter specified by name. Parameters:

name - name of configuration parameter to be accessed Returns:

value of configuration parameter, may be null if parameter is not defined or value is not available.

Service API

172

Interface PoCServiceListener javax.microedition.ims.service.poc

public interface PoCServiceListener

Interface PoCServiceListener that has to be implemented by the PoC application provides methods for notification of incoming session requests, instant personal alerts or group advertisments. The methods are being invoked by the PoC engine upon reception of a session request or an instant personal alert. A PoCServiceListener is registered at the PoCService instance by invoking method setSessionListener.

Method Summary Page

void processAdhocSession(String userURI, PoCAdhocSession session, boolean accepted)

Notifies an incoming request to participate in an ad-hoc PoC group session. 3

void processGroupAdvertisment(String userURI, String groupURI, String groupName, String description)

Notifies an incoming PoC group advertisement. 3

void processPersonalAlert(String userURI, String subject, String message) Notifies an incoming instant personal alert. 3

void processPrearrangedSession(String userURI, PoCPrearrangedSession session, boolean accepted)

Notifies an incoming request to participate in a prearranged PoC group session. 3

Method Detail

processPrearrangedSession

public void processPrearrangedSession(String userURI, PoCPrearrangedSession session, boolean accepted)

Notifies an incoming request to participate in a prearranged PoC group session. Parameters:

userURI - URI of the user that issued the request session - session instance providing access to the PoC session accepted - flag indicating if the request has already been accepted automatically (due to automatic answer mode or manual answer override)

processAdhocSession

public void processAdhocSession(String userURI, PoCAdhocSession session, boolean accepted)

Service API

173

Notifies an incoming request to participate in an ad-hoc PoC group session. Parameters:

userURI - URI of the user that issued the request session - session instance providing access to the PoC session accepted - flag indicating if the request has already been accepted automatically (due to automatic answer mode or manual answer override)

processPersonalAlert

public void processPersonalAlert(String userURI, String subject, String message)

Notifies an incoming instant personal alert. Parameters:

userURI - URI of the user that issued the instant personal alert subject - subject of the instant personal alert, may be null message - message text of the instant personal alert, may be null

processGroupAdvertisment

public void processGroupAdvertisment(String userURI, String groupURI, String groupName, String description)

Notifies an incoming PoC group advertisement. Parameters:

userURI - URI of the user that issued the advertisement groupURI - URI of the advertised PoC group groupName - display name of the advertised PoC group description - description of the advertised PoC group

Interface PoCSession javax.microedition.ims.service.poc

All Known Subinterfaces: PoCAdhocSession, PoCChatSession, PoCPrearrangedSession

public interface PoCSession

Interface PoCSession specifies all methods common to all three flavours of PoC sessions. The interfaces PoCChatSession, PoCPrearrangedSession and PoCAdhocSession are extensions of interface PoCSession. Whereas PoCSession can not be instantiated directly, instances of the derived types of PoCSession are exclusively created by the PoC service (PoCService) upon invocation of one of the session creation factory methods (createChatSession,

Service API

174

createPrearrangedSession, createAdhocSession) or upon an incoming invitation to participate in a PoC session.

The three flavors of PoC sessions exhibit strong commonalities in their state models. Upon creation each session starts in state OPERATIONAL. This state has several sub states the majority of which is common to all three flavors of PoC sessions. When entering state OPERATIONAL the session always starts in sub state DISCONNECTED. Various events can trigger transitions into sub state CONNECTED. The state model shown in the diagram below represents the states and transitions of a PoCPrearrangedSession. The state models for PoCChatSession and PoCAdhocSession are variations of that state model that either do not contain all transitions / states (PoCChatSession) or have additional restrictions for certain transitions (PoCAdhocSession). In the following, all states and transitions of the state model shown below are discussed in a generic way. Characteristics that are specific for particular flavors of PoC sessions are explained in the respective sections of the document.

Service API

175

As indicated a transition to state CONNECTED can be effected in three different ways:

• A 'join' request issued by the application puts the session into the transient state JOINING from which a transition to state CONNECTED is made upon reception of a 'Join accepted' notification. A 'Join rejected' notification puts the session back to state DISCONNECTED.

• An 'invite' request is forwarded to the PoC server by the PoC engine which sends individual 'invite' requests to all members of the respective group (or the users specified at session creation in case of the ad-hoc session). By issuing an 'invite' request the application puts the session into the transient state INVITING from which a transition to state CONNECTED is made upon reception of an 'Invite accepted' notification or a 'Session ongoing' notification generated by the PoC server. An 'Invite accepted' notification is

Service API

176

generated if the PoC server accepts the session setup request. A 'Session ongoing' notification is generated if the respective session is already ongoing. An 'Invite rejected' notification generated by the PoC server puts the session back to DISCONNECTED state. A pending session initiation can also be cancelled by the application through a cancel request that puts the system back to state DISCONNECTED.

• If the PoC engine receives an incoming invitation to participate in a prearranged session, it triggers a transition from state DISCONNECTED to state INVITED if manual answer mode is set, or directly to state CONNECTED if automatic answer mode is set or if the inviting party's request to perform manual answer override has been authorized by the server. If the respective session instance does not yet exist at reception of the invitation, it is generated before making the transition. When manual answer mode is set, the application must either accept the invitation effecting a transition from state CONNECTING to state CONNECTED or reject the invitation effecting a transition to state DISCONNECTED. If the invitation has been cancelled by the inviting party, the invited party receives a 'Cancel' notification that puts the session directly into state TERMINATED.

An application participating in a prearranged session (i.e. being in state CONNECTED) can invite further participants. The application can indicate that the session instance is no longer required by issuing a close request that also causes a transition to state TERMINATED. Transitions to state TERMINATED can be effected from all sub states of state OPERATIONAL. Being in state TERMINATED indicates that the session instance can be garbage collected or reused if necessary. Any type of session offers a Talk Burst Control (TBCtrl) mechanism operational in all states except state DISCONNECTED. The state machine shown in the diagram below specifies all states and transitions required for Talk Burst Control (Talk Bursts are always being referred to by the acronym TB).

Service API

177

The Talk Burst Control (TBCtrl) state machine shown above is initialized when a session is leaving state DISCONNECTED. After initialization, the Talk Burst Control system starts in state IDLE. A 'TB Request' issued by the PoC application puts the system into transient state REQUESTING. In that state, the further behavior of the system depends on whether queuing of the 'TB request' is to be performed (i.e. queuing is supported and has not been explicitly excluded in the request).

• If queuing is not to be performed, the system waits for confirmation of the 'TB request' by the PoC server. A 'TB rejected' notification puts the system back to state IDLE whereas a 'TB confirmed' puts it into state GRANTED. By sending a 'cancel TB' request the application can put the system back to state IDLE as well. Reception of a 'TB taken' notification leaves the system in REQUESTING state.

• If queuing is to be performed, a 'TB Queue Status' notification is received triggering a transition to state QUEUED. The system stays in state QUEUED until either a transition into state GRANTED is triggered by reception of a 'TB confirmed' notification or a transition back to state IDLE is triggered by a 'cancel TB' request issued by the PoC application or upon reception of a 'TB rejected' notification. In state QUEUED, the PoC application may issue a 'TB Queue Status' request without triggering a state change. Reception of a 'TB Queue Status' notification or a 'TB taken' notification also leaves the system in QUEUED state.

In state GRANTED the system receives a 'Start Talking' notification as soon as the system is ready to transmit a Talk Burst (i.e. the connection for audio streaming is established). A transition from state GRANTED back to state IDLE is triggered either by a 'release TB' request (issued by the PoC application) or upon reception of a 'TB revoked' notification (issued by the PoC engine).

Service API

178

In state IDLE, notifications indicating that permission to send a Talk Burst has been granted to another user ('TB taken' notification) or that no user is currently entitled to send a Talk Burst ('TB idle' notification) may be received. Reception of those indications does not trigger a state change. The Talk Burst Control state machine does not have a final state as it always returns to state IDLE after completion of a Talk Burst. The state machine is finalized when the session leaves state CONNECTED upon a close request or a session termination notification.

Field Summary Page

int RC_BANNED_FROM_SESSION Reason code indicating that the administrator of the server has banned the user

from participating in the session. 3

int RC_DENIED_BY_SERVER Reason code indicating that the session setup has been denied by the server. 3

int RC_DEVICE_POLICY Reason code indicating that an action has been taken by the PoC engine

following a local device policy (e.g. power saving strategy) 3

int RC_NOT_AUTHORIZED Reason code indicating that the authorization does not allow session setup. 3

int RC_SERVER_NOT_REACHABLE Reason code indicating that the engine has lost the connection to the server. 3

int RC_TOO_MANY_USERS Reason code indicating that the session setup has been denied because the

maximum number of users has been exceeded. 3

int STATE_CONNECTED PoC Session State constant CONNECTED. 3

int STATE_DISCONNECTED PoC Session State constant DISCONNECTED. 3

int STATE_INVITED PoC Session State constant INVITED. 3

int STATE_INVITING PoC Session State constant INVITING. 3

int STATE_JOINING PoC Session State constant JOINING. 3

int STATE_TERMINATED PoC Session State constant TERMINATED. 3

int TYPE_ADHOC Type constant indicating that the PoC session is an ad-hoc session. 3

int TYPE_CHAT Type constant indicating that the PoC session is a chat session. 3

int TYPE_PREARRANGED Type constant indicating that the PoC session is a prearranged session. 3

Service API

179

Method Summary Page

void close() Closes this session and terminates all resources and network activity

associated with it. 3

String getGroupURI() This method returns the group URI associated with the session object. 3

int getIdleTime() This method returns the time in seconds since the last activity occurred

within the session. 3

String getInitiator() This method returns the URI of the initiator of the current session. 3

String getParticipants() This method returns a list of URIs of the participants of the current

session. 3

String getPrincipal() This method returns the public user id associated with the session object. 3

int getState() This method returns the state of the PoC session 3

PoCTBController getTBController() This method returns the Talk Burst Controller of a PoC session. 3

int getType() This method returns the type of the PoC session 3

boolean isMuted() This method is used to query the mute state of a PoC session. 3

void join() This method is used to join an active PoC session. 3

void mute(boolean muted) This method is used to mute an active PoC session (i.e. deactivate

transmission of incoming Talk Bursts by the PoC server). 3

void setActivityListener(PoCActivityListener listener) This method is used to set an PoCActivityListener for the session. 3

void setParticipantListener(PoCParticipantListener listener) This method is used to set a PoCParticipantListener for the session. 3

void setSessionListener(PoCSessionListener listener) This method is used to set a PoCSessionListener for a session. 3

Field Detail

RC_DENIED_BY_SERVER

public static final int RC_DENIED_BY_SERVER

Reason code indicating that the session setup has been denied by the server.

Service API

180

RC_NOT_AUTHORIZED

public static final int RC_NOT_AUTHORIZED

Reason code indicating that the authorization does not allow session setup.

RC_TOO_MANY_USERS

public static final int RC_TOO_MANY_USERS

Reason code indicating that the session setup has been denied because the maximum number of users has been exceeded.

RC_SERVER_NOT_REACHABLE

public static final int RC_SERVER_NOT_REACHABLE

Reason code indicating that the engine has lost the connection to the server.

RC_BANNED_FROM_SESSION

public static final int RC_BANNED_FROM_SESSION

Reason code indicating that the administrator of the server has banned the user from participating in the session.

RC_DEVICE_POLICY

public static final int RC_DEVICE_POLICY

Reason code indicating that an action has been taken by the PoC engine following a local device policy (e.g. power saving strategy)

TYPE_CHAT

public static final int TYPE_CHAT

Type constant indicating that the PoC session is a chat session.

Service API

181

TYPE_PREARRANGED

public static final int TYPE_PREARRANGED

Type constant indicating that the PoC session is a prearranged session.

TYPE_ADHOC

public static final int TYPE_ADHOC

Type constant indicating that the PoC session is an ad-hoc session.

STATE_DISCONNECTED

public static final int STATE_DISCONNECTED

PoC Session State constant DISCONNECTED.

STATE_JOINING

public static final int STATE_JOINING

PoC Session State constant JOINING.

STATE_INVITING

public static final int STATE_INVITING

PoC Session State constant INVITING.

STATE_INVITED

public static final int STATE_INVITED

PoC Session State constant INVITED.

STATE_CONNECTED

public static final int STATE_CONNECTED

PoC Session State constant CONNECTED.

Service API

182

STATE_TERMINATED


PoC Session State constant TERMINATED.

Method Detail

getPrincipal

public String getPrincipal()

This method returns the public user id associated with the session object. Returns:

the associated public user id

getGroupURI

public String getGroupURI()

This method returns the group URI associated with the session object. Returns:

the groupURI

getType


This method returns the type of the PoC session Returns:

int type of the PoC session (TYPE_CHAT, TYPE_PREARRANGED or TYPE_ADHOC)

getState


This method returns the state of the PoC session Returns:

int state of the PoC session (STATE_DISCONNECTED, STATE_JOINING, STATE_INVITING, STATE_INVITED, STATE_CONNECTED or STATE_TERMINATED)

mute

public void mute(boolean muted) throws SecurityException

Service API

183

This method is used to mute an active PoC session (i.e. deactivate transmission of incoming Talk Bursts by the PoC server). Parameters:

muted - mute state true if muted, false otherwise Throws:

SecurityException - if permission is not granted

isMuted

public boolean isMuted()

This method is used to query the mute state of a PoC session. If transmission of incoming Talk Bursts by the PoC server is deactivated the method returns the boolean value true, otherwise it returns false. Returns:

true if muted, false otherwise

close

public void close() throws SecurityException

Closes this session and terminates all resources and network activity associated with it. After closing the PoCService can reuse the session instance or delete all internal references to the session instance and thus making it subject to garbage collection. Throws:


getIdleTime

public int getIdleTime()

This method returns the time in seconds since the last activity occurred within the session. If the session is not in CONNECTED state, the value -1 is returned as the idle time is then undefined. Returns:

Integer time period since last activity

getInitiator

public String getInitiator()

This method returns the URI of the initiator of the current session. In case of a chat session that has no initiator null is returned. Returns:

String the URI of the user that initiated the session

Service API

184

getTBController

public PoCTBController getTBController() throws IllegalStateException

This method returns the Talk Burst Controller of a PoC session. This method always works if the session is in state OPERATIONAL. Returns:

the Talk Burst Controller for the PoC session

getParticipants

public String getParticipants()

This method returns a list of URIs of the participants of the current session. In case the session is not active or the participants are not known because the session is not subscribed for receiving particpant information updates, null is returned. Returns:

String[] list of URIS of the users that are participating in the session

setSessionListener

public void setSessionListener(PoCSessionListener listener)

This method is used to set a PoCSessionListener for a session. This PoCSessionListener allows reception of all kinds of events regarding initiation and termination of PoC sessions, joining or leaving PoC sessions and invitation of additional participants. Parameters:

listener - listener receiving events regarding particular sessions

setParticipantListener

public void setParticipantListener(PoCParticipantListener listener)

This method is used to set a PoCParticipantListener for the session. This listener is used to receive all notifications regarding participant information updates. If the listener parameter is set to null, the subscription for participant information updates is cancelled at the PoC server. Parameters:

listener - listener receiving participant information updates

setActivityListener

public void setActivityListener(PoCActivityListener listener)

Service API

185

This method is used to set an PoCActivityListener for the session. This listener is used to receive all information regarding Talk Burst activity in a session. If the listener parameter is set to null, the subscription for session activity notifications is cancelled at the PoC server. Parameters:

listener - listener receiving activity information updates

join

public void join() throws IllegalStateException, SecurityException

This method is used to join an active PoC session. Throws:

IllegalStateException - if session instance is not in state DISCONNECTED SecurityException - if permission is not granted

Interface PoCSessionListener javax.microedition.ims.service.poc

public interface PoCSessionListener

Interface PoCSessionListener provides methods for notification of all kinds of events regarding initiation and termination of PoC sessions, joining or leaving PoC sessions and invitation of additional participants. The methods are being invoked by the PoC engine upon reception of such events from the PoC server. A PoCSessionListener is registered at a PoC Session instance by invoking method setSessionEventListener

Method Summary Page

void processCancel(PoCSession session) This method is used to notify the PoC application that a previously received

invitation from another party has been cancelled. 3

void processInviteAccepted(PoCSession session, String userURI) This method is used to notify the PoC application that the session setup has been

accepted by the PoC server. 3

void processInvited(PoCSession session) This method is used to notify the PoC application that an invitation to join a PoC

session has been received. 3

void processInviteRejected(PoCSession session, int reasonCode) This method is used to notify the PoC application that the session setup has been

rejected by the PoC server. 3

Service API

186

void processJoinAccepted(PoCSession session) This method is used to notify the PoC application that a previously sent request

to join a PoC session has been accepted. 3

void processJoinRejected(PoCSession session, int reasonCode) This method is used to notify the PoC application that a previously sent request

to join a PoC session has been rejected. 3

void processNoResponse(PoCSession session) This method is used to notify the PoC application that no response has been

received within the timeout period on a request sent earlier for a given PoC session (e.g. due to a broken connection).

3

void processSessionOngoing(PoCSession session) This method is used to notify the PoC application that a PoC session that is the

user tries to initiate already exists and that the user has been automatically joined to that session.

3

void processTerminated(PoCSession session, int reasonCode) This method is used to notify the PoC application that a PoC session has been

terminated by the PoC server. 3

Method Detail

processInvited

public void processInvited(PoCSession session)

This method is used to notify the PoC application that an invitation to join a PoC session has been received. Parameters:

session - the session instance

processCancel

public void processCancel(PoCSession session)

This method is used to notify the PoC application that a previously received invitation from another party has been cancelled. Parameters:


processInviteRejected

public void processInviteRejected(PoCSession session, int reasonCode)

This method is used to notify the PoC application that the session setup has been rejected by the PoC server.

Service API

187

Parameters: session - the session instance reasonCode - is used to describe the reason for the rejection of the session setup

processInviteAccepted

public void processInviteAccepted(PoCSession session, String userURI)

This method is used to notify the PoC application that the session setup has been accepted by the PoC server. Parameters:

session - the session instance userURI - the URI of the user that accepted the invitation

processJoinAccepted

public void processJoinAccepted(PoCSession session)

This method is used to notify the PoC application that a previously sent request to join a PoC session has been accepted. Parameters:


processJoinRejected

public void processJoinRejected(PoCSession session, int reasonCode)

This method is used to notify the PoC application that a previously sent request to join a PoC session has been rejected. Parameters:

session - the session instance reasonCode - represents the reason for the rejection

processSessionOngoing

public void processSessionOngoing(PoCSession session)

This method is used to notify the PoC application that a PoC session that is the user tries to initiate already exists and that the user has been automatically joined to that session. Parameters:


Service API

188

processTerminated

public void processTerminated(PoCSession session, int reasonCode)

This method is used to notify the PoC application that a PoC session has been terminated by the PoC server. Parameters:

session - the session instance reasonCode - represents the reason for the termination

processNoResponse

public void processNoResponse(PoCSession session)

This method is used to notify the PoC application that no response has been received within the timeout period on a request sent earlier for a given PoC session (e.g. due to a broken connection). Parameters:


Interface PoCTBController javax.microedition.ims.service.poc

public interface PoCTBController

Interface PoCTBController provides methods for issuing Talk Burst requests, querying the state of queued Talk Burst requests, cancelling Talk Burst requests, releasing a Talk Burst, setting a Talk Burst Control listener and obtaining information on the state of a Talk Burst.

Field Summary Page

int TB_PRIORITY_HIGH Talk Burst Queue Priority constant HIGH. 3

int TB_PRIORITY_NONE Talk Burst Queue Priority constant NONE. 3

int TB_PRIORITY_NORMAL Talk Burst Queue Priority constant NORMAL. 3

int TB_PRIORITY_PREEMPTIVE Talk Burst Queue Priority constant PREEMPTIVE. 3

int TB_STATE_GRANTED Talk Burst State constant GRANTED. 3

int TB_STATE_IDLE Talk Burst State constant IDLE. 3

Service API

189

int TB_STATE_QUEUED Talk Burst State constant QUEUED. 3

int TB_STATE_REQUESTING Talk Burst State constant REQUESTING. 3

Method Summary Page

void cancelTBRequest() Used to cancel a previously issued Talk Burst request. 3

PoCSession getSession() Returns the session instance associated with the Talk Burst Controller. 3

int getState() Returns the current state of the Talk Burst. 3

void requestTBQueueStatus() Requests from the server information on a queued Talk Burst request (position

and queuing priority of the request). 3

void sendTBRelease() Used to indicate that the application has completed sending a Talk Burst and

does not need control over the Talk Burst channel anymore. 3

void sendTBRequest(int priority) Used to request permission to send a Talk Burst. 3

void setTBControlListener(PoCTBControlListener listener) Used to set a Talk Burst Control listener (PoCTBControlListener) for the

session. 3

Field Detail

TB_PRIORITY_NONE

public static final int TB_PRIORITY_NONE

Talk Burst Queue Priority constant NONE.

TB_PRIORITY_NORMAL

public static final int TB_PRIORITY_NORMAL

Talk Burst Queue Priority constant NORMAL.

TB_PRIORITY_HIGH

public static final int TB_PRIORITY_HIGH

Service API

190

Talk Burst Queue Priority constant HIGH.

TB_PRIORITY_PREEMPTIVE

public static final int TB_PRIORITY_PREEMPTIVE

Talk Burst Queue Priority constant PREEMPTIVE.

TB_STATE_IDLE

public static final int TB_STATE_IDLE

Talk Burst State constant IDLE.

TB_STATE_REQUESTING

public static final int TB_STATE_REQUESTING

Talk Burst State constant REQUESTING.

TB_STATE_QUEUED

public static final int TB_STATE_QUEUED

Talk Burst State constant QUEUED.

TB_STATE_GRANTED

public static final int TB_STATE_GRANTED

Talk Burst State constant GRANTED.

Method Detail

getState


Returns the current state of the Talk Burst. Returns:

integer specifying the current state

Service API

191

sendTBRequest

public void sendTBRequest(int priority) throws IllegalStateException, IllegalArgumentException, SecurityException

Used to request permission to send a Talk Burst. The response sent by the PoC server either triggers invocation of method PocTBControlListener.processConfirmed() if the request is accepted or invocation of PoCTBControlListener.processRejected() if the request is rejected for some reason. If the request is not accepted immediately but put into the Talk Burst Reuqest queue, PocTBCtrlListener.processQueueStatus() is received. Parameters:

priority - the priority for this Talk Burst Throws:

IllegalStateException - if session instance is not in state CONNECTED or if Talk Burst state is not IDLE IllegalArgumentException - if the parameter is not valid SecurityException - if permission is not granted

sendTBRelease

public void sendTBRelease() throws IllegalStateException, SecurityException

Used to indicate that the application has completed sending a Talk Burst and does not need control over the Talk Burst channel anymore. Throws:

IllegalStateException - if session instance is not in state CONNECTED or if Talk Burst state is not GRANTED SecurityException - if permission is not granted

cancelTBRequest

public void cancelTBRequest() throws IllegalStateException, SecurityException

Used to cancel a previously issued Talk Burst request. This results in the deletion of the request in the Talk Burst request queue. Throws:

IllegalStateException - if associated session instance is not in state CONNECTED or if Talk Burst state is not QUEUED or REQUESTING SecurityException - if permission is not granted

Service API

192

requestTBQueueStatus

public void requestTBQueueStatus() throws IllegalStateException, SecurityException

Requests from the server information on a queued Talk Burst request (position and queuing priority of the request). The requested information is delivered asynchronously via a callback to PoCTBControlListener.processQueueStatus(). Throws:

IllegalStateException - if session instance is not in state CONNECTED or Talk Burst state is not QUEUED SecurityException - if permission is not granted

setTBControlListener

public void setTBControlListener(PoCTBControlListener listener)

Used to set a Talk Burst Control listener (PoCTBControlListener) for the session. This listener is used to receive all notifications related to Talk Burst Control. Parameters:

listener - listener receiving Talk Burst Control notifications

getSession

public PoCSession getSession()

Returns the session instance associated with the Talk Burst Controller. Returns:

session associated with the controller

Interface PoCTBControlListener javax.microedition.ims.service.poc

public interface PoCTBControlListener

Interface PoCTBControlListener provides methods for notification of Talk Burst Control events and for reception of information about the status of the Talk Burst Request Queue. The methods are being invoked by the PoC engine upon reception of a Talk Burst Control event. A PoCTBControlListener is registered at a PoCTBController instance by invoking method setTBControlListener

Service API

193

Method Summary Page

void processConfirmed(PoCTBController controller) Notifies the confirmation of a Talk Burst Request. 3

void processIdle(PoCTBController controller) Notifies that the Talk Burst channel of a session has become idle. 3

void processNobodyListened(PoCTBController controller) Notifies that a talk burst that had been sent by the client has not been listened to

by any session participant because the media connection had not yet been established.

3

void processQueueStatus(PoCTBController controller, int position, int priority) Notifies changes regarding pending Talk Burst requests in the Talk Burst

Request Queue. 3

void processRejected(PoCTBController controller, int reasonCode) Notifies the rejection of a Talk Burst Request. 3

void processRevoked(PoCTBController controller, int reasonCode) Notifies that a previously granted permission to issue a Talk Burst has been

revoked. 3

void processStartTalking(PoCTBController controller) Notifies that the PoC client is ready for talking. 3

void processTaken(PoCTBController controller, String userURI) Notifies that another participant has been granted permission to issue a Talk

Burst. 3

Method Detail

processConfirmed

public void processConfirmed(PoCTBController controller)

Notifies the confirmation of a Talk Burst Request. Parameters:

controller - PoC Talk Burst controller for which a Talk Burst request has been confirmed

processRejected

public void processRejected(PoCTBController controller, int reasonCode)

Notifies the rejection of a Talk Burst Request. Parameters:

controller - PoC Talk Burst controller for which a Talk Burst request has been rejected reasonCode - describes the reason for the rejection of the Talk Burst request

Service API

194

processIdle

public void processIdle(PoCTBController controller)

Notifies that the Talk Burst channel of a session has become idle. Parameters:

controller - PoC Talk Burst controller for which a Talk Burst Idle event has been delivered

processTaken

public void processTaken(PoCTBController controller, String userURI)

Notifies that another participant has been granted permission to issue a Talk Burst. Parameters:

controller - PoC Talk Burst controller for which permission to issue a Talk Burst has been granted userURI - URI of the user that has been granted permission to issue a Talk Burst

processRevoked

public void processRevoked(PoCTBController controller, int reasonCode)

Notifies that a previously granted permission to issue a Talk Burst has been revoked. Parameters:

controller - PoC Talk Burst controller for which a previously granted permission to issue a Talk Burst has been revoked reasonCode - describes the reason for the revocation of the Talk Burst request

processQueueStatus

public void processQueueStatus(PoCTBController controller, int position, int priority)

Notifies changes regarding pending Talk Burst requests in the Talk Burst Request Queue. Parameters:

controller - PoC Talk Burst controller for which a Talk Burst request is pending position - position of Talk Burst request in the Talk Burst Request Queue (The first entry in the queue has position 1.) priority - priority of Talk Burst request in the Talk Burst Request Queue

processStartTalking

public void processStartTalking(PoCTBController controller)

Service API

195

Notifies that the PoC client is ready for talking. If the application would like to send a beep in order to indicate acoustically that the talk burst is now granted then the application has to mute the microphone, send the beep and afterwards unmute the microphone again in order to avoid transmission of the beep to the other participants. Parameters:

controller - PoC Talk Burst controller which is ready for talking

processNobodyListened

public void processNobodyListened(PoCTBController controller)

Notifies that a talk burst that had been sent by the client has not been listened to by any session participant because the media connection had not yet been established. Parameters:

controller - PoC Talk Burst controller the talk burst had been sent to

Interface PoCUserAccessPolicy javax.microedition.ims.service.poc

All Superinterfaces: Synchronizable

public interface PoCUserAccessPolicy extends Synchronizable

Interface PoCUserAccessPolicy allows handling of a Poc User Access Rules document. As this client object corresponds to a XDM document residing on a server in the network, it inherits from interface Synchronizable.

Method Summary Page

String addUserAccessRule(int type) 3 PoCUserAccessRule getUserAccessRule(String id)

Returns the user access rule specified by ID. 3

String[] getUserAccessRuleIDs() Returns the IDs of all user access rules being part of the policy. 3

void removeUserAccessRule(String id) This method removes a Poc user access rule from the policy. 3

Service API

196

Method Detail

addUserAccessRule

public String addUserAccessRule(int type) throws IllegalStateException, IllegalArgumentException

Parameters: type - condition type of the rule

Returns: ID of user access rule that has been added

Throws: IllegalStateException - if the policy is not in stateMODIFIED IllegalArgumentException - if type is invalid

removeUserAccessRule

public void removeUserAccessRule(String id) throws IllegalStateException

This method removes a Poc user access rule from the policy. Parameters:

id - ID of user access rule to be removed from the policy Throws:

IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED.

getUserAccessRule

public PoCUserAccessRule getUserAccessRule(String id)

Returns the user access rule specified by ID. Parameters:

id - ID of user access rule; null if rule does not exist Returns:

user access rule

getUserAccessRuleIDs

public String[] getUserAccessRuleIDs()

Returns the IDs of all user access rules being part of the policy. Returns:

list of IDs of user access rules; empty array if there are none

Service API

197

Interface PoCUserAccessRule javax.microedition.ims.service.poc

All Superinterfaces: BasicRule

public interface PoCUserAccessRule extends BasicRule

Interface PoCUserAccessRule allows specification of a PoC user access rule. PoC user access rules are stored on a server in the network via PoCUserAccessPolicy instances. PoCUserAccessRule inherits from BasicRule which specifies various conditions shared by many different kinds of rules.

Field Summary Page

int ACTION_INVITE_ACCEPT Constant representing the ACCEPT action used for handling invitations to PoC

sessions. 3

int ACTION_INVITE_PASS Constant representing the PASS action used for handling invitations to PoC

sessions. 3

int ACTION_INVITE_REJECT Constant representing the REJECT action used for handling invitations to PoC

sessions. 3

Method Summary Page

int getAllowInvite() Returns the action asscoiated with the rule 3

void setAllowInvite(int action) This methods allows specification of an action to be taken when receiving an

invitation to a PoC session from any user specified in the condition part of the rule. 3

Field Detail

ACTION_INVITE_PASS

public static final int ACTION_INVITE_PASS

Constant representing the PASS action used for handling invitations to PoC sessions.

Service API

198

ACTION_INVITE_REJECT

public static final int ACTION_INVITE_REJECT

Constant representing the REJECT action used for handling invitations to PoC sessions.

ACTION_INVITE_ACCEPT

public static final int ACTION_INVITE_ACCEPT

Constant representing the ACCEPT action used for handling invitations to PoC sessions.

Method Detail

setAllowInvite

public void setAllowInvite(int action) throws IllegalArgumentException, IllegalStateException

This methods allows specification of an action to be taken when receiving an invitation to a PoC session from any user specified in the condition part of the rule. Parameters:

action - action code (may be one of ACTION_INVITE_PASS, ACTION_INVITE_REJECT, ACTION_INVITE_ACCEPT)

Throws: IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED.

getAllowInvite

public int getAllowInvite()

Returns the action asscoiated with the rule Returns:

action code

Package javax.microedition.ims.service.presence

This package defines the JSR 281 Presence API.

See: Description

Service API

199


DeviceInformation Interface DeviceInformation specfies a set of presence information elements that are typically used as presence information for a device.

3

PeerPresentity Interface PeerPresentity provides access to presence information obtained when a subscription to the respective presentity has been made.

3

PersonInformation Interface PersonInformation specfies a set of presence information elements that are typically used as presence information for a person.

3

PresenceAuthorizationPolicy Interface PresenceAuthorizationPolicy is a container for presence authorization rules.

3

PresenceAuthorizationRule

Interface PresenceAuthorizationRule provides means for specifying a particular action for handling subscription requests from particular watchers (subscription authorization rule).

3

PresenceContainer Interface PresenceContainer servces as container for presence information.

3

PresenceInformation Interface PresenceInformation specfies a set of methods and attributes used for storing, modifiying and retrieving presence information.

3

PresenceList Interface PresenceList specifies methods to get and manipulate information on presentities that a user can make a subscription to.

3

PresenceProfile Interface PresenceProfile provides methods for accessing the content of a presence profile.

3

PresenceService

Interface PresenceService is an extension of IMSService that acts as a factory for all instances of presentities, subscriptions, policies and rules, presence profiles and presence lists owned by a particular public user ID.

3

Presentity Interface Presentity provides means to manage and publish presence information and related documents for a particular public user ID, device ID or service ID.

3

PresentityListener Interface PresentityListener provides methods for notifications associated with publication of presence data. requests.

3

ServiceInformation Interface ServiceInformation specfies a set of presence information elements that are typically used as presence information for a service.

3

Service API

200

Subscription Interface Subscription provides means to manipulate and perform subscriptions for a particular target and manage related data.

3

SubscriptionListener

Interface SubscriptionListener provides methods for notifications associated with subscriptions to other users' presence data and a method for notification of incoming subscription notifications regarding a user's presence data.

3

Package javax.microedition.ims.service.presence Description

This package defines the JSR 281 Presence API. The following diagrams illustrate the architecture of the Presence API.

Service API

201

Service API

202



Service API

203

Figure 3: Presence Factory (class PresenceManager) and its products

Interface DeviceInformation javax.microedition.ims.service.presence

All Superinterfaces: PresenceInformation

public interface DeviceInformation extends PresenceInformation

Interface DeviceInformation specfies a set of presence information elements that are typically used as presence information for a device. The constants are to be used as names of presence information elements that can be retrieved by method getElement.

Service API

204

Field Summary Page

String IDENTITY_LOCATION_INFO Constant specifying name of element 3

String IDENTITY_NETWORK_AVAILABILITY Constant specifying name of element 3

String IDENTITY_USAGE_RULES Constant specifying name of element 3

String NOTE Constant specifying name of element 3

String TIMESTAMP Constant specifying name of element 3

Method Summary Page

String getDeviceID() Returns value of attribute 'id' of element 3

Field Detail

IDENTITY_NETWORK_AVAILABILITY

public static final String IDENTITY_NETWORK_AVAILABILITY

Constant specifying name of element

IDENTITY_LOCATION_INFO

public static final String IDENTITY_LOCATION_INFO


IDENTITY_USAGE_RULES

public static final String IDENTITY_USAGE_RULES


TIMESTAMP

public static final String TIMESTAMP


Service API

205

NOTE

public static final String NOTE


Method Detail

getDeviceID

public String getDeviceID()

Returns value of attribute 'id' of element Returns:

id of device

Interface PeerPresentity javax.microedition.ims.service.presence

All Superinterfaces: PresenceContainer

public interface PeerPresentity extends PresenceContainer

Interface PeerPresentity provides access to presence information obtained when a subscription to the respective presentity has been made. The presence information in the presentity is updated automatically when a respective notification is obtained from the Presence server.

Interface PersonInformation javax.microedition.ims.service.presence


public interface PersonInformation extends PresenceInformation

Interface PersonInformation specfies a set of presence information elements that are typically used as presence information for a person. The constants are to be used as names of presence information elements that can be retrieved by method getElement.

Service API

206

Field Summary Page

String ACTIVITIES Constant specifying name of element 3

String LOCATION_INFO Constant specifying name of element 3

String MOOD Constant specifying name of element 3

String NOTE Constant specifying name of element 3

String OVERIDING_WILLINGNESS Constant specifying name of element 3

String PLACE_TYPE Constant specifying name of element 3

String STATUS_ICON Constant specifying name of element 3

String TIME_OFFSET Constant specifying name of element 3


String USAGE_RULES Constant specifying name of element 3

Method Summary Page

String getPersonID() Returns value of attribute 'id' of element 3

Field Detail

OVERIDING_WILLINGNESS

public static final String OVERIDING_WILLINGNESS


ACTIVITIES

public static final String ACTIVITIES


Service API

207

PLACE_TYPE

public static final String PLACE_TYPE


TIME_OFFSET

public static final String TIME_OFFSET


MOOD

public static final String MOOD


STATUS_ICON

public static final String STATUS_ICON


LOCATION_INFO

public static final String LOCATION_INFO


USAGE_RULES

public static final String USAGE_RULES


TIMESTAMP



Service API

208

NOTE

public static final String NOTE


Method Detail

getPersonID

public String getPersonID()

Returns value of attribute 'id' of element Returns:

id of person

Interface PresenceAuthorizationPolicy javax.microedition.ims.service.presence


public interface PresenceAuthorizationPolicy extends Synchronizable

Interface PresenceAuthorizationPolicy is a container for presence authorization rules. As this client object corresponds to a XDM document residing on the Persence server in the network, it inherits from interface Synchronizable.

Method Summary Page

String addAuthorizationRule(int type) Adds a presence authorization rule to the policy. 3

PresenceAuthorizationRule getAuthorizationRule(String id) Returns the presence authorization rule specified by ID. 3

String[] getAuthorizationRuleIDs() Returns the IDs of all presence authorization rules being part of

the policy. 3

void removeAuthorizationRule(String id) Removes the authorization rule specified by ID from the policy. 3

Service API

209

Method Detail

addAuthorizationRule

public String addAuthorizationRule(int type) throws IllegalStateException, IllegalArgumentException

Adds a presence authorization rule to the policy. Parameters:

type - condition type of the rule Returns:

ID of the rule that has been added Throws:

IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED. IllegalArgumentException - if type is invalid

removeAuthorizationRule

public void removeAuthorizationRule(String id) throws IllegalStateException

Removes the authorization rule specified by ID from the policy. Parameters:

id - ID of presence authorization rule to be removed from the policy Throws:


getAuthorizationRule

public PresenceAuthorizationRule getAuthorizationRule(String id)

Returns the presence authorization rule specified by ID. Parameters:

id - id of presence authorization rule Returns:

user access rule; null if rule does not exist

getAuthorizationRuleIDs

public String[] getAuthorizationRuleIDs()

Returns the IDs of all presence authorization rules being part of the policy. Returns:

list of IDs of presence authorization rules; empty array if there are none

Service API

210

Interface PresenceAuthorizationRule javax.microedition.ims.service.presence


public interface PresenceAuthorizationRule extends BasicRule

Interface PresenceAuthorizationRule provides means for specifying a particular action for handling subscription requests from particular watchers (subscription authorization rule). Furthermore, allowances for provisioning of presence information elements to subscribed watchers can be the specified (content authorization rule). PresenceAuthorizationRule inherits from BasicRule and thus all types of conditions specified there can be used to specify to which watchers this rule applies for. Upon generation of a PresenceAuthorizationRule, the following default settings apply:

• Subscriptions are allowed for all watchers specified in the condition part of the rule (ACTION_ALLOW)

• All devices are permitted to access presence information (TYPE_ALL_DEVICES) • All persons are permitted to access presence information (TYPE_ALL_PERSONS) • All services are permitted to access presence information (TYPE_ALL_SERVICES) • All presence information elements are provided to watchers.

Field Summary Page

int ACTION_ALLOW Constant representing the action 'subscription is allowed' 3

int ACTION_BLOCK Constant representing the action 'subscription is blocked' 3

int ACTION_CONFIRM Constant representing the action 'presentity must confirm subscription' 3

int ACTION_POLITE_BLOCK Constant representing the action 'subscription is blocked politely' 3

int ATTR_ACTIVITIES Constant representing the presence information attribute 'activities' 3

int ATTR_ALL_ATTRIBUTES Constant representing all presence attributes 3

int ATTR_BARRING_STATE Constant representing the presence information attribute 'barring-state' 3

int ATTR_GEOPRIV Constant representing the presence information attribute 'geopriv' 3

Service API

211

int ATTR_MOOD Constant representing the presence information attribute 'mood' 3

int ATTR_NETWORK_AVAILABILITY Constant representing the presence information attribute 'network-availablity' 3

int ATTR_NOTE Constant representing the presence information attribute 'note' 3

int ATTR_PLACE_TYPE Constant representing the presence information attribute 'place-type' 3

int ATTR_REGISTRATION_STATE Constant representing the presence information attribute 'registration-state' 3

int ATTR_SESSION_PARTICIPATION Constant representing the presence information attribute 'session-participation' 3

int ATTR_STATUS_ICON Constant representing the presence information attribute 'status-icon' 3

int ATTR_TIME_OFFSET Constant representing the presence information attribute 'time-offset' 3

int ATTR_UNKNOWN_ATTRIBUTE Constant representing all unknown attributes 3

int ATTR_WILLINGNESS Constant representing the presence information attribute 'willingness' 3

int TYPE_ALL_DEVICES Constant representing the permission type 'all-devices' 3

int TYPE_ALL_PERSONS Constant representing the permission type 'all-persons' 3

int TYPE_ALL_SERVICES Constant representing the permission type 'all-services' 3

int TYPE_CLASS Constant representing the permission type 'class' 3

int TYPE_DEVICE_ID Constant representing the permission type 'device-id' 3

int TYPE_OCCURENCE_ID Constant representing the permission type 'occurence-id' 3

int TYPE_SERVICE_ID Constant representing the permission type 'service-id' 3

int TYPE_SERVICE_URI Constant representing the permission type 'service-uri' 3

int TYPE_SERVICE_URI_SCHEME Constant representing the permission type 'service-uri-scheme' 3

Service API

212

Method Summary Page

void addDevicePermission(int type, String value) Adds a permission element for controlling provision of presence information

regarding devices ( element) 3

void addPersonPermission(int type, String value) Adds a permission element for controlling provision of presence information

regarding persons ( element) 3

void addServicePermission(int type, String value) Adds a permission element for controlling provision of presence information

regarding services ( element) 3

String[] getDevicePermissions(int type) Returns all values of permission elements of the specified type 3

String[] getPersonPermissions(int type) Returns all values of permission elements of the specified type 3

int[] getProvidedAttributes() Returns the attribute codes of the presence elements that are allowed to be

provided. 3

String[] getServicePermissions(int type) Returns all permission elements for controlling provision of presence

information regarding services 3

int getSubHandling() Returns the action which the server uses to handle the subscription. 3

boolean isAttributeProvided(int attr) Returns true if the presence information element specified by parameter attr is

provided to the watchers, false otherwise. 3

boolean isAttributeProvided(String name, String ns) Returns true if the presence information element specified by parameters name

and ns is provided to the watchers, false otherwise. 3

void provideAttribute(int attr, boolean provided) Changes allowance for providing a particular presence information element

specified by parameter attr. 3

void provideAttribute(String name, String ns, boolean provided) Changes allowance for providing an unknown presence information element

(i.e. a presence information element for which no ATTR_* constant exists) specified by parameters name and ns.

3

void removeDevicePermission(int type, String value) Removes a permission element for controlling provision of presence information

regarding devices ( element) 3

void removePersonPermission(int type, String value) Removes a permission element for controlling provision of presence information

regarding persons 3

Service API

213

void removeServicePermission(int type, String value) Removes a permission element for controlling provision of presence information

regarding services 3

void setSubHandling(int action) Allows setting of the action which the server uses to handle the subscription. 3

Field Detail

ACTION_BLOCK

public static final int ACTION_BLOCK

Constant representing the action 'subscription is blocked'

ACTION_CONFIRM

public static final int ACTION_CONFIRM

Constant representing the action 'presentity must confirm subscription'

ACTION_POLITE_BLOCK

public static final int ACTION_POLITE_BLOCK

Constant representing the action 'subscription is blocked politely'

ACTION_ALLOW

public static final int ACTION_ALLOW

Constant representing the action 'subscription is allowed'

TYPE_CLASS

public static final int TYPE_CLASS

Constant representing the permission type 'class'

TYPE_OCCURENCE_ID

public static final int TYPE_OCCURENCE_ID

Service API

214

Constant representing the permission type 'occurence-id'

TYPE_DEVICE_ID

public static final int TYPE_DEVICE_ID

Constant representing the permission type 'device-id'

TYPE_ALL_DEVICES

public static final int TYPE_ALL_DEVICES

Constant representing the permission type 'all-devices'

TYPE_ALL_PERSONS

public static final int TYPE_ALL_PERSONS

Constant representing the permission type 'all-persons'

TYPE_SERVICE_ID

public static final int TYPE_SERVICE_ID

Constant representing the permission type 'service-id'

TYPE_SERVICE_URI

public static final int TYPE_SERVICE_URI

Constant representing the permission type 'service-uri'

TYPE_SERVICE_URI_SCHEME

public static final int TYPE_SERVICE_URI_SCHEME

Constant representing the permission type 'service-uri-scheme'

TYPE_ALL_SERVICES

public static final int TYPE_ALL_SERVICES

Service API

215

Constant representing the permission type 'all-services'

ATTR_WILLINGNESS

public static final int ATTR_WILLINGNESS

Constant representing the presence information attribute 'willingness'

ATTR_NETWORK_AVAILABILITY

public static final int ATTR_NETWORK_AVAILABILITY

Constant representing the presence information attribute 'network-availablity'

ATTR_SESSION_PARTICIPATION

public static final int ATTR_SESSION_PARTICIPATION

Constant representing the presence information attribute 'session-participation'

ATTR_ACTIVITIES

public static final int ATTR_ACTIVITIES

Constant representing the presence information attribute 'activities'

ATTR_MOOD

public static final int ATTR_MOOD

Constant representing the presence information attribute 'mood'

ATTR_PLACE_TYPE

public static final int ATTR_PLACE_TYPE

Constant representing the presence information attribute 'place-type'

ATTR_STATUS_ICON

public static final int ATTR_STATUS_ICON

Service API

216

Constant representing the presence information attribute 'status-icon'

ATTR_TIME_OFFSET

public static final int ATTR_TIME_OFFSET

Constant representing the presence information attribute 'time-offset'

ATTR_NOTE

public static final int ATTR_NOTE

Constant representing the presence information attribute 'note'

ATTR_GEOPRIV

public static final int ATTR_GEOPRIV

Constant representing the presence information attribute 'geopriv'

ATTR_ALL_ATTRIBUTES

public static final int ATTR_ALL_ATTRIBUTES

Constant representing all presence attributes

ATTR_REGISTRATION_STATE

public static final int ATTR_REGISTRATION_STATE

Constant representing the presence information attribute 'registration-state'

ATTR_BARRING_STATE

public static final int ATTR_BARRING_STATE

Constant representing the presence information attribute 'barring-state'

ATTR_UNKNOWN_ATTRIBUTE

public static final int ATTR_UNKNOWN_ATTRIBUTE

Service API

217

Constant representing all unknown attributes

Method Detail

setSubHandling

public void setSubHandling(int action) throws IllegalArgumentException, IllegalStateException

Allows setting of the action which the server uses to handle the subscription. Parameters:

action - an action code (may be one of ACTION_BLOCK, ACTION_CONFIRM, ACTION_POLITE_BLOCK, ACTION_ALLOW)

Throws: IllegalArgumentException - if an invalid action code is specified

getSubHandling

public int getSubHandling()

Returns the action which the server uses to handle the subscription. Returns:

action code

addDevicePermission

public void addDevicePermission(int type, String value) throws IllegalArgumentException, IllegalStateException

Adds a permission element for controlling provision of presence information regarding devices ( element) Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_DEVICE_ID, TYPE_ALL_DEVICES) value - string value of the permission element (must be meaningful with regard to setting of type)

Throws: IllegalArgumentException - if an invalid type is specified IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED.

removeDevicePermission

public void removeDevicePermission(int type, String value) throws IllegalArgumentException, IllegalStateException

Service API

218

Removes a permission element for controlling provision of presence information regarding devices ( element) Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_DEVICE_ID, TYPE_ALL_DEVICES) value - string value of the permission element (must be meaningful with regard to setting of type)


getDevicePermissions

public String[] getDevicePermissions(int type) throws IllegalArgumentException

Returns all values of permission elements of the specified type Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_DEVICE_ID, TYPE_ALL_DEVICES)

Returns: list of values of permission elements


addPersonPermission

public void addPersonPermission(int type, String value) throws IllegalArgumentException, IllegalStateException

Adds a permission element for controlling provision of presence information regarding persons ( element) Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_ALL_PERSONS) value - string value of the permission element (must be meaningful with regard to setting of type)


removePersonPermission

public void removePersonPermission(int type, String value) throws IllegalArgumentException, IllegalStateException

Service API

219

Removes a permission element for controlling provision of presence information regarding persons Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_ALL_PERSONS) value - string value of the permission element (must be meaningful with regard to setting of type)


getPersonPermissions

public String[] getPersonPermissions(int type) throws IllegalArgumentException

Returns all values of permission elements of the specified type Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_ALL_PERSONS)


Throws: IllegalArgumentException - if an invalid type is specified

addServicePermission

public void addServicePermission(int type, String value) throws IllegalArgumentException, IllegalStateException

Adds a permission element for controlling provision of presence information regarding services ( element) Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_SERVICE_ID, TYPE_SERVICE_URI, TYPE_URI_SCHEME, TYPE_ALL_SERVICES) value - string value of the permission element (must be meaningful with regard to setting of type)


removeServicePermission

public void removeServicePermission(int type, String value) throws IllegalArgumentException, IllegalStateException

Service API

220

Removes a permission element for controlling provision of presence information regarding services Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_SERVICE_ID, TYPE_SERVICE_URI, TYPE_URI_SCHEME, TYPE_ALL_SERVICES) value - string value of the permission element (must be meaningful with regard to setting of type)


getServicePermissions

public String[] getServicePermissions(int type) throws IllegalArgumentException

Returns all permission elements for controlling provision of presence information regarding services Parameters:

type - type of permission element (may be one of TYPE_CLASS, TYPE_OCCURENCE_ID, TYPE_SERVICE_ID, TYPE_SERVICE_URI, TYPE_URI_SCHEME, TYPE_ALL_SERVICES)


Throws: IllegalArgumentException - if an invalid type is specified

provideAttribute

public void provideAttribute(int attr, boolean provided) throws IllegalArgumentException, IllegalStateException

Changes allowance for providing a particular presence information element specified by parameter attr. If parameter provided is set to true, the attribute is provided to the watchers specified in the condition elements; if set to false, it is retained. Parameters:

attr - attribute constant representing a particular kind of presence information element (may be one of the constants ATTR_* as specified above) provided - boolean specifying whether the specified presence attribute is to be provided

Throws: IllegalArgumentException - if an invalid attribute code is specified IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED.

provideAttribute

public void provideAttribute(String name, String ns, boolean provided) throws IllegalStateException

Service API

221

Changes allowance for providing an unknown presence information element (i.e. a presence information element for which no ATTR_* constant exists) specified by parameters name and ns. If parameter provided is set to true, the presence information element is provided to the watchers specified in the condition elements; if set to false, it is retained. Parameters:

name - unqualified element name of the unknown presence information element ns - namespace uri of the unknown presence information element provided - boolean specifying whether the specified presence attribute is to be provided


isAttributeProvided

public boolean isAttributeProvided(int attr) throws IllegalArgumentException

Returns true if the presence information element specified by parameter attr is provided to the watchers, false otherwise. Parameters:

attr - attribute constant representing a particular kind of presence information element Returns:

true if a particular presence information element is provided, false otherwise Throws:

IllegalArgumentException - if an invalid attribute code is specified

isAttributeProvided

public boolean isAttributeProvided(String name, String ns)

Returns true if the presence information element specified by parameters name and ns is provided to the watchers, false otherwise. Parameters:

name - unqualified element name of the presence information element ns - namespace uri of the presence information element

Returns: true if a particular presence information element is provided, false otherwise

getProvidedAttributes

public int[] getProvidedAttributes()

Returns the attribute codes of the presence elements that are allowed to be provided. Returns:

list of attribute codes

Service API

222

Interface PresenceContainer javax.microedition.ims.service.presence

All Known Subinterfaces: PeerPresentity, PresenceProfile, Presentity

public interface PresenceContainer

Interface PresenceContainer servces as container for presence information. It must contain exactly one set of presence information for a person and may contain several sets of presence information for services or devices.

Method Summary Page

void addDeviceInformation(String deviceID) Adds a set of presence information for a device with given device ID. 3

void addServiceInformation(String serviceID) Adds a set of presence information for a service with give service ID. 3

String[] getDeviceIDs() Returns the IDs of the devices associated with the presentity. 3

DeviceInformation getDeviceInformation(String deviceID) Returns a set of presence information regarding a device associated

with the presentity. 3

String getPersonID() Returns the ID of the user associated with the presentity. 3

PersonInformation getPersonInformation() Returns a set of presence information regarding the user associated with

the presentity. 3

String[] getServiceIDs() Returns the IDs of the services associated with the presentity. 3

ServiceInformation getServiceInformation(String serviceID) Returns a set of presence information regarding a service associated

with the presentity. 3

void removeDeviceInformation(String deviceID) Removes a set of presence information for a device with given device

ID. 3

void removeServiceInformation(String serviceID) Removes a set of presence information for a service with given service

ID. 3

Service API

223

Method Detail

getPersonID

public String getPersonID()

Returns the ID of the user associated with the presentity. Returns:

ID of person

getPersonInformation

public PersonInformation getPersonInformation()

Returns a set of presence information regarding the user associated with the presentity. Returns:

presence information regarding a person

getServiceIDs

public String[] getServiceIDs()

Returns the IDs of the services associated with the presentity. Returns:

list of service IDs

addServiceInformation

public void addServiceInformation(String serviceID) throws IllegalStateException

Adds a set of presence information for a service with give service ID. The service ID must be unique in the context of this presence container. Parameters:

serviceID - ID of service Throws:


removeServiceInformation

public void removeServiceInformation(String serviceID) throws IllegalStateException

Removes a set of presence information for a service with given service ID. If presence information does not exist for the specified service ID, the method has no effect.

Service API

224

Parameters: serviceID - ID of service


getServiceInformation

public ServiceInformation getServiceInformation(String serviceID)

Returns a set of presence information regarding a service associated with the presentity. If presence information dows not exist for the specified service ID, null>/code> is returned. Parameters:

serviceID - the ID of the service Returns:

presence information regarding a service

getDeviceIDs

public String[] getDeviceIDs()

Returns the IDs of the devices associated with the presentity. Returns:

list of device IDs

addDeviceInformation

public void addDeviceInformation(String deviceID) throws IllegalStateException

Adds a set of presence information for a device with given device ID. The device ID must be unique in the context of this presence container. Parameters:

deviceID - ID of device Throws:


removeDeviceInformation

public void removeDeviceInformation(String deviceID) throws IllegalStateException

Removes a set of presence information for a device with given device ID. If presence information does not exist for the specified device ID, the method has no effect. Parameters:

deviceID - ID of device

Service API

225


getDeviceInformation

public DeviceInformation getDeviceInformation(String deviceID)

Returns a set of presence information regarding a device associated with the presentity. If presence information dows not exist for the specified device ID, null>/code> is returned. Parameters:

deviceID - the ID of the device Returns:

presence information regarding a device

Interface PresenceInformation javax.microedition.ims.service.presence

All Known Subinterfaces: DeviceInformation, PersonInformation, ServiceInformation

public interface PresenceInformation

Interface PresenceInformation specfies a set of methods and attributes used for storing, modifiying and retrieving presence information. The constants are to be used as types of presence information that are further detailed by the interfaces PersonInformation, DeviceInformation and ServiceInformation.

Field Summary Page

int TYPE_DEVICE presentity type constant for devices 3

int TYPE_PERSON presentity type constant for persons 3

int TYPE_SERVICE presentity type constant for services 3

Method Summary Page

void addElement(Element element) Adds a presence information element to the presence information container. 3

Element getElement(String name) Returns a presence element by name. 3

String[] getElementNames() Returns the names of all presence elements in the container. 3

Service API

226

Element[] getElements() Returns all presence elements in the container. 3

String getIdentity() Returns identitfier for the presentity asscociated with the presence information

container 3

String[] getStandardElementNames() Returns the names of all standard presence elements as described in the

respective sub-interface corresponding with the value of the type attribute. 3

int getType() Returns type of presence information 3

void removeElement(Element element) Removes the specified presence element. 3

Field Detail

TYPE_PERSON

public static final int TYPE_PERSON

presentity type constant for persons

TYPE_DEVICE

public static final int TYPE_DEVICE

presentity type constant for devices

TYPE_SERVICE

public static final int TYPE_SERVICE

presentity type constant for services

Method Detail

getIdentity

public String getIdentity()

Returns identitfier for the presentity asscociated with the presence information container Returns:

identity (URI)

Service API

227

getType


Returns type of presence information Returns:

type (may be one of TYPE_PERSON, TYPE_DEVICE, TYPE_SERVICE)

addElement

public void addElement(Element element) throws IllegalStateException

Adds a presence information element to the presence information container. If an element with the same name is already present, that element is overwritten. Parameters:

element - presence information element Throws:


getElement

public Element getElement(String name)

Returns a presence element by name. Parameters:

name - name of presence element Returns:

presence element

getElementNames

public String[] getElementNames()

Returns the names of all presence elements in the container. Returns:

list of presence element names

getStandardElementNames

public String[] getStandardElementNames()

Returns the names of all standard presence elements as described in the respective sub-interface corresponding with the value of the type attribute. Returns:

list of standard presence element names

Service API

228

getElements

public Element[] getElements()

Returns all presence elements in the container. Returns:

list of presence element

removeElement

public void removeElement(Element element) throws IllegalStateException

Removes the specified presence element. Parameters:

element - presence information element Throws:


Interface PresenceList javax.microedition.ims.service.presence


public interface PresenceList extends Synchronizable

Interface PresenceList specifies methods to get and manipulate information on presentities that a user can make a subscription to. Presence lists are provided by the RLS server.

Method Summary Page

void addService(String serviceURI) Puts a new service element including an empty list construct into the presence

list. 3

XDMList getList(String serviceURI) Returns a list of resources to which the server will perform virtual subscriptions. 3

String[] getServices() Returns all services for which there are subscribable presentities in the presence

list. 3

void removeAllServices() Removes all service elements including the list constructs from the presence list. 3

Service API

229

void removeService(String serviceURI) Removes the specified service element including the list construct from the

presence list. 3

Method Detail

addService

public void addService(String serviceURI) throws IMSMalformedURIException, IllegalStateException

Puts a new service element including an empty list construct into the presence list. The list can be populated with resources by obtaining a reference to it via getList(serviceURI) and manipulating the obtained list using the methods of XDMList. Parameters:

serviceURI - URI of service to be added Throws:

IMSMalformedURIException - if the URI is malformed IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

removeService

public void removeService(String serviceURI) throws IMSMalformedURIException, IllegalStateException

Removes the specified service element including the list construct from the presence list. Parameters:

serviceURI - URI of service to be removed Throws:

IMSMalformedURIException - if the URI is malformed IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

removeAllServices

public void removeAllServices() throws IllegalStateException

Removes all service elements including the list constructs from the presence list. Throws:

IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

Service API

230

getServices

public String[] getServices()

Returns all services for which there are subscribable presentities in the presence list. Returns:

list of service URIs

getList

public XDMList getList(String serviceURI) throws IMSMalformedURIException

Returns a list of resources to which the server will perform virtual subscriptions. A service URI must be specified. Parameters:

serviceURI - URI specifying the service for which resources are queried Returns:

XDMList instance containing list of resources Throws:

IMSMalformedURIException - if serviceURI is malformed

Interface PresenceProfile javax.microedition.ims.service.presence

All Superinterfaces: PresenceContainer, Synchronizable

public interface PresenceProfile extends Synchronizable, PresenceContainer

Interface PresenceProfile provides methods for accessing the content of a presence profile. A PresenceProfile is associated with a particular public user id, must have a unique name, consists of presence information of a certain type and is stored on the XDMS. Currently, presence profiles are not part of the OMA standard, but can be easily realized by introducing a new AUID specific for presence profiles. As presence profiles are mentioned in the requirements specification document for the presence service enabler, they are likely to be standardized in later versions of the standard.

Method Summary Page

String getName() Returns the name of the presence profile. 3

void reset() Resets the profile to the initial values specified in the default profile. 3

Service API

231

Method Detail

getName

public String getName()

Returns the name of the presence profile. Returns:

name

reset

public void reset()

Resets the profile to the initial values specified in the default profile.

Interface PresenceService javax.microedition.ims.service.presence


public interface PresenceService extends ImsService

Interface PresenceService is an extension of IMSService that acts as a factory for all instances of presentities, subscriptions, policies and rules, presence profiles and presence lists owned by a particular public user ID. PresenceService also acts as a registry for those entities. It is created via the createService() method of IMSManager if the proper application ID for the Presence service is used.

Method Summary Page

PresenceProfile createPresenceProfile(String name) Creates a presence profile for the current public user ID. 3

PresenceProfile createPresenceProfile(String name, PresenceProfile template)

Creates a presence profile for the current public user ID from a template.

3

Subscription createSubscription(String targetURI, int type) Creates a subscription object to a target URI for the current

public user ID. 3

Service API

232

PresenceAuthorizationPolicy getPresenceAuthorizationPolicy() Returns the Presence authorization policy for the current public

user ID. 3

PresenceList getPresenceList() Returns the presence list for the current public user ID. 3

PresenceProfile getPresenceProfile(String name) Returns a particular presence profile specfied by name. 3

PresenceProfile[] getPresenceProfiles() Returns all presence profiles for the current public user ID. 3

Presentity getPresentity() Returns the presentity associated with the current public user

ID. 3

Subscription getSubscription(String targetURI) Returns the subscription object for the current public user ID

and a particular target 3

Subscription[] getSubscriptions() Returns all subscriptions for the current public user ID. 3

Method Detail

createPresenceProfile

public PresenceProfile createPresenceProfile(String name) throws IMSObjectExistsException, SecurityException

Creates a presence profile for the current public user ID. Parameters:

name - name for presence profile Returns:

presence profile Throws:

IMSObjectExistsException - if the presence profile already exists SecurityException - if permission is not granted

createPresenceProfile

public PresenceProfile createPresenceProfile(String name, PresenceProfile template) throws IMSObjectExistsException, SecurityException

Creates a presence profile for the current public user ID from a template. Parameters:

name - name for presence profile template - template presence profile

Service API

233

Returns: presence profile

Throws: IMSObjectExistsException - if the presence profile already exists SecurityException - if permission is not granted

createSubscription

public Subscription createSubscription(String targetURI, int type) throws IMSMalformedURIException, IMSObjectExistsException, IllegalArgumentException, SecurityException

Creates a subscription object to a target URI for the current public user ID. (The following values may be used for type: Subscription.TYPE_ONCE, Subscription.TYPE_MANY). The actual subscription has to be performed manually. Parameters:

targetURI - target URI (URI of a presentity or URI of a presence list service) type - type of subscription

Returns: subscription

Throws: IMSMalformedURIException - if the target URI is malformed IMSObjectExistsException - if the subscription object already exists IllegalArgumentException - if the type argument is invalid SecurityException - if permission is not granted

getPresentity

public Presentity getPresentity() throws SecurityException

Returns the presentity associated with the current public user ID. Returns:

presentity Throws:


getPresenceList

public PresenceList getPresenceList() throws IMSDocumentNotExistingException, SecurityException

Returns the presence list for the current public user ID. If the presence list document does not exist/could not be created on the server, an exception is thrown. Returns:

presence list

Service API

234

Throws: IMSDocumentNotExistingException - if the document does not exist on the server SecurityException - if permission is not granted

getSubscriptions

public Subscription[] getSubscriptions()

Returns all subscriptions for the current public user ID. Returns:

list of subscriptions

getPresenceProfiles

public PresenceProfile[] getPresenceProfiles() throws SecurityException

Returns all presence profiles for the current public user ID. Returns:

list of presence profiles Throws:


getPresenceAuthorizationPolicy

public PresenceAuthorizationPolicy getPresenceAuthorizationPolicy() throws SecurityException

Returns the Presence authorization policy for the current public user ID. If no policy document exists on the server, an empty default policy document is returned. Upon comittment of this policy document using Synchronizable.submit(), a respective document is created on the server. Throws:


getSubscription

public Subscription getSubscription(String targetURI) throws IMSMalformedURIException

Returns the subscription object for the current public user ID and a particular target Parameters:

targetURI - subscription target (URI of a presentity or a presence list service) Returns:

subscription object; null if not existing Throws:

IMSMalformedURIException - if any URI is malformed

Service API

235

getPresenceProfile

public PresenceProfile getPresenceProfile(String name) throws IMSMalformedURIException, SecurityException

Returns a particular presence profile specfied by name. Parameters:

name - name (document URI) of presence profile Returns:

presence profile Throws:

IMSMalformedURIException - if the name is malformed SecurityException - if permission not granted

Interface Presentity javax.microedition.ims.service.presence

All Superinterfaces: PresenceContainer

public interface Presentity extends PresenceContainer

Interface Presentity provides means to manage and publish presence information and related documents for a particular public user ID, device ID or service ID. A Presentity instance is a container for presence information, presence profiles and presence authorization policies and provides means to get informed about incoming subscriptions. The diagram below shows the state model for publication handling.

Service API

236

After initialization, a presentity always starts in state INITIAL. Issuing a 'publish' or an 'unpublish' request triggers a transition into state PUBLISHING which is a transient state. Reception of a 'published notification' triggers a transition into state PUBLISHED, reception of an 'unpublished notification' or a 'failed notification' triggers a transition to state EXPIRED. State PUBLISHED is a stable state that can either undergo a transition to state PUBLISHING due to a 'publish' ('unpublish') request or by reception of an 'expired notification' leading into state EXPIRED. State EXPIRED is also a stable state that can only undergo a transition to state PUBLISHING when a 'publish' request is issued whereas an 'unpublish' request does not cause any state transition. As a presentity can not be deleted or terminated by the user no state TERMINATED does exist.

Field Summary Page

int STATE_EXPIRED Constant representing state EXPIRED of a presentity 3

int STATE_INITIAL Constant representing state INITIAL of a presentity 3

Service API

237

int STATE_PUBLISHED Constant representing state PUBLISHED of a presentity 3

int STATE_PUBLISHING Constant representing state PUBLISHING of a presentity 3

int STATE_TERMINATED Constant representing state TERMINATED of a presentity 3

Method Summary Page

String getActiveProfile() Returns the name of the active presence profile. 3

String[] getPendingWatchers() Returns all watchers of that presentity waiting for autorization

of a subscription request. 3

PresenceAuthorizationPolicy getPresenceAuthorizationPolicy() Returns the presence authorization instance for presentity. 3

PresenceProfile[] getProfiles() Returns all presence profiles associated with presentity. 3

int getState() Returns the state of the presentity. 3

void publish() Triggers publication of the current presence information. 3

void setActiveProfile(String name) Sets the active presence profile by name. 3

void setActiveProfile(PresenceProfile profile) Sets the active presence profile. 3

void setPresentityListener(PresentityListener listener) Sets the presentity listener. 3

void unpublish() Unpublishes the current presence information (corresponds to a

publication with expiration time zero). 3

Field Detail

STATE_INITIAL

public static final int STATE_INITIAL

Constant representing state INITIAL of a presentity

STATE_PUBLISHING

public static final int STATE_PUBLISHING

Service API

238

Constant representing state PUBLISHING of a presentity

STATE_PUBLISHED

public static final int STATE_PUBLISHED

Constant representing state PUBLISHED of a presentity

STATE_EXPIRED

public static final int STATE_EXPIRED

Constant representing state EXPIRED of a presentity

STATE_TERMINATED


Constant representing state TERMINATED of a presentity

Method Detail

getState


Returns the state of the presentity. Returns:

state (one of STATE_*)

getProfiles

public PresenceProfile[] getProfiles() throws SecurityException

Returns all presence profiles associated with presentity. Returns:

list of presence profiles Throws:

SecurityException - if permission not granted

Service API

239

getActiveProfile

public String getActiveProfile()

Returns the name of the active presence profile. Returns:

name of active presence profile; null if none is active

setActiveProfile

public void setActiveProfile(String name) throws IllegalArgumentException, SecurityException

Sets the active presence profile by name. The presence information of the presentity is replaced by the presence information of the profile. Parameters:

name - name of presence profile Throws:

IllegalArgumentException - if the presence profile specified by name does not exist or is not associated with presentity SecurityException - if permission is not granted

setActiveProfile

public void setActiveProfile(PresenceProfile profile) throws IllegalArgumentException, SecurityException

Sets the active presence profile. The presence information of the presentity is replaced by the presence information of the profile. Parameters:

profile - presence profile Throws:

IllegalArgumentException - if the presence profile specified is not associated with presentity SecurityException - if permission is not granted

getPresenceAuthorizationPolicy

public PresenceAuthorizationPolicy getPresenceAuthorizationPolicy() throws SecurityException

Returns the presence authorization instance for presentity. Returns:

presence authorization policy Throws:


Service API

240

getPendingWatchers

public String[] getPendingWatchers()

Returns all watchers of that presentity waiting for autorization of a subscription request. Returns:

list of pending watchers

publish

public void publish() throws IllegalStateException, SecurityException

Triggers publication of the current presence information. Usually, presence information is periodically updated by the IMS engine without user intervention. Throws:

IllegalStateException - if presentity is not in state INITIAL, PUBLISHED or EXPIRED SecurityException

unpublish

public void unpublish() throws IllegalStateException, SecurityException

Unpublishes the current presence information (corresponds to a publication with expiration time zero). Throws:

IllegalStateException - if presentity is not in state INITIAL, PUBLISHED or EXPIRED SecurityException

setPresentityListener

public void setPresentityListener(PresentityListener listener)

Sets the presentity listener. Parameters:

listener - presentity listener

Interface PresentityListener javax.microedition.ims.service.presence

public interface PresentityListener

Service API

241

Interface PresentityListener provides methods for notifications associated with publication of presence data. requests. The methods are being invoked by the Presence engine upon reception of notifications from the Presence server. A PresentityListener is registered at a Presentity instance by invoking method setPresentityListener.

Method Summary Page

void processExpired(Presentity presentity) Notifies expiration of a publication that has been previously made by presentity. 3

void processFailed(Presentity presentity, String errorMessage) Notifies failure of a publication request that has been previously issued by

presentity. 3

void processPublished(Presentity presentity) Notifies execution of a publication request that has been previously issued by

presentity. 3

void processSubscriptionRequest(Presentity presentity, String watcherURI, boolean authorized)

Notifies reception of a subscription request at the Presence server. 3

void processUpcomingExpiration(Presentity presentity) Notifies that a publication that has been previously made will expire soon. 3

Method Detail

processPublished

public void processPublished(Presentity presentity)

Notifies execution of a publication request that has been previously issued by presentity. Parameters:

presentity - the presentity that has sent the publication request

processExpired

public void processExpired(Presentity presentity)

Notifies expiration of a publication that has been previously made by presentity. Parameters:

presentity - the presentity that has made the publication

processUpcomingExpiration

public void processUpcomingExpiration(Presentity presentity)

Notifies that a publication that has been previously made will expire soon.

Service API

242

Parameters: presentity - the presentity that has made the publication

processFailed

public void processFailed(Presentity presentity, String errorMessage)

Notifies failure of a publication request that has been previously issued by presentity. Parameters:

presentity - the presentity that has issued the publication request errorMessage - string specifying the reason for a failure

processSubscriptionRequest

public void processSubscriptionRequest(Presentity presentity, String watcherURI, boolean authorized)

Notifies reception of a subscription request at the Presence server. The notification provides information on the concerned presentity, the URI of the watcher that wants to subscribe and whether the request has already been automatically authorized at the server maccording to a matching subscription authorization rule. If the request has not yet been authorized, the user may establish a respective subscription authorization rule to do so. Parameters:

presentity - the presentity that the subscription request refers to watcherURI - the URI of the watcher that sent the subscription authorized - boolean indicating whether the subscription has already been authorized by the server

Interface ServiceInformation javax.microedition.ims.service.presence


public interface ServiceInformation extends PresenceInformation

Interface ServiceInformation specfies a set of presence information elements that are typically used as presence information for a service. The constants are to be used as names of presence information elements that can be retrieved by method getElement.

Service API

243

Field Summary Page

String AVAILABILITY Constant specifying name of element 3

String BARRING_STATE Constant specifying name of element 3

String CLASS Constant specifying name of element 3

String CONTACT Constant specifying name of element 3

String DEVICE_ID Constant specifying name of element 3

String REGISTRATION_STATE Constant specifying name of element 3

String SERVICE_DESCRIPTION Constant specifying name of element 3

String SESSION_PARTICIPATION Constant specifying name of element 3

String STATUS_ICON Constant specifying name of element 3


String WILLINGNESS Constant specifying name of element 3

Method Summary Page

String getServiceID() returns value of attribute 'id' of element 3

Field Detail

WILLINGNESS

public static final String WILLINGNESS


AVAILABILITY

public static final String AVAILABILITY


Service API

244

REGISTRATION_STATE

public static final String REGISTRATION_STATE


BARRING_STATE

public static final String BARRING_STATE


STATUS_ICON

public static final String STATUS_ICON


SESSION_PARTICIPATION

public static final String SESSION_PARTICIPATION


CONTACT

public static final String CONTACT


SERVICE_DESCRIPTION

public static final String SERVICE_DESCRIPTION


TIMESTAMP



Service API

245

CLASS

public static final String CLASS


DEVICE_ID

public static final String DEVICE_ID


Method Detail

getServiceID

public String getServiceID()

returns value of attribute 'id' of element Returns:

id of service

Interface Subscription javax.microedition.ims.service.presence

public interface Subscription

Interface Subscription provides means to manipulate and perform subscriptions for a particular target and manage related data. Moreover, a Subscription instance is a container for presence information obtained as the result of a subscription. The diagram below shows the state model for subscription handling.

Service API

246

After initialization, a subscription always starts in state INITIAL. Issuing a 'subscribe' or an 'unsubscribe' request triggers a transition into state SUBSCRIBING which is a transient state. Reception of a 'subscribed notification' triggers a transition into state SUBSCRIBED, reception of an

Service API

247

'unscubscribed notification' or a 'failed notification' triggers a transition to state EXPIRED. State SUBSCRIBED is a stable state can either undergo a transition to state SUBSCRIBING due to a 'subscribe' ('unsubscribe') request or by reception of an 'expired notification' leading into state EXPIRED. State EXPIRED is also a stable state that can only undergo a transition to state SUBSCRIBING when a 'subscribe' request is issued whereas an 'unsubscribe' request does not cause any state transition. Issuing a 'close' request causes a transition to state TERMINATED from any other state.

Field Summary Page

int STATE_EXPIRED Constant representing state EXPIRED of a subscription 3

int STATE_INITIAL Constant representing state INITIAL of a subscription 3

int STATE_SUBSCRIBED Constant representing state SUBSCRIBED of a subscription 3

int STATE_SUBSCRIBING Constant representing state SUBSCRIBING of a subscription 3

int STATE_TERMINATED Constant representing state TERMINATED of a subscription 3

int TYPE_MANY subscription type constant requesting recurring delivery of notifications 3

int TYPE_ONCE subscription type constant requesting one-time delivery of notifications 3

Method Summary Page

void close() Closes the subscription, i.e. the subscription is terminated and the

Subscription object is deleted from the registry maintained by PresenceService.

3

PeerPresentity[] getPeerPresentities() Returns all PeerPresentity instances monitored according to the

subscription. 3

PeerPresentity getPeerPresentity(String presentityURI) Returns the PeerPresentity instance for a particular URI 3

String[] getPeerPresentityURIs() Returns the URIs of all peer presentities monitored according to the

subscription. 3

int getState() Returns the state of the subscription. 3

String getSubscriber() Returns the URI of the subscriber. 3

Service API

248

String getTargetURI() Returns the URI of the target (may be a single presentity or a presence

list service) 3

int getType() Returns the type of the subscription 3

void setSubscriptionListener(SubscriptionListener listener) Sets the subscription listener. 3

void setType(int type) Sets the type of the subscription (may be one of TYPE_ONCE,

TYPE_MANY) 3

void subscribe() Performs a subscription of the current subscription type. 3

void unsubscribe() Unsubscribes from the target. 3

Field Detail

TYPE_ONCE

public static final int TYPE_ONCE

subscription type constant requesting one-time delivery of notifications

TYPE_MANY

public static final int TYPE_MANY

subscription type constant requesting recurring delivery of notifications

STATE_INITIAL


Constant representing state INITIAL of a subscription

STATE_SUBSCRIBING

public static final int STATE_SUBSCRIBING

Constant representing state SUBSCRIBING of a subscription

Service API

249

STATE_SUBSCRIBED

public static final int STATE_SUBSCRIBED

Constant representing state SUBSCRIBED of a subscription

STATE_EXPIRED

public static final int STATE_EXPIRED

Constant representing state EXPIRED of a subscription

STATE_TERMINATED


Constant representing state TERMINATED of a subscription

Method Detail

getTargetURI

public String getTargetURI()

Returns the URI of the target (may be a single presentity or a presence list service) Returns:

URI of target

getSubscriber

public String getSubscriber()

Returns the URI of the subscriber. Returns:

URI of subscriber

getState


Returns the state of the subscription. Returns:

state (one of STATE_*)

Service API

250

getPeerPresentityURIs

public String[] getPeerPresentityURIs()

Returns the URIs of all peer presentities monitored according to the subscription. Returns:

list of URIs

getPeerPresentity

public PeerPresentity getPeerPresentity(String presentityURI) throws IMSMalformedURIException, SecurityException

Returns the PeerPresentity instance for a particular URI Parameters:

presentityURI - URI of peer presentity Returns:

peer presentity Throws:

IMSMalformedURIException - if URI of peer presentity is malformed. SecurityException - if permission not granted

getPeerPresentities

public PeerPresentity[] getPeerPresentities() throws SecurityException

Returns all PeerPresentity instances monitored according to the subscription. Returns:

list of peer presentities Throws:


setType

public void setType(int type) throws IllegalArgumentException

Sets the type of the subscription (may be one of TYPE_ONCE, TYPE_MANY) Parameters:

type - type of the subscription Throws:

IllegalArgumentException - if an invalid type parameter is specified

getType


Service API

251

Returns the type of the subscription Returns:

type

subscribe

public void subscribe() throws IllegalStateException, SecurityException

Performs a subscription of the current subscription type. Usually, the subscription is periodically updated by the IMS engine without user intervention. Throws:

IllegalStateException - if subscription is not in state INITIAL, SUBSCRIBED or EXPIRED SecurityException - if permission is not granted

unsubscribe

public void unsubscribe() throws IllegalStateException, SecurityException

Unsubscribes from the target. Throws:

IllegalStateException - if subscription is not in state INITIAL, SUBSCRIBED or EXPIRED SecurityException - if permission is not granted

close

public void close() throws SecurityException

Closes the subscription, i.e. the subscription is terminated and the Subscription object is deleted from the registry maintained by PresenceService. Throws:


setSubscriptionListener

public void setSubscriptionListener(SubscriptionListener listener)

Sets the subscription listener. Parameters:

listener - subscription listener

Service API

252

Interface SubscriptionListener javax.microedition.ims.service.presence

public interface SubscriptionListener

Interface SubscriptionListener provides methods for notifications associated with subscriptions to other users' presence data and a method for notification of incoming subscription notifications regarding a user's presence data. The methods are being invoked by the Presence engine upon reception of notifications from the Presence server. A SubscriptionListener is registered at a Subcription instance by invoking method setSubscriptionListener.

Method Summary Page

void processChanged(Subscription subscription, PeerPresentity presentity) Notifies a change of presence information associated with a presentity for which

a subscription has been previously made. 3

void processExpired(Subscription subscription) Notifies expiration of a subscription that has been previously made by

subscription instance. 3

void processFailed(Subscription subscription, String errorMessage) Notifies failure of a subscription request that has been previously issued by

subscription instance. 3

void processSubscribed(Subscription subscription) Notifies successful completion of a subscription request that has been previously

issued by subcription instance. 3

void processUpcomingExpiration(Subscription subscription) Notifies that a subscription that has been previously made will expire soon. 3

Method Detail

processSubscribed

public void processSubscribed(Subscription subscription)

Notifies successful completion of a subscription request that has been previously issued by subcription instance. Parameters:

subscription - the subscription instance that has sent the subscription request

processFailed

public void processFailed(Subscription subscription, String errorMessage)

Service API

253

Notifies failure of a subscription request that has been previously issued by subscription instance. Parameters:

subscription - the subscription instance that has sent the subscription request errorMessage - string specifying the reason for a failure

processExpired

public void processExpired(Subscription subscription)

Notifies expiration of a subscription that has been previously made by subscription instance. Parameters:

subscription - the subscription instance that has made the subscription

processUpcomingExpiration

public void processUpcomingExpiration(Subscription subscription)

Notifies that a subscription that has been previously made will expire soon. Parameters:

subscription - the subscription instance that has made the subscription

processChanged

public void processChanged(Subscription subscription, PeerPresentity presentity)

Notifies a change of presence information associated with a presentity for which a subscription has been previously made. Parameters:

subscription - the subscription instance that has made the subscription presentity - the peer presentity instance that contains the presence information

Package javax.microedition.ims.service.util This package defines utility entities for JSR 281 service enablers.

See: Description


BasicRule Interface BasicRule provides an interface to the condition part of a policy rule.

3

Service API

254

ExternalListCondition Interface ExternalListCondition provides means to specify an external URI list as condition element for a rule.

3

IdentityCondition Interface IdentityCondition provides means to specify for which users the rule that the condition is associated with is applicable.

3

Synchronizable Interface Synchronizable provides means for controlling synchronization of client-side objects with associated server-side documents.

3

SynchronizationListener Interface SynchronizationListener provides various notification methods for instances implementing interface Synchronizable.

3

Validity Interface Validity provides methods to access a validity specification being a part of a validity condition.

3

ValidityCondition Interface ValidityCondition represents a set of validity constraints, which each specify a period of time during which a rule is valid.

3

Class Summary Page

Attribute Class Attribute represents an attribute in a XDMDocument. 3

Element Class Element represents an element of a XDMDocument. 3

Entry Class Entry represents an entry in a list containing a URI and an optional display name.

3

UsageEntry

Class UsageEntry is an extension of class Entry, representing an entry in a group usage list that contains not only a mandatory URI attribute, but also uriusage elements specifying service names indicating what the URI is used for.

3

Package javax.microedition.ims.service.util Description

This package defines utility entities for JSR 281 service enablers.

Class Attribute javax.microedition.ims.service.util

java.lang.Object javax.microedition.ims.service.util.Attribute

public class Attribute extends Object

Class Attribute represents an attribute in a XDMDocument.

Service API

255


Attribute(String name, String value) Public constructor; parameter name must not be set to null 3

Method Summary Page

String getName() Returns attribute name 3

String getValue() Returns attribute value 3

void setValue(String value) Sets attribute value 3

Constructor Detail

Attribute

public Attribute(String name, String value) throws IllegalArgumentException

Public constructor; parameter name must not be set to null Parameters:

name - attribute name value - attribute value

Throws: IllegalArgumentException - if the parameter name is null or the parameter value is null

Method Detail

getName


Returns attribute name Returns:

name of the attribute

getValue

public String getValue()

Returns attribute value Returns:

value of the attribute

Service API

256

setValue

public void setValue(String value) throws IllegalStateException

Sets attribute value Parameters:

value - new value that should be asigned to this attribute Throws:


Interface BasicRule javax.microedition.ims.service.util

All Known Subinterfaces: GroupAuthorizationRule, PoCUserAccessRule, PresenceAuthorizationRule

public interface BasicRule

Interface BasicRule provides an interface to the condition part of a policy rule. Any actions are to be specified in usage specific extensions of this interface. As complex conditions are not allowed according to the OMA XDM Spec, the condition type of a BasicRule determines which condition the rule actually implements. Basic Rule is defined as specified in COMMONPOL and OMA XDM Core specification. OMA XDM Core defines 3 additional conditional types: TYPE_EXTERNAL, TYPE_DEFAULT and TYPE_ANONYMOUS. While BasicRule has just these three condition types, extensions of BasicRule may add more conditions types for which the same restrictions apply.

Field Summary Page

int TYPE_ANONYMOUS Constant representing a condition of type <anonymous-request> 3

int TYPE_DEFAULT Constant representing a condition of type <other-identity> 3

int TYPE_EXTERNAL Constant representing a condition of type <external-list> 3

int TYPE_IDENTITY Constant representing a condition of type <identity> 3

Method Summary Page

ExternalListCondition getExternalListCondition() Returns the external list condition 3

String getID() Returns the rule's ID 3

Service API

257

IdentityCondition getIdentityCondition() Returns the identity condition 3

String getSphereCondition() Returns the sphere condition 3

int getType() Returns the condition type of the rule. 3

ValidityCondition getValidityCondition() Returns the validity condition 3

void setSphereCondition(String value) Sets the sphere condition of the rule. 3

Field Detail

TYPE_IDENTITY

public static final int TYPE_IDENTITY

Constant representing a condition of type <identity>

TYPE_EXTERNAL

public static final int TYPE_EXTERNAL

Constant representing a condition of type <external-list>

TYPE_DEFAULT

public static final int TYPE_DEFAULT

Constant representing a condition of type <other-identity>

TYPE_ANONYMOUS

public static final int TYPE_ANONYMOUS

Constant representing a condition of type <anonymous-request>

Method Detail

getIdentityCondition

public IdentityCondition getIdentityCondition()

Service API

258

Returns the identity condition Returns:

identity condition or null if the condition type of the rule is another than TYPE_IDENTITY.

getValidityCondition

public ValidityCondition getValidityCondition()

Returns the validity condition Returns:

validity condition

setSphereCondition

public void setSphereCondition(String value) throws IllegalStateException

Sets the sphere condition of the rule. Parameters:

value - text string specifying the sphere; null to unset the sphere condition Throws:


getSphereCondition

public String getSphereCondition()

Returns the sphere condition Returns:

sphere condition or null if the sphere condition is not set

getExternalListCondition

public ExternalListCondition getExternalListCondition()

Returns the external list condition Returns:

external list condition or null if the condition type of the rule is another than TYPE_EXTERNAL.

getType


Returns the condition type of the rule.

Service API

259

Returns: type of the rule as integer value

getID

public String getID()

Returns the rule's ID Returns:

rule ID

Class Element javax.microedition.ims.service.util

java.lang.Object javax.microedition.ims.service.util.Element

public class Element extends Object

Class Element represents an element of a XDMDocument.


Element(String name, String value) public constructor; name must not be set to null 3

Method Summary Page

void addAttribute(Attribute attr) Adds an attribute. 3

void addElement(Element elem) Adds a child element. 3

Attribute[] getAttributes() Returns all attributes of element. 3

Element[] getElements() Returns all child elements. 3

String getName() Returns the element's name. 3

String getValue() Returns the element's value. 3

void removeAttribute(Attribute attr) Removes an attribute. 3

Service API

260

void removeElement(Element elem) Removes a child element. 3

void setValue(String value) Sets the element's value. 3

Constructor Detail

Element

public Element(String name, String value) throws IllegalArgumentException

public constructor; name must not be set to null Parameters:

name - element name value - element value

Throws: IllegalArgumentException - if parameter name is null

Method Detail

getName


Returns the element's name. Returns:

element name

getValue

public String getValue()

Returns the element's value. Returns:

element Value

setValue

public void setValue(String value) throws IllegalStateException

Sets the element's value. Parameters:

value - new value to be set

Service API

261

Throws: IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

addAttribute

public void addAttribute(Attribute attr) throws IllegalStateException

Adds an attribute. Parameters:

attr - the attribute to be added Throws:


removeAttribute

public void removeAttribute(Attribute attr) throws IllegalStateException

Removes an attribute. Parameters:

attr - the attribute to be removed Throws:


getAttributes

public Attribute[] getAttributes()

Returns all attributes of element. Returns:

list of attributes of element

addElement

public void addElement(Element elem) throws IllegalStateException

Adds a child element. Parameters:

elem - new child element Throws:


Service API

262

removeElement

public void removeElement(Element elem) throws IllegalStateException

Removes a child element. Parameters:

elem - child element to be removed Throws:


getElements


Returns all child elements. Returns:

list of child elements or an empty list if no child elements exist

Class Entry javax.microedition.ims.service.util

java.lang.Object javax.microedition.ims.service.util.Entry

Direct Known Subclasses: UsageEntry

public class Entry extends Object

Class Entry represents an entry in a list containing a URI and an optional display name.


Entry(String uri) Public constructor without display name. 3

Entry(String uri, String name) Public constructor with display name. 3

Method Summary Page

String getDisplayname() Returns the display name attribute. 3

Service API

263

String getURI() Returns the URI attribute. 3

void setDisplayname(String name) Sets the display name attribute. 3

Constructor Detail

Entry

public Entry(String uri) throws IMSMalformedURIException

Public constructor without display name. Parameters:

uri - URI of the entry Throws:

IMSMalformedURIException - if uri is malformed

Entry

public Entry(String uri, String name) throws IMSMalformedURIException

Public constructor with display name. Parameters:

uri - URI of the entry name - display name of the entry

Throws: IMSMalformedURIException - if uri is malformed

Method Detail

getURI

public String getURI()

Returns the URI attribute. Returns:

URI attribute of the entry

getDisplayname

public String getDisplayname()

Returns the display name attribute.

Service API

264

Returns: display name of the entry

setDisplayname

public void setDisplayname(String name) throws IllegalStateException

Sets the display name attribute. Parameters:

name - display name to be assigned to the entry Throws:


Interface ExternalListCondition javax.microedition.ims.service.util

public interface ExternalListCondition

Interface ExternalListCondition provides means to specify an external URI list as condition element for a rule.

Method Summary Page

void addExternalList(String uri) Adds an external list attribute to the external list condition. 3

String[] getExternalLists() Returns all external list attributes. 3

void removeExternalList(String uri) Removes an external list attribute from the external list condition. 3

Method Detail

addExternalList

public void addExternalList(String uri) throws IMSMalformedURIException, IllegalStateException

Adds an external list attribute to the external list condition. Parameters:

uri - URI of external list Throws:

IMSMalformedURIException - if the list URI is malformed

Service API

265


removeExternalList

public void removeExternalList(String uri) throws IMSMalformedURIException, IllegalStateException

Removes an external list attribute from the external list condition. Parameters:

uri - URI of external list Throws:

IMSMalformedURIException - if the list URI is malformed IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

getExternalLists

public String[] getExternalLists()

Returns all external list attributes. Returns:

list of URIs of external lists

Interface IdentityCondition javax.microedition.ims.service.util

public interface IdentityCondition

Interface IdentityCondition provides means to specify for which users the rule that the condition is associated with is applicable.

Method Summary Page

void excludeDomain(String domain) Effects that rule is not applicable for any user in a particular domain. 3

void excludeUser(String uri) Effects that rule is not applicable for a particular user. 3

void excludeUser(String uri, String domain) Effects that rule is not applicable for a particular user in a particular domain. 3

String[] getExcludedDomains() Returns all domains for all users thereof rule is not applicable as the domains

have explicitly been specified to not fall under the rule (i.e. 3

Service API

266

String[] getExcludedUsers() Returns all users for which rule is not applicable as they have explicitly been

specified not to fall under the rule (i.e. they have been specified via a <except id="URI"> child element of any 'many' element with or without an attribute 'domain').

3

String[] getExcludedUsers(String domain) Returns all users for which rule is not applicable as they have explicitly been

specified to not fall under the rule (i.e. they have been specified via a <except id="URI"> child element of a 'many' element with an attribute 'domain' with value DOMAIN).

3

String[] getIncludedDomains() Returns all domains for all users thereof rule is applicable as the domains have

explicitly been specified to fall under the rule (i.e. they have been specified via a <many domain="DOMAIN"> child element of the 'identity' element).

3

String[] getIncludedUsers() Returns all users for which rule is applicable as they have explicitly been

specified to fall under the rule (i.e. they have been specified via a <one id="URI"> child element of the 'identity' element).

3

void includeAnyKnownUser() Resets all domain specific settings and makes rule applicable for any

authenticated user (i.e. except anonymous users) by replacing all existing 'many' child elements of the 'identity' element with an empty 'many' child element ('<identity><many/></identity>')

3

void includeAnyUser() Resets all identity settings and makes rule applicable for any user. 3

void includeDomain(String domain) Makes rule applicable to any user in a particular domain. 3

void includeUser(String uri) Makes rule applicable for a particular user. 3

void includeUser(String uri, String domain) Makes rule applicable to a particular user in a particular domain. 3

boolean isAnyKnownUserIncluded() Checks if rule is applicable for any authenticated user (i.e. if the 'identity'

element has an empty 'many' child element). 3

boolean isAnyUserIncluded() Checks if rule is applicable for any user (i.e. if the 'identity' element is empty). 3

Method Detail

includeAnyUser

public void includeAnyUser() throws IllegalStateException

Service API

267

Resets all identity settings and makes rule applicable for any user. This is achieved by removing all entries from the 'identity' element. Throws:


isAnyUserIncluded

public boolean isAnyUserIncluded()

Checks if rule is applicable for any user (i.e. if the 'identity' element is empty). Returns:

true if rule is applicable for any user, false otherwise.

includeAnyKnownUser

public void includeAnyKnownUser() throws IllegalStateException

Resets all domain specific settings and makes rule applicable for any authenticated user (i.e. except anonymous users) by replacing all existing 'many' child elements of the 'identity' element with an empty 'many' child element ('<identity><many/></identity>') Throws:


isAnyKnownUserIncluded

public boolean isAnyKnownUserIncluded()

Checks if rule is applicable for any authenticated user (i.e. if the 'identity' element has an empty 'many' child element). Returns:

true if rule is applicable for any authenticated user, false otherwise.

includeUser

public void includeUser(String uri) throws IMSMalformedURIException, IllegalStateException

Makes rule applicable for a particular user. (This is achieved by adding a '<one id="URI"/>' child element to the 'identity'element. If there are '<except id="URI">' child elements in any 'many' element (with or without 'domain' attribute), these child elements are being removed.)

Service API

268

Parameters: uri - URI of the user the rule should be applicable for

Throws: IMSMalformedURIException - if the parameter uri is not a well defined/well formatted URI IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

excludeUser

public void excludeUser(String uri) throws IMSMalformedURIException, IllegalStateException

Effects that rule is not applicable for a particular user. (This is achieved either by removing an existing child element <one 'id="URI"'> or by adding a child element '<except id="URI"/>' to an existing 'many' child element without 'domain' attribute or with a matching 'domain' attribute.) PROBLEM TO BE SOLVED: How to prohibit that rule erroneously becomes applicable for any user if removal of the 'one' child element results in an empty 'identity' element? POSSIBLE SOLUTION: Avoid generation of an empty 'identity' element by adding a 'one' child element that has its 'id' attribute set to the public user ID of the user running the application. Parameters:

uri - URI of the user the rule should not be applicable for Throws:

IMSMalformedURIException - if the parameter uri is not a well defined/well formatted URI IllegalStateException - iif the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

includeDomain

public void includeDomain(String domain) throws IllegalStateException

Makes rule applicable to any user in a particular domain. (This is achieved by either adding a child element '<many id="DOMAIN"> or, if that child alement already exists, removing any 'except' child elements from that 'many' child element or, if a 'many' child element without 'domain' attribute exists, removing the <except domain="DOMAIN"> if that exists.) Parameters:

domain - domain for all users thereof rule should be applicable Throws:


Service API

269

excludeDomain

public void excludeDomain(String domain) throws IllegalStateException

Effects that rule is not applicable for any user in a particular domain. (This is achieved by either removing an existing 'many' child element with 'domain="DOMAIN"' attribute or, in case that a 'many' child element without 'domain' attribute exists instead, adding a child element '&;except domain="DOMAIN">' to that 'many' child element.) Parameters:

domain - domain for all users thereof rule should not be applicable Throws:


includeUser

public void includeUser(String uri, String domain) throws IMSMalformedURIException, IllegalStateException

Makes rule applicable to a particular user in a particular domain. (This is achieved by either removing an existing <except id="URI"> child element from a 'many' element with or without 'domain="DOMAIN"' attribute or, if no matching 'many' elements exist, adding a <one id="URI"> child element to the 'identity' element.) Parameters:

uri - URI of the user the rule should be applicable for domain - domain the user is in

Throws: IllegalStateException - if the parameter URI is not a well defined/well formatted URI

excludeUser

public void excludeUser(String uri, String domain) throws IMSMalformedURIException, IllegalStateException

Effects that rule is not applicable for a particular user in a particular domain. (This is achieved by either adding a child element '<except id="URI"/>' to an existing 'many' child element without 'domain' attribute or with a matching 'domain' attribute or by removing an existing child element <one 'id="URI"'> or by .) PROBLEM TO BE SOLVED: How to prohibit that rule erroneously becomes applicable for any user if removal of the 'one' child element results in an empty 'identity' element? POSSIBLE SOLUTION: Avoid generation of an empty 'identity' element by adding a 'one'

Service API

270

child element that has its 'id' attribute set to the public user ID of the user running the application. Parameters:

uri - URI of the user the rule should not be applicable for domain - domain the user is in

Throws: IMSMalformedURIException - if the parameter uri is not a well defined/well formatted URI IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

getIncludedUsers

public String[] getIncludedUsers()

Returns all users for which rule is applicable as they have explicitly been specified to fall under the rule (i.e. they have been specified via a <one id="URI"> child element of the 'identity' element). Returns:

a list of URIs of users that the rule is applicable for, or an empty array if no users are included

getExcludedUsers

public String[] getExcludedUsers()

Returns all users for which rule is not applicable as they have explicitly been specified not to fall under the rule (i.e. they have been specified via a <except id="URI"> child element of any 'many' element with or without an attribute 'domain'). Returns:

a list of URIs of users that the rule is not applicable for, or an empty array if no users are excluded

getIncludedDomains

public String[] getIncludedDomains()

Returns all domains for all users thereof rule is applicable as the domains have explicitly been specified to fall under the rule (i.e. they have been specified via a <many domain="DOMAIN"> child element of the 'identity' element). Returns:

a list of domains for all users thereof rule is applicable, or an empty array if no domains are included

getExcludedDomains

public String[] getExcludedDomains()

Service API

271

Returns all domains for all users thereof rule is not applicable as the domains have explicitly been specified to not fall under the rule (i.e. they have been specified via a <except domain="DOMAIN"> child element of a 'many' element without an attribute 'domain'). Returns:

a list of domains for all users thereof rule is not applicable, or an empty array if no domains are excluded

getExcludedUsers

public String[] getExcludedUsers(String domain)

Returns all users for which rule is not applicable as they have explicitly been specified to not fall under the rule (i.e. they have been specified via a <except id="URI"> child element of a 'many' element with an attribute 'domain' with value DOMAIN). Returns:

a list of URIs of users that the rule is not applicable for, or an empty array if no users are excluded

Interface Synchronizable javax.microedition.ims.service.util

All Known Subinterfaces: Group, GroupUsageList, PoCGroup, PoCUserAccessPolicy, PresenceAuthorizationPolicy, PresenceList, PresenceProfile, URIList, XDMDirectory, XDMDocument

public interface Synchronizable

Interface Synchronizable provides means for controlling synchronization of client-side objects with associated server-side documents. The interface provides methods to trigger synchronization between client and server in both directions while being online, but also to modify the object in offline state and either perform synchronization later when again being online or return to a previously stored synchronized state if synchronization is currently not feasible. When an instance of Synchronizable is created, it starts in state INITIAL. This state is a transient state not visible to an external user of a synchronizable, as it only exists for a short period of time during construction of a Synchronizable. In order to fetch a document of type X from a server, usually a method getX provided by a manager entity has to be invoked. Internally the XDM engine contacts the server and tries to fetch the content of the respective document from the server. While waiting for the response from the server, the object is in state UPDATING. This response is either an OK, meaning that the contents of the document are successfully received. In this case the object's state changes to STABLE. Or the device receives an error. This could mean either that the server can not be contacted (e.g. timeout) or that the server could not send the document contents. In this case the object's state changes to OUTDATED. An outdated object can either be disposed or it can try to

Service API

272

update contents from the server again. This means that again the device tries to fetch the contents from the server and the object's state is changed to UPDATING again. If an object should be initially created and stored on the server, one has to call the manager's create method. Internally the object's state is transferred to state I_MODIFED and the object itself is marked as ready to be modified. The I states that the object is initially modified, and not yet stored on the server. After modifying the document one can submit the object, in order to create the document on the server. In this case it has to be decided whether the object is submitted the very first time. If so, the request is sent to the server and the object's state is changed to I_SUBMITTING. The object stays in this state until a server response is received. If the response is positive, meaning that the document was successfully stored on the server, the object's state changes to STABLE. This means that the object is in sync with the document on the server. If the object is in state I_SUBMITTING and a negative response is received, e.g. the document already exists on the server and thus the document was not overwritten, the object's state is changed back to I_MODIFIED. One can either dispose the object or modify the object. If a document in state I_MODIFIED can not be submitted because there is already a document with the same name on the server, one has to dispose the object and allocate a new one with a new name, or one has to call the managers get method in order to fetch the document from the server. A document in state STABLE can be either modified, or updated. If one receives a notification indicating that an object on the server has been changed, and the object is in state STABLE, one can update the object, which means fetching the new document content from the server. The object's state is changed from STABLE to UPDATING. If the server response is positive, meaning the content has been successfully received, the object's state is changed back to state STABLE, since it is in sync with the server again. If the response is negative, the objects state is changed to OUTDATED, meaning that it is not in sync with the server. One can update the object again, which again leads to a state transition from OUTDATED to UPDATING. If the update is performed successfully, the state changes back to STABLE again. In order to modify an object, the object has to be in state MODIFY. This is achieved by calling method modify(). When calling this method a backup of the stable object is saved. When all modifications are performed, the changes can be submitted to the server. This leads to a state transition to SUBMITTING. The object is in this state until a server response is received; if the submit was successful, the object's state changes to STABLE and the backup, which has been saved when changing to state modified, is disposed. If the submit is not successful, the state is changed back to MODIFIED. the user can either try to re-submit the changes, or reverse the changes and go back to state STABLE. In this case the backup is restored and the modified object is disposed. If a change notification of an object is received, the object has to be in state STABLE in order to being able to process an update, which leads to a state transition to state UPDATING. Methods dispose() or delete() can be called in any state and lead to a state transition to state TERMINATED. Objects in this state MUST NOT be used any more, and they are disposed for garbage collection. REMARK: If a modifying method is being invoked upon a Synchronizable object or any of its child objects, like e.g. an Attribute, an Element, or an XDMList WITHOUT the root Synchronizable being in state MODIFIED, the repsective object must not be changed and an

Service API

273

IllegalStateException has to be thrown by the respective method. REMARK: If a Synchronizable is disposed (i.e. put int state TERMINATED and thus marked for being no longer needed) by calling delete() or dispose() the corresponding manager has to remove the object from its internal 'registry' in order to give the garbage collector chance to clear away the object. Therefore the implementation has to make sure that the responsible manager is being informed when a Synchronizable is disposed.

Service API

274

Service API

275

Figure 1: State model for synchronization mechanism

Field Summary Page

int STATE_I_MODIFIED STATE_I_MODIFIED signalizes initial modification of an object that has not yet

been synchronized with the server 3

int STATE_I_SUBMITTING STATE_I_SUBMITTING this state signalizes an initial submiting of the object 3

int STATE_INITIAL STATE_INITIAL signalized the state of an object when it is created 3

int STATE_MODIFIED STATE_MODIFIED indicates that a object has been modified and thus is not

consitent with the corresponding documetn on the server. 3

int STATE_OUTDATED STATE_OUTDATED indicates that the object is not consistant with the object on the

server 3

int STATE_STABLE STATE_STABLE indicates that an object is consistant whith the corresponding

object on the server 3

int STATE_SUBMITTING STATE_SUBMITTING indicates that the local changes are currently submitted on

the server. 3

int STATE_TERMINATED STATE_TERMINATED indicates that an object is not used any more and thus can be

garbage collected 3

int STATE_UPDATING STATE_UPDATING update of an object in order to get the corresponding document

on the server 3

Method Summary Page

void delete() Marks a Synchronizable object for deletion on the client and also deletes the

associated XDM document on the server. 3

void dispose() Marks a Synchronizable object for deletion on the client and terminates all

resources and network activity associated with it. 3

Service API

276

String getDocumentURI() This method returns the document URI of the XDM document 3

String getPrincipal() This method returns the principal of an object 3

int getState() This method returns the current state of an object as defined integer value (see

state constants) 3

boolean isReadOnly() This method returns whether an object is read only or not 3

void modify() This method has to be called before ANY modifications of a Synchronizable is

performed. 3

void reverse() This method leads to discarding all changes that have not yet been successfuly

submited. 3

void setSynchronizationListener(SynchronizationListener listener) This method facilitates to add a synchronization Listener 3

void submit() Submits the currents state of an object to the server. 3

void update() This method fetches the current state of the object from the server. 3

Field Detail

STATE_INITIAL


STATE_INITIAL signalized the state of an object when it is created

STATE_I_MODIFIED

public static final int STATE_I_MODIFIED

STATE_I_MODIFIED signalizes initial modification of an object that has not yet been synchronized with the server

STATE_I_SUBMITTING

public static final int STATE_I_SUBMITTING

STATE_I_SUBMITTING this state signalizes an initial submiting of the object

Service API

277

STATE_UPDATING

public static final int STATE_UPDATING

STATE_UPDATING update of an object in order to get the corresponding document on the server

STATE_STABLE

public static final int STATE_STABLE

STATE_STABLE indicates that an object is consistant whith the corresponding object on the server

STATE_MODIFIED

public static final int STATE_MODIFIED

STATE_MODIFIED indicates that a object has been modified and thus is not consitent with the corresponding documetn on the server.

STATE_SUBMITTING

public static final int STATE_SUBMITTING

STATE_SUBMITTING indicates that the local changes are currently submitted on the server.

STATE_OUTDATED

public static final int STATE_OUTDATED

STATE_OUTDATED indicates that the object is not consistant with the object on the server

STATE_TERMINATED


STATE_TERMINATED indicates that an object is not used any more and thus can be garbage collected

Service API

278

Method Detail

update

public void update() throws IllegalStateException, SecurityException

This method fetches the current state of the object from the server. It leads to a state transition to state UPDATING. Throws:

IllegalStateException - if objec tis in state I_SUBMITTING, SUBMITTING or TERMINATED

modify

public void modify() throws IllegalStateException

This method has to be called before ANY modifications of a Synchronizable is performed. It leads to a state transition If a Synchronziable or ANY member of a Synchronizable, e.g. added Elements, Attributes, Policies, Lists are modified WITHOUT calling method modify() the changes can not be submitted, thus they do not have any effect on the document on the server. If members of a Synchronizable are changed without transition to state MODIFY the object might be inconsistent and changes overwritten when the next update() is performed. Throws:

IllegalStateException - if the method is called from an that is NOT in state STABLE or INITIAL.

reverse

public void reverse() throws IllegalStateException

This method leads to discarding all changes that have not yet been successfuly submited. Object is in state STABLE again. Throws:

IllegalStateException - if this method is called by an object that is NOT in state MODIFIED.

submit

public void submit() throws IllegalStateException, SecurityException

Submits the currents state of an object to the server. Leads to a state transition to state SUBMITTING. If the server response to this request is an error or a timeout, the object state is

Service API

279

set back to state MODIEFIED. If the server response is a Notify Synced() the object state is state STABLE. Throws:

IllegalStateException - if the object is not in state I_MODIFIED, in state MODIEFIED, or in state TERMINATED

dispose

public void dispose()

Marks a Synchronizable object for deletion on the client and terminates all resources and network activity associated with it. This method can be called in every state and leads to a state transition to state TERMINATED. An object in state TERMINATED MUST NOT be used any more as it may be reused or be subject to garbage collection. REMARK: Invocation of dispose() only affects the client side representation of a Synchronizable object and does not affect the associated XDM document stored on a server.

delete

public void delete() throws IllegalStateException, SecurityException

Marks a Synchronizable object for deletion on the client and also deletes the associated XDM document on the server. This method can be called in every state and leads to a state transition to state TERMINATED. An object in state TERMINATED MUST NOT be used any more as it may be reused or be subject to garbage collection. Throws:

IllegalStateException - if the object is a read-only document, e.g. XDMDirectory

getState


This method returns the current state of an object as defined integer value (see state constants) Returns:

state the current state of the object

isReadOnly

public boolean isReadOnly()

This method returns whether an object is read only or not

Service API

280

Returns: true if read-only object, false otherwise

getDocumentURI

public String getDocumentURI()

This method returns the document URI of the XDM document Returns:

URI of the current document

getPrincipal

public String getPrincipal()

This method returns the principal of an object Returns:

the PUID of owner of the XDM Directory document

setSynchronizationListener

public void setSynchronizationListener(SynchronizationListener listener)

This method facilitates to add a synchronization Listener Parameters:

listener - Synchronization listener to be added

Interface SynchronizationListener javax.microedition.ims.service.util

public interface SynchronizationListener

Interface SynchronizationListener provides various notification methods for instances implementing interface Synchronizable.

Method Summary Page

void processChanged(Synchronizable target) This event is triggered if the document associated with a synchronizable instance

has changed on the server. 3

void processFailure(Synchronizable target, String errorMessage) This event is triggered if a submit() or update() request could not be successfully

executed on the server. 3

Service API

281

void processSynchronized(Synchronizable target) This event is triggered if a submit() or update() request has been successfully

completed. 3

Method Detail

processChanged

public void processChanged(Synchronizable target)

This event is triggered if the document associated with a synchronizable instance has changed on the server. Upon reception of such an event, update() may be invoked on the synchronizable instance. Parameters:

target - synchronizable instance associated with the document that changed

processSynchronized

public void processSynchronized(Synchronizable target)

This event is triggered if a submit() or update() request has been successfully completed. Upon reception of such an event, the synchronizable instance makes a transition to state STABLE. Parameters:

target - synchronizable instance that has been successfully synchronized

processFailure

public void processFailure(Synchronizable target, String errorMessage)

This event is triggered if a submit() or update() request could not be successfully executed on the server. The event is generated if either an error response has been received from the server or if no response has been received within a specified period of time (timeout). Parameters:

target - object that could not be synchronized/created with the server errorMessage - identifying the failure that occoured

Class UsageEntry javax.microedition.ims.service.util

java.lang.Object javax.microedition.ims.service.util.Entry javax.microedition.ims.service.util.UsageEntry

Service API

282

public class UsageEntry extends Entry

Class UsageEntry is an extension of class Entry, representing an entry in a group usage list that contains not only a mandatory URI attribute, but also uriusage elements specifying service names indicating what the URI is used for.


UsageEntry(String uri, String service) Public constructor. 3

Method Summary Page

void addURIUsage(String service) Adds a service name representing a uri usage. 3

String[] getURIUsages() Returns the service names representing uri usages. 3

void removeURIUsage(String service) Removes a service name representing a uri usage. 3

Constructor Detail

UsageEntry

public UsageEntry(String uri, String service) throws IMSMalformedURIException

Public constructor. Parameters:

uri - URI of the entry service - service name representing a uri usage

Throws: IMSMalformedURIException - if uri is malformed

Method Detail

getURIUsages

public String[] getURIUsages()

Returns the service names representing uri usages. Returns:

service name

Service API

283

addURIUsage

public void addURIUsage(String service) throws IllegalStateException

Adds a service name representing a uri usage. Parameters:

service - name of the service Throws:


removeURIUsage

public void removeURIUsage(String service) throws IllegalStateException, IllegalArgumentException

Removes a service name representing a uri usage. Parameters:

service - name of the service Throws:

IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED. IllegalArgumentException - if the service is either not in the list of uri usages or is the very last uri usage entry and thus must not be removed.

Interface Validity javax.microedition.ims.service.util

public interface Validity

Interface Validity provides methods to access a validity specification being a part of a validity condition.

Method Summary Page

String getFrom() Returns value of 'from' attribute. 3

String getName() Returns name of the validity 3

String getUntil() Returns value of 'until' attribute. 3

Service API

284

Method Detail

getFrom

public String getFrom()

Returns value of 'from' attribute. Returns:

value of from attribute

getUntil

public String getUntil()

Returns value of 'until' attribute. Returns:

value of until attribute

getName


Returns name of the validity Returns:

name

Interface ValidityCondition javax.microedition.ims.service.util

public interface ValidityCondition

Interface ValidityCondition represents a set of validity constraints, which each specify a period of time during which a rule is valid.

Method Summary Page

void addValidity(String name, String from, String until) Adds a validity specification to the validity condition. 3

Validity[] getValidities() Returns all validity specifications of the validity condition. 3

Validity getValidity(String name) Returns the matching validity. 3

Service API

285

void removeValidity(String name) Removes a validity specification from the validity condition. 3

Method Detail

addValidity

public void addValidity(String name, String from, String until) throws IllegalArgumentException, IMSMalformedDateTimeException, IllegalStateException

Adds a validity specification to the validity condition. Parameters:

name - unique name of the validity, MUST NOT be set to null from - date/time from when on rule is valid until - date/time until when rule is valid

Throws: IllegalArgumentExceptionException - if name is set to null IMSMalformedDateTimeException - if either from or until parameters are no well defined XLM date/time strings. IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

removeValidity

public void removeValidity(String name) throws IllegalStateException

Removes a validity specification from the validity condition. Parameters:

name - name of the validity specification to be removed Throws:


getValidities

public Validity[] getValidities()

Returns all validity specifications of the validity condition. Returns:

list of validities contained in the validity condition

Service API

286

getValidity

public Validity getValidity(String name)

Returns the matching validity. Parameters:

name - name of the validity Returns:

validity with the given name, null if no matching validity was found.

Package javax.microedition.ims.service.xdm

This package defines the JSR 281 XML Document Management (XDM) API.

See: Description


Folder Interface Folder represents a folder in an directory.xml document, represented by XDMDirecotry.

3

FolderEntry Interface FolderEntry represents an entry in a folder of a directory.xml document, represented by XDMDirectory.

3

Group Interface Group represents a XDMGroup, which is a group like defined in the OMA XDM Shared Group document.

3

GroupAuthorizationRule Interface GroupAuthorizationRule facilitates specification of rules that authorize participation in group sessions.

3

GroupUsageList Interface GroupUsageList represents a list of entries containing group URIs and associated uri usage information and is stored on a server.

3

URIList Interface URIList represents a list of URIs and is stored on an XDM server.

3

XDMDirectory Interface XDMDirectory provides high level access to the document directory.xml.

3

XDMDocument Interface XDMDocument is a general abstraction of a document stored on an XDM server.

3

XDMList Interface XDMList represents a list without a URI. 3

XDMService Interface XDMService is an extension of IMSService that acts as a factory for all XDMDocuments, XDMDirectories, Groups, and lists owned by a particular public user ID.

3

Package javax.microedition.ims.service.xdm Description

Service API

287

This package defines the JSR 281 XML Document Management (XDM) API. The following diagrams illustrate the overview architecture of the XDM API. The central class of this API is the XDMManager. It creates and manages instances of Group, XDMDocument, URIList and XDMDirectory. Lists: The basic List class is the XDMList this list is only a local list, thus it does not implement Synchronizable. XDMList implements the basic list mechanismns, and is extended by URIList and GroupUsageList. A XDMList can contain entries (Entry.class), internal Lists (XDMList), and external lists (represented by a documentURI). GroupUsageList and URIList implement both Synchronizable interface. They are stored on the server and can only be modified if they are in the appropriate state.


Service API

288


Figure 3: XDM Factory (class XDMManager) and its products

Service API

289

Interface Folder javax.microedition.ims.service.xdm

public interface Folder

Interface Folder represents a folder in an directory.xml document, represented by XDMDirecotry. It is used as container for elements of type FolderEntry that represent folder entries referring to individual documents.

Method Summary Page

String getAUID() Returns the application usage ID of the folder. 3

FolderEntry[] getEntries() Returns all entries of a folder. 3

String getErrorCode() Returns the error code associated with the XDM folder. 3

Method Detail

getAUID

public String getAUID()

Returns the application usage ID of the folder. Returns:

application usage ID

getEntries

public FolderEntry[] getEntries()

Returns all entries of a folder. Returns:

list of entries contained in this folder, or an empty array if the folder does not contain any entries

getErrorCode

public String getErrorCode()

Returns the error code associated with the XDM folder. Returns:

error code of the folder; null if not present

Service API

290

Interface FolderEntry javax.microedition.ims.service.xdm

public interface FolderEntry

Interface FolderEntry represents an entry in a folder of a directory.xml document, represented by XDMDirectory. A FolderEntry contains a reference to an individual XDM document.

Method Summary Page

String getDocumentURL() Returns the URL of the XDM document referred to by the entry. 3

String getEtag() Returns a server computed etag value of the current instance of the XDM

document referred to y the entry. 3

String getLastModified() Returns the date/time when the XDM document referred to by the entry was last

modified. 3

String getSize() Returns the size of the XDM document in octets. 3

Method Detail

getDocumentURL

public String getDocumentURL()

Returns the URL of the XDM document referred to by the entry. Returns:

URL of document

getEtag

public String getEtag()

Returns a server computed etag value of the current instance of the XDM document referred to y the entry. (This allows the XCAP client to determine whether the locally cached copy of a document is up-to-date.) Returns:

etag value of the document, null if not present

Service API

291

getLastModified

public String getLastModified()

Returns the date/time when the XDM document referred to by the entry was last modified. Returns:

modification time of document; null if not present

getSize

public String getSize()

Returns the size of the XDM document in octets. Returns:

size of the document; null if not present

Interface Group javax.microedition.ims.service.xdm


All Known Subinterfaces: PoCGroup

public interface Group extends Synchronizable

Interface Group represents a XDMGroup, which is a group like defined in the OMA XDM Shared Group document. It offers features for oranizing lists, attributes and premissions.A group is persistently stored on the Server, therefore it implements the Synchronizable interface, thus one has to call the modify() method in order to being able to edit the object, which is only possible in state MODIFIED. This group is an entity that may be used by different types of applications, e.g. PoC. In order to be adaptable to specifics of particular applications, group offers an extension mechanism by allowing addition of arbitrary attributes and elements.

Method Summary Pagevoid addAttribute(Attribute attr)

This method adds an Attribute to a group. 3

String addAuthorizationRule(int type) Adds a group authorization rule to the group. 3

Service API

292

void addElement(Element elem) This method adds an Element to a group. 3

void allowInviteMembers(boolean flag) This flag changes the group, therefore modify has to be called

before chaning this setting 3

Attribute[] getAttributes() Returns a list of all attributes within this group 3

GroupAuthorizationRule getAuthorizationRule(String id) Returns the group authorization rule specified by ID. 3

String[] getAuthorizationRuleIDs() Returns the IDs of all group authorization rules being part of the

policy. 3

String getDisplayname() Returns the group's display name 3

Element[] getElements() Returns an array of elements previously added to the group 3

String getGroupURI() This method returns the URI of the group 3

int getMaxParticipantCount() Returns the maximum number of participants allowed 3

XDMList getMemberList() This method returns the member list of a group 3

boolean isInviteMembersAllowed() Returns whether invitation of members is allowed 3

void removeAttribute(Attribute attr) This method removes an Attribute from a group. 3

void removeAuthorizationRule(String id) Removes the group authorization rule specified by ID from the

group. 3

void removeElement(Element elem) This method removes an Element from a group. 3

void setDisplayname(String name) This method changes the displayname of a group. 3

void setGroupURI(String uri) This method sets the URI of the group 3

void setMaxParticipantCount(int count) Changes the settings for maximum participants allowed. 3

Method Detail

setGroupURI

public void setGroupURI(String uri)

Service API

293

This method sets the URI of the group Parameters:

uri - of the group

getGroupURI

public String getGroupURI()

This method returns the URI of the group Returns:

uri of the group

setDisplayname

public void setDisplayname(String name) throws IllegalStateException

This method changes the displayname of a group. Parameters:

name - the displayname that should be set for the current group Throws:


getDisplayname

public String getDisplayname()

Returns the group's display name Returns:

the current displayName of the group; null if displayName is not set

addAttribute

public void addAttribute(Attribute attr) throws IllegalStateException

This method adds an Attribute to a group. Parameters:

attr - to be added Throws:


Service API

294

removeAttribute

public void removeAttribute(Attribute attr) throws IllegalStateException

This method removes an Attribute from a group. Parameters:

attr - attribute that should be removed Throws:


getAttributes

public Attribute[] getAttributes()

Returns a list of all attributes within this group Returns:

array of all attributes; or an empty list if group does not have any attributes

getMemberList

public XDMList getMemberList()

This method returns the member list of a group Returns:

groups' memberlist; null if group list does not exist

allowInviteMembers

public void allowInviteMembers(boolean flag) throws IllegalStateException

This flag changes the group, therefore modify has to be called before chaning this setting Parameters:

flag - true if InviteMember is allowed, false if InviteMember is not allowed Throws:


isInviteMembersAllowed

public boolean isInviteMembersAllowed()

Returns whether invitation of members is allowed Returns:

the value of MembersAllowed setting; true if InviteMember is allowed, false if InviteMember is not allowed

Service API

295

setMaxParticipantCount

public void setMaxParticipantCount(int count) throws IllegalStateException

Changes the settings for maximum participants allowed. Parameters:

count - number of maximum participants Throws:


getMaxParticipantCount

public int getMaxParticipantCount()

Returns the maximum number of participants allowed Returns:

maximum participants allowed in the group

addAuthorizationRule

public String addAuthorizationRule(int type) throws IllegalStateException, IllegalArgumentException

Adds a group authorization rule to the group. Parameters:

type - condition type of the group authorization rule Returns:

ID of group authorization rule that has been added Throws:

IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED. IllegalArgumentException - if type is invalid

removeAuthorizationRule

public void removeAuthorizationRule(String id) throws IllegalStateException

Removes the group authorization rule specified by ID from the group. Parameters:

id - ID of group authorization rule to be removed from the group Throws:


Service API

296

getAuthorizationRule

public GroupAuthorizationRule getAuthorizationRule(String id)

Returns the group authorization rule specified by ID. Parameters:

id - ID of group authorization rule Returns:

authorization rules; null if rule does not exist

getAuthorizationRuleIDs

public String[] getAuthorizationRuleIDs()

Returns the IDs of all group authorization rules being part of the policy. Returns:

list of IDs of group authorization rules; empty array if there are none

addElement

public void addElement(Element elem) throws IllegalStateException

This method adds an Element to a group. Parameters:

elem - Element that should be added Throws:


removeElement

public void removeElement(Element elem) throws IllegalStateException

This method removes an Element from a group. Parameters:

elem - Element that should be removed Throws:

IllegalStateException - if the object is not in state MODIFIED or in state STATE_I_MODIFIED.

getElements


Returns an array of elements previously added to the group

Service API

297

Returns: Array of Elements contained in the group; an empty array if no elements exist

Interface GroupAuthorizationRule javax.microedition.ims.service.xdm


public interface GroupAuthorizationRule extends BasicRule

Interface GroupAuthorizationRule facilitates specification of rules that authorize participation in group sessions. These rules are part of a group document and thus are not stored as a separate document on an XDM server.

Field Summary Page

int TYPE_MEMBER Constant representing the <is-list-member> condition 3

Method Summary Page

void allowAnonymousParticipant(boolean flag) Controls whether anonymous participants are allowed. 3

void allowConferenceStateEvents(boolean flag) Controls whether subscription to the conference state event package is allowed. 3

void allowInitiateConference(boolean flag) Controls whether initation of a conference is allowed. 3

void allowInviteUsersDynamically(boolean flag) Controls whether users can be invited dynamically. 3

void allowJoining(boolean flag) Controls whether users are allowed to join a group session. 3

boolean isAnonymousParticipantAllowed() Returns whether anonymous participants are allowed. 3

boolean isConferenceStateAllowed() Returns whether subscription to the conferecen state event package is allowed 3

boolean isInitiateConferenceAllowed() Returns whether initiation of conferences is allowed. 3

boolean isInviteUsersDynamicallyAllowed() Returns whether dynamic invitation of users is allowed. 3

boolean isJoiningAllowed() Returns whether users are allowed to join a group session 3

Service API

298

boolean isKeyParticipant() Returns whether the identity matching with the condition part of the rule is a

Distinguished Participant in a one-to-many-to-one topology. 3

void setKeyParticipant(boolean flag) Specifies that the identity matching with the condition part of the rule is a

Distinguished Participant in a one-to-many-to-one topology. 3

Field Detail

TYPE_MEMBER

public static final int TYPE_MEMBER

Constant representing the <is-list-member> condition

Method Detail

allowConferenceStateEvents

public void allowConferenceStateEvents(boolean flag) throws IllegalStateException

Controls whether subscription to the conference state event package is allowed. Parameters:

flag - true if subscription is to be allowed, false otherwise Throws:


isConferenceStateAllowed

public boolean isConferenceStateAllowed()

Returns whether subscription to the conferecen state event package is allowed Returns:

true if subscription is allowed, false otherwise

allowInviteUsersDynamically

public void allowInviteUsersDynamically(boolean flag) throws IllegalStateException

Controls whether users can be invited dynamically. Parameters:

flag - true if inviting users dynamically is allowed, false otherwise

Service API

299


isInviteUsersDynamicallyAllowed

public boolean isInviteUsersDynamicallyAllowed()

Returns whether dynamic invitation of users is allowed. Returns:

the current InviteUsersDynamically state

allowJoining

public void allowJoining(boolean flag) throws IllegalStateException

Controls whether users are allowed to join a group session. Parameters:

flag - true if joining is allowed, false if joining is not be allowed Throws:


isJoiningAllowed

public boolean isJoiningAllowed()

Returns whether users are allowed to join a group session Returns:

the current JoiningAllowed flag

allowInitiateConference

public void allowInitiateConference(boolean flag) throws IllegalStateException

Controls whether initation of a conference is allowed. Parameters:

flag - true if initiating conferences is allowed, false if initiating conferences is not be allowed


Service API

300

isInitiateConferenceAllowed

public boolean isInitiateConferenceAllowed()

Returns whether initiation of conferences is allowed. Returns:

the current InitatingConference flag

allowAnonymousParticipant

public void allowAnonymousParticipant(boolean flag) throws IllegalStateException

Controls whether anonymous participants are allowed. Parameters:

flag - true if anonymous participants are allowed, false if anonymous participants are not be allowed


isAnonymousParticipantAllowed

public boolean isAnonymousParticipantAllowed()

Returns whether anonymous participants are allowed. Returns:

the current AnonymousParticipate flag

setKeyParticipant

public void setKeyParticipant(boolean flag) throws IllegalStateException

Specifies that the identity matching with the condition part of the rule is a Distinguished Participant in a one-to-many-to-one topology. Parameters:

flag - code>true if user is a Distinguished Participant, false otherwise Throws:


isKeyParticipant

public boolean isKeyParticipant()

Service API

301

Returns whether the identity matching with the condition part of the rule is a Distinguished Participant in a one-to-many-to-one topology. Returns:

true if user is a Distinguished Participant, false otherwise

Interface GroupUsageList javax.microedition.ims.service.xdm

All Superinterfaces: Synchronizable, XDMList

public interface GroupUsageList extends XDMList, Synchronizable

Interface GroupUsageList represents a list of entries containing group URIs and associated uri usage information and is stored on a server. When building group usage lists, the following restrictions apply:

• the parent list as well as the child lists may not contain references to external lists or references to external entries.

• all entries must be instances of UsageEntry that also contains uri usage information

If these restrictions are not followed, an error results when the group usage list is to be stored on the server. Thus, the implementation of group usage list should ensure that these restrictions are obeyed.

Method Summary Page

void addEntry(Entry newEntry) overloaded method from parent Class XDMList; This method always throws an

Illegal arguemtn exception since ONLY UsageEntries are allowed in a Group usage list.

3

void addEntry(UsageEntry newEntry) This methods adds a new Entry to the GroupUsageList 3

String[] getURIUsages() Returns all uri usages used in all entries of the group usage list. 3

Method Detail

getURIUsages

public String[] getURIUsages()

Returns all uri usages used in all entries of the group usage list.

Service API

302

Returns: list of service names

addEntry

public void addEntry(UsageEntry newEntry)

This methods adds a new Entry to the GroupUsageList Parameters:

newEntry - Usage entry to be added

addEntry

public void addEntry(Entry newEntry) throws IllegalArgumentException

overloaded method from parent Class XDMList; This method always throws an Illegal arguemtn exception since ONLY UsageEntries are allowed in a Group usage list. Specified by:

addEntry in interface XDMList Parameters:

newEntry - entry to be added Throws:

IllegalArgumentException - always thrown since this method must not be called with an Entry parameter, only UsageEntries are allowed

Interface URIList javax.microedition.ims.service.xdm

All Superinterfaces: Synchronizable, XDMList

public interface URIList extends XDMList, Synchronizable

Interface URIList represents a list of URIs and is stored on an XDM server.

Interface XDMDirectory javax.microedition.ims.service.xdm


Service API

303

public interface XDMDirectory extends Synchronizable

Interface XDMDirectory provides high level access to the document directory.xml. Since every directory.xml is read only, this object must not be altered. If so, an IllegalStateException is thrown. Example code:

public class MyExample { private XDMDirectory myXDMDirectory; private XDMService service; //constructor public MyExample(XDMService service) { ... this.service = service; myXDMDirectory = new myXDMDirectory(); ... } pulbic void doSomething() { ... //looking for the group named "MyFriends" Folder[] friends = myXDMDirectory.findGroups("MyFriends"); if (friends!=null) { //this folder contains a group named MyFriends or a group that //name contains MyFriends as substring ... try { //catch the Group from the server //get the URL from the FolderEntry Group myFriends = service.getGroup(friends.getDocumentURL()); }catch (IMSMalformedURIException mue){ //uri is not formatted correctly }//catch }//if ... }//doSomething }//myExample

Method Summary Page

Folder[] findDocument(String searchParam) Wildcard search for a term that is contained in any folder element of any XDM

document (including groups). 3

Folder[] findGroups(String searchParam) Wildcard search for a term that is contained in any folder element of a group. 3

Folder[] getAllGroups() Returns all groups contained in the directory.xml 3

Folder[] getErroneousFolders(String auid) Returns all folders containing any erroneous entries. 3

Service API

304

Folder[] getFolders(String auid) Returns all folders contained in the document 3

String getHeader() Returns the header of the document 3

Method Detail

getHeader

public String getHeader()

Returns the header of the document Returns:

the header of the XDM Directory document

getFolders

public Folder[] getFolders(String auid)

Returns all folders contained in the document Parameters:

auid - application usage ID, may contain asterisks as wildcard characters Returns:

the folder for the AUID specified; if AUID contains wildcard characters, all matching folders are returned\

getErroneousFolders

public Folder[] getErroneousFolders(String auid)

Returns all folders containing any erroneous entries. Parameters:

auid - Application Usage ID, may contain asterisks as wildcard characters Returns:

the folder for the AUID specified if there are XDMS errors i.e. the folder containing entries containing a non-empty error-code element for the given AUID; if AUID contains wildcard characters, all matching folders with errors are returned.

getAllGroups

public Folder[] getAllGroups()

Returns all groups contained in the directory.xml Returns:

list of folders containing information about all groups in directory.xml or an empty list if no groups are contained

Service API

305

findGroups

public Folder[] findGroups(String searchParam)

Wildcard search for a term that is contained in any folder element of a group. The asterisk (*) can be used as wildcard to replace zero to many [0...n] characters. Parameters:

searchParam Returns:

list of folders containing information about groups that match the given search parameter

findDocument

public Folder[] findDocument(String searchParam)

Wildcard search for a term that is contained in any folder element of any XDM document (including groups). The asterisk (*) can be used as wildcard to replace zero to many [0...n] characters. Parameters:

searchParam Returns:

list of folders containing information about documents that match the given search parameter

Interface XDMDocument javax.microedition.ims.service.xdm


public interface XDMDocument extends Synchronizable

Interface XDMDocument is a general abstraction of a document stored on an XDM server. XDMDocument can represent any kind of XDM document. Method getContentAsString() provides access to the raw XML code, thus allowing usage of any XML parser.

Method Summary Page

String getContentAsString() Returns the whole content of the document. 3

String getContentType() Returns the content type of the document 3

Element getRootElement() Returns the element of the document 3

Service API

306

void setContentType(String contentType) Sets the content type of a document. 3

Method Detail

getContentType


Returns the content type of the document Returns:

the content type

setContentType

public void setContentType(String contentType) throws IllegalStateException, IllegalArgumentException

Sets the content type of a document. Parameters:

contentType - content type to be set for the document Throws:

IllegalStateException - if object is not in state MODIFIED or in state STATE_I_MODIFIED. IllegalArgumentException - if the specified content type is invalid

getRootElement

public Element getRootElement()

Returns the element of the document Returns:

root element

getContentAsString

public String getContentAsString()

Returns the whole content of the document. Returns:

text string

Service API

307

Interface XDMList javax.microedition.ims.service.xdm

All Known Subinterfaces: GroupUsageList, URIList

public interface XDMList

Interface XDMList represents a list without a URI. This kind of list is only local in a document, and thus no URI is required. Its display name is used for identification. A list can contain entries, which consist of URIs and display name, or sub-lists or references to external lists stored in separate documents.

Method Summary Page

void addEntry(Entry newEntry) Puts a new entry into the list. 3

void addExternalList(String uri) Puts a new external list into the list. 3

void addList(String name) Puts a new sub-list with given name into the list. 3

Entry[] getEntries() Retrieves all entries stored in the list. 3

Entry getEntry(String uri) Returns the entry specified by URI. 3

String getExternalListName(String uri) Gets the display name of the external list specified by uri. 3

String[] getExternalLists() Retrieves all external lists stored in list. 3

XDMList getList(String name) Returns the sub-list specified by name. 3

String[] getListNames() Returns the names of all sub-lists stored in list. 3

XDMList[] getLists() Returns all sub-lists stored in list. 3

String getName() Returns the name of the list 3

void removeEntry(String uri) Removes the entry specified by URI from the list. 3

void removeExternalList(String uri) This method deletes the entry which is identified by the given URI. 3

Service API

308

void removeList(String name) Removes the sub-list specified by URI from the list. 3

void setExternalListName(String uri, String displayname) Assigns a display name to the external list specified by uri. 3

void setName(String name) Sets the name of the list 3

Method Detail

setName

public void setName(String name) throws IllegalStateException

Sets the name of the list Parameters:

name - the name of the list Throws:


getName


Returns the name of the list Returns:

the name of the list; may be null if name is not defined

addEntry

public void addEntry(Entry newEntry) throws IllegalStateException

Puts a new entry into the list. Parameters:

newEntry - entry to be added to the list Throws:


removeEntry

public void removeEntry(String uri) throws IMSMalformedURIException, IllegalStateException

Service API

309

Removes the entry specified by URI from the list. Parameters:

uri - URI of entry to be removed Throws:

IMSMalformedURIException - if the uri is malformed IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

getEntry

public Entry getEntry(String uri) throws IMSMalformedURIException

Returns the entry specified by URI. Parameters:

uri - uri of the entry Returns:

entry Throws:

IMSMalformedURIException - if the uri is malformed

getEntries

public Entry[] getEntries()

Retrieves all entries stored in the list. Returns:

array of entries

addList

public void addList(String name) throws IllegalArgumentException, IllegalStateException

Puts a new sub-list with given name into the list. Parameters:

name - name of sub-list to be added Throws:

IllegalArgumentException - if the specified name is already in use in the parent list. IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

removeList

public void removeList(String name) throws IllegalStateException

Service API

310

Removes the sub-list specified by URI from the list. Parameters:

name - name of sub-list to be removed Throws:


getList

public XDMList getList(String name)

Returns the sub-list specified by name. Returns:

sub-list; null if not existing

getListNames

public String[] getListNames()

Returns the names of all sub-lists stored in list. Returns:

array of names of sub-Lists

getLists

public XDMList[] getLists()

Returns all sub-lists stored in list. Returns:

array of sub-Lists

addExternalList

public void addExternalList(String uri) throws IMSMalformedURIException, IllegalStateException

Puts a new external list into the list. Parameters:

uri - uri of the external list. Uri may be a HTTP URI referencing the whole resource-lists document or a XCAP node selector (extended HTTP URI) that references a single list.

Throws: IMSMalformedURIException - if the uri is malformed IllegalStateException - if this method is invoked upon a GroupUsageList or if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

Service API

311

getExternalListName

public String getExternalListName(String uri) throws IMSMalformedURIException, IllegalArgumentException

Gets the display name of the external list specified by uri. Parameters:

uri - uri of the external list Returns:

display name assigned to the external list Throws:

IMSMalformedURIException - if the uri is malformed IllegalArgumentException - if the list specified by uri is not referenced as external list

setExternalListName

public void setExternalListName(String uri, String displayname) throws IMSMalformedURIException, IllegalArgumentException, IllegalStateException

Assigns a display name to the external list specified by uri. Parameters:

uri - uri of the external list displayname - display name to be assigned to the external list entry

Throws: IMSMalformedURIException - if the uri is malformed IllegalArgumentException - if the list specified by uri is not referenced as external list IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

removeExternalList

public void removeExternalList(String uri) throws IMSMalformedURIException, IllegalStateException

This method deletes the entry which is identified by the given URI. Parameters:

uri - URI of entry to be removed. Throws:

IMSMalformedURIException - if the uri is malformed IllegalStateException - if the Synchronizable container of the object is not in state MODIFIED or in state STATE_I_MODIFIED.

Service API

312

getExternalLists

public String[] getExternalLists()

Retrieves all external lists stored in list. Returns:

array of external Lists

Interface XDMService javax.microedition.ims.service.xdm


public interface XDMService extends ImsService

Interface XDMService is an extension of IMSService that acts as a factory for all XDMDocuments, XDMDirectories, Groups, and lists owned by a particular public user ID. XDMService also acts as a registry for those entities. It is created via the createService() method of IMSManager if the proper application ID for the XMD service is used. XDM documents are stored on the XDM server, which does not support synchronization. This means that submitting the documents overwrites all changes that have priviously been submitted to the server. The API does not cover merging or server synchronization issues. Code Example - How to work with an XDMService

public class MyXDMApplication { private XDMService xdm_service; public MyXDMApplication() { ... xdm_service = null; } public void doSomething { ... //initializing the XDMSerive by the usage of IMSManager xdm_service = IMSManager.createService(XDM, myPUID); XDMDocument myGroup = null; try { myGroup = xdm_service.getGroup(aValidDocumentURI); }catch (MalformedURIException muriE) { //URI is not valid } ... do something ... //TODO algin the creation method for XDMService!!! try { //setting maximum Participants to 8 myGroup.setMaxParticipantsCount(8); //get the groups MemberList and check if Simon is a member Entries[] myEntries = myGroup.getMemeberList.getEntries(); Entry simon = null; int i=0;

Service API

313

int length=myEntries.length()-1; while ((Entry)myEntries[i].getDisplayName()!="Simon" && i< length) { i++; }//while //found the Entry Simon if(i!=length){ simon =myEntries[i]; //changing DisplayName from Simon to Simone simon.setDisplayName("Simone"); }//if //submit changes to server myGroup.submit(); }catch(SecurityException se) { //application does not have sufficient rights to contact the //server and submit a new document ... do something ... }catch(IllegalStateException ise) { //group is not in the correct state, thus entry MUST NOT be altered ... do something ... } .... }//doSomething }//MyXDMApplication

Method Summary Page

XDMDocument createDocument(String documentURI, String contentType) Creates a new document, which is not yet present on the server. 3

Group createGroup(String documentURI) Creates a new group, which is not yet present on the server. 3

GroupUsageList createGroupUsageList(String documentURI) Creates a new GroupUSageList instance, which is not yet present on the

server. 3

URIList createURIList(String documentURI) Creates a new URIList instance, which is not yet present on the server. 3

XDMDirectory getDirectory() Returns the directory.xml for the current user. 3

XDMDocument getDocument(String documentURI) Fetches the content of a document from the server. 3

Group getGroup(String documentURI) Fetches a group from server and creates a respective group instance or

returns local group instance, if available. 3

Group[] getGroups() Returns all local groups 3

GroupUsageList getGroupUsageList(String documentURI) Fetches a group usage list from server and creates a respective

GroupUsageList instance or returns local GroupUsageList instance, if available.

3

GroupUsageList[] getGroupUsageLists() Returns all local group usage lists. 3

Service API

314

XDMDocument[] getLocalDocuments() Returns all documents that are available locally on the client 3

URIList getURIList(String documentURI) Fetches a uri list from server and creates a respective URIList instance or

returns a local URIList instance, if available. 3

URIList[] getURILists() Returns all local uri lists. 3

Method Detail

createDocument

public XDMDocument createDocument(String documentURI, String contentType) throws IMSMalformedURIException, IMSObjectExistsException, IllegalArgumentException, SecurityException

Creates a new document, which is not yet present on the server. If the document already exists, a IMSObjectExists exception is thrown. One has the chance to fetch the document from the server by calling getDocument. A subscription for changes within this document is automatically made when the changes are submited to the server. To unsubscribe one has to locally dispose the document. Parameters:

documentURI - specifies the URI under which the document is stored on the server. contentType - specifies the content type of the document.

Returns: new XDMDocument

Throws: IMSMalformedURIException - if documentURI is malformed IMSObjectExistsException - if a document with the name documentURI already exists IllegalArgumentException - if the specified content type is invalid SecurityException - if permission not granted

createGroup

public Group createGroup(String documentURI) throws IMSMalformedURIException, IMSObjectExistsException, SecurityException

Creates a new group, which is not yet present on the server. If the group already exists, an IMSObjectExists exception is thrown. One has the chance to fetch the group from the server by calling getGroup. A subscription for changes within this group is automatically made when the changes are submited to the server. To unsubscribe one has to locally dispose the group. Parameters:

documentURI - specifies the uri under which the group is stored on the server.

Service API

315

Returns: group instance

Throws: IMSMalformedURIException - if documentURI is malformed IMSObjectExistsException - if a document with the name documentURI already exists SecurityException - if permission is not granted

createURIList

public URIList createURIList(String documentURI) throws IMSObjectExistsException, IMSMalformedURIException, SecurityException

Creates a new URIList instance, which is not yet present on the server. If the URI list already exists, an IMSObjectExistsException is thrown. One has the chance to fetch the URI list from the server by calling getURIList. A subscription for changes within this uri list is automatically made when the changes are submited to the server. To unsubscribe one has to locally dispose the URI list. Parameters:

documentURI - specifies the URI under which the list is stored on the server. Returns:

URIList instance Throws:

IMSMalformedURIException - if documentURI is malformed IMSObjectExistsException - if a document with the name documentURI already exists SecurityException - if permission is not granted

createGroupUsageList

public GroupUsageList createGroupUsageList(String documentURI) throws IMSObjectExistsException, IMSMalformedURIException, SecurityException

Creates a new GroupUSageList instance, which is not yet present on the server. If the group usage list already exists, an IMSObjectExistsException is thrown. One has the chance to fetch the group usage list from the server by calling getURIList. A subscription for changes within this URIList is automatically made when the changes are submited to the server. To unsubscribe one has to locally dispose the group usage list. Parameters:

documentURI - specifies the uri under which the list is stored on the server. Returns:

GroupUsageList instance Throws:

IMSMalformedURIException - if documentURI is malformed IMSObjectExistsException - if a document with the documentURI already exists SecurityException - if permission is not granted

Service API

316

getDocument

public XDMDocument getDocument(String documentURI) throws IMSMalformedURIException, SecurityException

Fetches the content of a document from the server. This automatically leads to a subscription for changes for the given document. To unsubscribe, one has to dispose the document locally. Parameters:

documentURI - URI of the document that should be retrieved Returns:

document with the specified documentURI, null if document does not exist Throws:

IMSMalformedURIException - if URI is malformed SecurityException - if permission is not granted

getLocalDocuments

public XDMDocument[] getLocalDocuments()

Returns all documents that are available locally on the client Returns:

Array with XDMDocuments locally available for the current user.

getDirectory

public XDMDirectory getDirectory() throws SecurityException

Returns the directory.xml for the current user. Returns:

object that contains directory.xml content for the current user; null if no directory.xml is existent


getGroup

public Group getGroup(String documentURI) throws IMSMalformedURIException, SecurityException

Fetches a group from server and creates a respective group instance or returns local group instance, if available. This leads automatically to a subscription for group changes for the given group. To unsubscribe, one has to dispose the group locally. Parameters:

documentURI - uri representing the group to be retrieved

Service API

317

Returns: group; null if no group matches

Throws: IMSMalformedURIException - if documentURI is malformed SecurityException - if permission is not granted

getURIList

public URIList getURIList(String documentURI) throws IMSMalformedURIException, SecurityException

Fetches a uri list from server and creates a respective URIList instance or returns a local URIList instance, if available. This automatically leads to a subscription for changes for the given uri list. To unsubscribe, one has to dispose the uri list locally. Parameters:

documentURI - uri representing the uri list to be retrieved Returns:

uri list; null if no uri list matches Throws:

IMSMalformedURIException - if documentURI is malformed SecurityException - if permission is not granted

getGroupUsageList

public GroupUsageList getGroupUsageList(String documentURI) throws IMSMalformedURIException, SecurityException

Fetches a group usage list from server and creates a respective GroupUsageList instance or returns local GroupUsageList instance, if available. This automatically leads to a subscription for changes for the given group usage list. To unsubscribe, one has to dispose the group usage list locally. Parameters:

documentURI - URI representing the group usage to be retrieved Returns:

group usage list; null if no group usage list matches Throws:

IMSMalformedURIException - if documentURI is malformed SecurityException - if permission is not granted

getGroups

public Group[] getGroups()

Returns all local groups Returns:

a list of groups

Service API

318

getURILists

public URIList[] getURILists()

Returns all local uri lists. Returns:

a list uri lists

getGroupUsageLists

public GroupUsageList[] getGroupUsageLists()

Returns all local group usage lists. Returns:

a list group usage lists

Glossary

319

8 Glossary

Accept list Formerly known as white list. Is a list of users that are explicitly allowed to contact a user by a certain service.

Access list A access list can be either an accept list or a reject list (formerly known as black and white list)

Closed group Has a member list. Only users being on the member list are allowed to utilize this group.

Contact List A list of users that are represented by a URI and a display name. A simple form of an address book.

Group list A group is a predefined set of users together with its attributes. It provides a means to establishment of communication sessions. Group is a basic identity which means that it can be handled as a standalone entity (apart from some cases when it makes no sense to do so, e. g. Contact lists containing groups cannot constitute the basis of a presence enhanced phone book since a group has no presence). It can be, for example, included in an accept/reject list. A group can be addressed by its SIP URI and session is established with all group members. The type of the session depends on the service which uses the group. The group consists of its own attributes, a member list with member attributes and a reject list.

Group Reject list Group reject list defines the users who do not have the opportunity to participate in the communication established based on the given group (independently from the type of the communication). When reject list is used, member list should no be in use, since except for the users listed on the reject list everybody is accepted (e.g. open chat group).

IMS Session Is a Point-2-point IMS services session based on SIP Dialog including media connections

Member list Group member list defines the users who have the opportunity to participate in the communication established based on the given group (independently from the type of the communication). When member list is used, reject list should be empty and not be in use, since except for the members everybody is rejected.

Open group Has a reject list. Everybody is allowed to use the group except those on the reject list. An open group does not utilize a member list.