|
||||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
| Packages | |
|---|---|
| javax.microedition.sip | This specification defines the JSR180, SIP API for J2ME. |
This document defines JSR 180, the SIP API for Java ME API, version 1.2.
Author: Java Community Process / JSR 180 Expert Group (e-mail: [email protected])
Status: Maintenance Release
Released: 2008-24-12
Copyright © 2004-2008 Nokia Corporation. All rights reserved.| Version | Published | Description |
|---|---|---|
| 1.2. | 2008-24-12 | Maintenance Release |
NOKIA CORPORATION IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE TERMS CONTAINED IN THIS LICENSE ( “LICENSE” ). PLEASE READ THE TERMS AND CONDITIONS OF THIS LICENSE CAREFULLY. BY ACCESSING OR USING THE SPECIFICATION YOU WILL BE BOUND BY THE TERMS OF THIS LICENSE.
JSR 180 SIP API (“Specification”)
Specification Lead: Nokia Corporation ( “Specification Lead” )
Version: 1.2.
Status: Maintenance Release
Release: 2008-24-12
Copyright 2004-2008 Nokia Corporation. All rights reserved.
1. NOTICE; LIMITED LICENSE GRANTS
1.1 The Specification Lead hereby grants You a non-exclusive, non-transferable, worldwide, royalty-free, fully paid-up, limited license (without the right to sublicense) solely under intellectual property rights licensable by the Specification Lead to analyze and to use the Specification for research, evaluation, optimization and development purposes. In addition You may make a reasonable number of verbatim copies of this Specification in its entirety for Your private or internal use, as applicable, in accordance with the terms and conditions of this License.
1.2 No rights are granted under this License for internal deployment, the creation and/or distribution of implementations of the Specification for direct or indirect (including strategic) gain or advantage, the modification of the Specification (other than to the extent of Your fair use rights) or the distribution of the Specification or making the Specification available for 3rd parties.
1.3 Except as expressly set forth in this license, You acquire no right, title or interest in or to Specification or any other intellectual property licensable by the Specification Lead and no other rights are granted by implication, estoppel or otherwise. The Specification may only be used in accordance with the license terms set forth herein. This License will terminate immediately without notice from Specification Lead if You fail to comply with any provision of this License.
2. TRADEMARKS
2.1 Nokia is a registered trademark of Nokia Corporation. Nokia Corporation's product names are either trademarks or registered trademarks of Nokia Corporation. Your access to this Specification should not be construed as granting, by implication, estoppel or otherwise, any license or right to use any marks appearing in the Specification without the prior written consent of Nokia Corporation or Nokia's licensors. No right, title, or interest in or to any trademarks, service marks, or trade names of any third parties, is granted hereunder.
2.2 You shall not be allowed to remove any of the copyright statements or disclaimers or other proprietary notices contained in the Specification and You are obliged to include the copyright statement and the disclaimers, if any, in any copies of the Specification You make.
3. DISCLAIMER OF WARRANTIES
3.1 SUBJECT TO ANY STATUTORY WARRANTIES OR CONDITIONS WHICH CAN NOT BE EXCLUDED, THE SPECIFICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OR CONDITION OF ANY KIND EITHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, AND STATUTORY ARE HEREBY DISCLAIMED. THE ENTIRE RISK ARISING OUT OF OR RELATING TO THE USE OR PERFORMANCE OF THE SPECIFICATION REMAINS WITH YOU.
3.2 THE SPECIFICATION MAY INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. 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.
4. LIMITATION OF LIABILITY
4.1 TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL THE SPECIFICATION LEAD OR ITS SUPPLIERS BE LIABLE FOR ANY LOST PROFITS, LOST SAVINGS, LOST REVENUE, LOST DATA, PROCUREMENT OF SUBSTITUE GOODS, OR FOR ANY DIRECT, INDIRECT, INCIDENTIAL, SPECIAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, EVEN IF THE SPECIFICATION LEAD OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. IN ADDITION THE SPECIFICATION LEAD AND ITS SUPPLIERS WILL NOT BE LIABLE FOR ANY DAMAGES CLAIMED BY YOU BASED ON ANY THIRD PARTY CLAIM.
4.2 Some jurisdictions do not allow the exclusion of implied warranties, or the limitation for consequential damages, so Section 4.1 may not apply to You in whole, but in such case Section 4.1 will apply to You to the maximum extent permitted by applicable law.
5. EXPORT CONTROL
5.1 You shall follow all export control laws and regulations relating to Specification.
6. RESTRICTED RIGHTS LEGEND
6.1 Note to U.S. Government Users. The Specification is a “Commercial Items” , as that term is defined at 48 C.F.R. 2. 101, consisting of “Commercial Computer Software” and “ Commercial Computer Software Documentation ” , as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software Documentation are being licensed to U.S. Government end users a) only as Commercial Items and b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States.
This specification defines a J2ME Optional Package that enables resource limited devices (referred to as 'terminals' in the following) to send and receive SIP messages. The API is designed to be a compact and generic SIP API, which provides SIP functionality in transaction level. The API is integrated into the Generic Connection Framework defined in Connected, Limited Device Configuration (CLDC).
The SIP API for J2ME is designed as an Optional Package that can be used with many J2ME Profiles. The minimum platform required by this API is the J2ME CLDC v1.0. The API can also be used with the J2ME Connected Device Configuration (CDC).
The picture below shows the simplified class diagram of
the API, relations between classes, inheritance from
javax.microedition.io.Connection and relation to
javax.microedition.io.Connector.
The SIP API is used by the applications to implement SIP User Agent (UA) functionality. The following picture shows what interfaces terminals A and B are using to implement SIP User Agent Client (UAC) and User Agent Server (UAS) functionality respectively. See Glossary for explanation of UAC and UAS functionality.
In reality applications will use both SIP client and server connections in the same terminal (terminal A in picture below) and thus implementing both UAC and UAS functionality.
The following code examples shows how to open SIP
connections and the usage of the main classes
SipClientConnection,
SipServerConnection and
SipConnectionNotifier.
Examples of helper classes:
SipDialog,
SipAddress,
SipHeader and
RefreshHelper
are shown in the API documentation. The example
below shows how to open a SIP client connection,
send one request and receive a response. The
interface used in this simple client connection
example is SipClientConnection.
public void sendTextMessage(String msg)
{
SipClientConnection sc = null;
try
{
// open SIP connection
sc = (SipClientConnection) Connector.open("sip:[email protected]:5060");
// initialize SIP request MESSAGE
sc.initRequest("MESSAGE", null);
// set some headers
sc.setHeader("From", "sip:[email protected]");
sc.setHeader("Subject", "testing...");
// write message body
sc.setHeader("Content-Type", "text/plain");
sc.setHeader("Content-Length", Integer.toString(msg.length()));
OutputStream os = sc.openContentOutputStream();
os.write(msg.getBytes());
os.close(); // close stream and send the message to the network
// wait max 15 seconds for response
sc.receive(15000);
// response received
if(sc.getStatusCode() == 200)
{
// handle 200 OK response
}
else
{
// handle other responses
}
sc.close();
} catch(Exception ex)
// handle Exceptions
}
}
The following code example shows how to open a SIP
server connection, receive one request and send a
response. The interfaces used in the simple server
connection example are SipConnectionNotifier and
SipServerConnection.
public receiveMessage()
{
SipConnectionNotifier scn = null;
SipServerConnection ssc = null;
String method = null;
try
{
// Open SIP server connection and listen to incoming requests
scn = (SipConnectionNotifier) Connector.open("sip:");
// block and wait for incoming request.
// SipServerConnection is established and returned
// when a new request is received.
ssc = scn.acceptAndOpen();
// what was the SIP method
method = ssc.getMethod();
if(method.equals("MESSAGE"))
{
// read the content of the MESSAGE
String contentType = ssc.getHeader("Content-Type");
if((contentType != null) && contentType.equals("text/plain"))
{
InputStream is = ssc.openContentInputStream();
int ch;
// read content
while ((ch = is.read()) != -1)
{
...
}
}
// initialize SIP 200 OK and send it back
ssc.initResponse(200);
ssc.send();
ssc.close();
} catch(Exception ex) {
// handle IOException, InterruptedIOException, SecurityException
// or SipException
}
}
SIP is an application-layer control protocol that can establish, modify, and terminate multimedia sessions. SIP can also invite participants to already existing sessions. SIP transparently supports name mapping and redirection services, which supports personal mobility - users can maintain a single externally visible identifier regardless of their network location (see RFC 3261 [1]). SIP can also be used to implement non-real-time services like Instant Messaging and Presence [2][3].
SIP supports five facets of establishing and terminating multimedia communications:
User location: Determination of the end system to be used for communication
User availability: Determination of the willingness of the called party to engage in communications
User capabilities: Determination of the media and media parameters to be used
Session setup: Establishment of session parameters at both called and calling party
Session management: Including transfer and termination of sessions, modifying session parameters, and invoking services
All compliant implementations MUST support at least the methods defined in RFC 2976, RFC 3261, RFC 3262, RFC 3265, RFC 3311, RFC 3428, RFC 3515, and RFC 3903. In particular, implementations MUST support:
Sending INFO, REGISTER, OPTIONS, INVITE,
CANCEL, BYE, ACK, PRACK, SUBSCRIBE,
NOTIFY, UPDATE, MESSAGE, REFER, and
PUBLISH requests on the
SipClientConnection interface
Receiving INFO, OPTIONS, INVITE, CANCEL,
BYE, ACK, PRACK, SUBSCRIBE, NOTIFY,
UPDATE, MESSAGE, and REFER requests on
the SipServerConnection interface
Implementations MUST also freely allow sending and receiving of any other non-dialogcreating requests, whether in-dialog or out-of-dialog, as described in RFC3261
The API contains dedicated methods for initiating some of these requests. Each request type is only required to be supported using the appropriate API method (as defined in the JSR 180 specification).
These RFCs have requirements for both the SIP protocol stack underneath the JSR 180 API as well as for the application level corresponding to the applications using the API. The SIP protocol stack MUST implement those requirements of the RFCs that are relevant for the stack, but following the application level requirements is the responsibility of the applications using the JSR 180 API. The responsibilities are approximately divided as follows:
Following are the requirements of the SIP protocol stack:
Support the defined method type
Support possible new header types defined in the RFC
Support the responses defined in the RFC
Manage basic transactions for new requests and responses
Create and manage the dialog, if the request creates a dialog
Following are the requirements of the application level:
Send appropriate requests and responses in the correct order
Fill required user headers
Fill required content with the required content type
Maintain and provide event states and content for the PUBLISH method, as defined in RFC 3903
Other application-specific requirements defined by the RFC that are not directly related to the SIP protocol
The implementations MUST support at least the Digest authentication, as defined in RFC 3261. Implementations that interface with a GSM or IMS/MMD identity module MUST also support Digest- AKA authentication.
Implementations MUST handle both 401 and 407 responses if the required authentication mechanism is supported.
This specification uses the following terms as they are defined in the table below:
Table 1. Notations
| 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. |
This section defines terms used in the specification.
The SIP API's client connection (class
SipClientConnection) is an interface to SIP client
transaction, which sends original request and
receives responses until final response. See also,
SIP Transaction and Server Connection.
The SIP API's server connection (class
SipServerConnection) is an interface to SIP server
transaction, which receives the original request and
sends response(s) until final response. Also see,
SIP Transaction and Client Connection.
A SIP transaction occurs between a client and a server and comprises all messages from the first request sent from the client to the server up to a final (non-1xx) response sent from the server to the client. If the request is INVITE and the final response is a non-2xx, the transaction also includes an ACK to the response. The ACK for a 2xx response to an INVITE request is a separate transaction.
The SIP API's class SipDialog keeps the information
about one SIP dialog. Using that interface the user
is able to send subsequent requests within that
dialog. A dialog is a peer-to-peer SIP relationship
between two UAs that persists for some time. A
dialog is established by SIP messages, such as a 2xx
response to an INVITE request. A dialog is
identified by a call identifier, local tag, and a
remote tag.
A logical entity that can act as both a user agent client and user agent server. Typically an application (e.g. MIDlet) will implement the User Agent functionality using the SIP API for J2ME. See also, UAC and UAS.
A user agent client is a logical entity that creates a new request, and then uses the client transaction state machinery to send it. The role of the UAC lasts only for the duration of that transaction. In other words, if a piece of software initiates a request, it acts as a UAC for the duration of that transaction. If it receives a request later, it assumes the role of a user agent server for the processing of that transaction.
A user agent server is a logical entity that generates a response to a SIP request. The response accepts, rejects, or redirects the request. This role lasts only for the duration of that transaction. In other words, if a piece of software responds to a request, it acts as a UAS for the duration of that transaction. If it generates a request later, it assumes the role of a user agent client for the processing of that transaction.
The method is the primary function that a request is meant to invoke on a server. The method is carried in the request message itself. Example methods are INVITE and BYE.
A response used by the server to indicate progress, but that does not terminate a SIP transaction. 1xx responses are provisional, other responses are considered final.
A response that terminates a SIP transaction, as opposed to a provisional response that does not. All 2xx, 3xx, 4xx, 5xx and 6xx responses are final.
[3] Session Initiation Protocol (SIP) Extension for Instant Messaging, RFC 3428. IETF. December 2002.
[4] Indicating User Agent Capabilities in the Session Initiation Protocol (SIP), RFC 3840. IETF. August 2004.
Appendix A. Deploying JSR 180 on MIDP 2.0 Platform
Appendix B. Code samples
Appendix C. Change history
|
||||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||