📄 sipconnection.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.4.2_10) on Wed Feb 28 12:31:09 CET 2007 -->
<TITLE>
SipConnection (JSR180 SIP API for J2ME)
</TITLE>
<META NAME="keywords" CONTENT="javax.microedition.sip.SipConnection interface">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
parent.document.title="SipConnection (JSR180 SIP API for J2ME)";
}
</SCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A><A HREF="#skip-navbar_top" title="Skip navigation links"></A><TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A><TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../javax/microedition/sip/SipClientConnectionListener.html" title="interface in javax.microedition.sip"><B>PREV CLASS</B></A>
<A HREF="../../../javax/microedition/sip/SipConnectionNotifier.html" title="interface in javax.microedition.sip"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../index.html" target="_top"><B>FRAMES</B></A>
<A HREF="SipConnection.html" target="_top"><B>NO FRAMES</B></A>
<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A><!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
javax.microedition.sip</FONT>
<BR>
Interface SipConnection</H2>
<DL>
<DT><B>All Superinterfaces:</B> <DD>javax.microedition.io.Connection</DD>
</DL>
<DL>
<DT><B>All Known Subinterfaces:</B> <DD><A HREF="../../../javax/microedition/sip/SipClientConnection.html" title="interface in javax.microedition.sip">SipClientConnection</A>, <A HREF="../../../javax/microedition/sip/SipServerConnection.html" title="interface in javax.microedition.sip">SipServerConnection</A></DD>
</DL>
<HR>
<DL>
<DT>public interface <B>SipConnection</B><DT>extends javax.microedition.io.Connection</DL>
<P>
<code>SipConnection</code> is the base interface for SIP connections. <code>SipConnection</code> holds the common properties and methods for subinterfaces <code>SipClientConnection</code> and <code>SipServerConnection</code>. <br> <h2>Integration to Generic Connection Framework</h2> <h3>Integration to <tt>javax.microedition.io.Connector</tt></h3> A new SIP connection is instantiated by a call to <code>Connector.open()</code>. An application SHOULD call <code>close()</code> when it is finished with the connection. It should be noticed that the <code>Connector.open()</code> returns a <em>client mode connection</em> (<code>SipClientConnection</code>) or <em>server mode connection</em> (<code>SipConnectionNotifier</code>) depending on the string (SIP URI) passed to the <code>Connector.open()</code>. The SIP URI is specified in RFC3261 [1] and here it takes general form of:<br> <pre> <b><code>{scheme}:[{target}][{params}]</code></b></pre> where: <p> <ul> <li><b><code>scheme</code></b> is SIP scheme supported by the system <code>sip</code> or <code>sips</code></li> <li><b><code>target</code></b> is user network address in form of <code>[{user_name}@]{target_host}[:{port}]</code> or <code>{telephone_number}</code>, see examples below. <li><b><code>params</code></b> stands for additional SIP URI parameters like <code>;transport=udp</code> </ul> The SIP URI may contain quote characters. The application can use either the quote character or it's escaped version <tt>(%22)</tt>, the API implementation must support both forms. </p> <h3>Opening new client connection <tt>(SipClientConnection)</tt></h3> If the target host is included a, <code>SipClientConnection</code> will be returned.<br> Examples: <p> <pre> sip:bob@biloxi.com sip:alice@10.128.0.8:5060 sips:alice@company.com:5060;transport=tcp sip:+358-555-1234567;postd=pp22@foo.com;user=phone </pre> </p> <A NAME="SERVERURI"</A> <h3>Opening new server connection <tt>(SipConnectionNotifier)</tt></h3> The server mode is detected by missing target host in the SIP URI. The server connection can be opened in two modes <em>shared</em> and <em>dedicated</em> (see also <A HREF="#SIPID">SIP Identity</A> chapter). It is not required that an implementation of this specification supports both server modes. There may be devices where dedicating separate ports for applications is not feasible. Conversely there may be devices where sharing the SIP listening port among applications is not feasible. Naturally it is required that either <em>shared</em> or <em>dedicated</em> server mode is supported. <p> This specification defines a special URI format for opening the SIP server mode connections: <pre> <b><code>{scheme}:[{port}][{params}]</code></b></pre> where: <p> <ul> <li><b><code>scheme</code></b> is SIP scheme supported by the system <code>sip</code> or <code>sips</code></li> <li><b><code>port</code></b> optional port number e.g. 5060 or asterisk <tt>*</tt>. Asterisk <tt>*</tt> is used to detect <em>shared</em> mode server connections (see below). <li><b><code>params</code></b> additional parameters e.g. like media feature tags. See below. </ul> </p> <p> <h4>Opening server connection in <em>shared</em> mode</h4> <ul> <li><b><code>sip:*;type="application/<app_subtype>"[;<other_params>]</code></b> <br>Returns <code>SipConnectionNotifier</code> in <em>shared</em> mode. The <code>SipConnectionNotifier</code> is sharing the user's SIP identity with other SIP applications and also sharing the system listening port. Because the listening port is shared the parameter <tt>'type'</tt> identifying the application is mandatory in this mode. Furthermore, the SIP registration is done by the system. The application does not register itself separately.<br><br> The <tt>IOException</tt> is thrown if the application type is already reserved or the shared mode can not be opened for other reason. <br><br>URI parameters are:<br> <ul> <li><b><code>type</code></b> application identifier as MIME type feature tag, where <b><code><app_subtype></code></b> is an unique application type/name. Example value: <tt>type="application/vnd.company.x-game"</tt><br> <li><b><code><other_params></code></b> Other possible media feature tags or parameters (see RFC3840 [4]) </ul> <br> The incoming requests targeted to the application tagged with the parameter <tt>'type'</tt> are routed to this <code>SipConnectionNotifier</code>. </ul> <h4>Opening server connection in <em>dedicated</em> mode</h4> <ul> <li><b><code>sip:[nnnn][;<params>]</code></b> <br>Returns <code>SipConnectionNotifier</code> in <em>dedicated</em> mode, where a dedicated listening port is opened for the application. The <code>SipConnectionNotifier</code> is listening to incoming SIP requests on port number <code>nnnn</code>. If the port number is omitted an arbitrary number is allocated by the system. Application identifier <tt>'type'</tt> and other media feature parameters are optional. Since the user's SIP identity is not shared the application has to do the SIP registration by itself.<br><br> The <tt>IOException</tt> is thrown if the port number is already in use or it cannot be opened for other reason. <br><br>URI parameters are:<br> <ul> <li><b><code><params></code></b> Optional media feature tag parameters e.g. <tt>'type'</tt> and others (see RFC3840 [4]). </ul> <br> If the application identifier <tt>'type'</tt> is specified the requests targeted to this application are routed to this <code>SipConnectionNotifier</code>. </ul> </p> Examples of opening a SIP server connection: <p> <pre> <em>// Shared mode, the application MIME type identifier is // application/vnd.company.x-game</em> SipConnectionNotifier scn = (SipConnectionNotifier) Connector.open("sip:*;type=\"application/vnd.company.x-game\""); <em>// Dedicated mode, port number 5060 opened for the application</em> SipConnectionNotifier scn = (SipConnectionNotifier) Connector.open("sip:5060"); <em>// Dedicated mode, port number 5080, using secure transport // the application identifier is "application/messenger"</em> SipConnectionNotifier scn = (SipConnectionNotifier) Connector.open("sips:5080;type=\"application/messenger\""); <em>// Dedicated mode, dedicated port number selected by the system</em> SipConnectionNotifier scn = (SipConnectionNotifier) Connector.open("sip:"); </pre> </p> <h4>Connector.open(String name, String mode)</h4> The optional second parameter 'mode' in <code>Connector.open()</code> specifies the access mode. This is ignored in SIP API. This is because both connection modes: <em>client mode connection</em> and <em>server mode connection</em> can send and receive messages. <h4>Connector.open(String name, String mode, boolean timeouts)</h4> The optional third parameter is a boolean flag that indicates if the calling code can handle timeout exceptions. That parameter is also ignored by the SIP API. <h4>Convenience methods for opening streams</h4> The <code>Connector</code> convenience methods to gain access to a specific input or output stream directly are not supported by the SIP API. The implementations MUST throw <code>IOException</code> if these methods are called with SIP URIs. <A NAME=CONNECTOR_EXCEPTIONS</A> <h4>The Exceptions when calling Connector.open()</h4> <dl> <dt><code>IllegalArgumentException</code> <dd>- If a parameter is invalid. <dt><code>ConnectionNotFoundException</code> <dd>- If the requested connection cannot be created, or the protocol type does not exist. <dt><code>IOException</code> <dd>- If some other kind of I/O error occurs. For example the port number for <em>server mode connection</em> is already reserved. <dt><code>SecurityException</code> <dd>- May be thrown if access to the protocol handler is prohibited. <dt><code>SipException</code> <dd>- TRANSACTION_UNAVAILABLE if the system can not open new SIP transactions. TRANSPORT_NOT_SUPPORTED if the requested transport is not supported. See above <tt>transport</tt> URI parameter. </dl> <h2>Supported Transport Protocols</h2> All compliant implementations MUST support sending and receiving SIP messages, at least on UDP and TCP transport protocols, as defined in RFC 3261 (section 18). The default transport protocol MUST be UDP. Whenever requested, the preferred transport protocol MUST be indicated with the <tt>;transport={transport}</tt> parameter within the URI indicated in the <tt>Connector.open()</tt> method, either for client or server connections. The choice of transport protocols on which an UAS MUST listen are specified by RFC 3261 (18.2.1):<br> <tt>For any port and interface that a server listens on for UDP, it MUST listen on that same port and interface for TCP. This is because a message may need to be sent using TCP, rather than UDP, if it is too large. As a result, the converse is not true. A server need not listen for UDP on a particular address and port just because it is listening on that same address and port for TCP.</tt> <p> This means that for a <tt>SipConnectionNotifier</tt> listening on UDP transport protocol is not mandatory if all requests have been sent on top of TCP, that is if all the Contact headers sent within a registration or within dialogs indicate <tt>transport=tcp</tt>. <h2><A NAME="SIPID">SIP Identity</A></h2> SIP identity is a logical identity (address-of-record, AOR), a type of Uniform Resource Identifier (URI) called a SIP URI. SIP identity is frequently thought of as the "public address" of the user. (see RFC 3261 [1], 6 Definitions, p.20). SIP terminal is typically configured for one user at the time (in SIP settings). The AOR is associated (inside the terminal) with one listening port e.g. 5060 (udp/tcp). So, all incoming SIP requests to that particular address-of-record are received through that port. <br><br> Now it is still possible to have several applications that want to share the same SIP identity, without specifying own listening ports (audio/video, instant message/presence and e.g. game applications). It is not feasible, or even possible, for every application to reserve own listening port and register that to the SIP registrar. This is particularly not feasible in resource-constrained terminals/networks.<br> On the other hand, some applications can still use their own SIP identity (for that particular service), which does not share the system SIP properties. <br><br> In SIP terms: if the request is targeted to specific application (and it is sent outside an existing dialog) it is not possible to always route incoming SIP requests using: port number, SDP media type or SIP method name (INVITE, MESSAGE, SUBSCRIBE, ...). <br><br> The issue falls to the decisions on how the initial SIP requests are routed (inside the terminal) to the User Agents (applications). This kind of functionality is specified in <A HREF="http://www.ietf.org/html.charters/sip-charter.html"> SIP Working Group</A> as callee capabilities RFC3840 [4] and caller preferences RFC3841 [5]. The JSR180 specification utilizes similar functinality und uses the media feature tag <tt>'type'</tt> for specifying the application identifier, which is used to route the incoming requests for correct applications. <br><br> Applications can use the MIME type feature tag first to register locally to the SIP system and second to indicate that in a caller preference header <tt>Accept-Contact</tt>. Each application is mapped to a certain MIME type. JSR180 SIP API provides the way to utilize this functionality as specified below. <p> To allow the Java SIP API to share the system SIP identity or use application's own identity, the following rules are defined when the SIP server connection is opened with <tt>Connector.open()</tt>: <br><br> <table BORDER COLS=4 WIDTH="100%" > <tr> <td><tt> </tt></td> <td><b><u>Connector SIP URI</u></b></td> <td><b><u>SIP Identity</u></b></td> <td><b><u>Request routing</u></b></td> </tr> <tr> <td><b>1)</b></td> <td><tt>sip:*;type=<br>"application/subtype"</tt></td>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -