sipconnection.html

sipapi 说明文档.用于JAVA的SIP开发及应用.

<DD>Sends the SIP message. Send must also close the <tt>OutputStream</tt> if it
 was opened.
 Calling <tt>send()</tt> is asynchronous. Any kind of immediate failure will
 throw <tt>IOException</tt> or <tt>SipException</tt>. Errors during the 
 send operation can be handled with the <tt>SipErrorListener</tt> 
 mechanism.
 <br><br>
 With <tt>SipServerConnection</tt> it is possible to resend 2xx responses
 in <em>Completed</em> state, by calling directly <tt>send()</tt>.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>

<DT><B>Throws:</B>
<DD><CODE>java.io.IOException</CODE> - if the message could not be sent
          or because of network failure. When IOException is thrown the
          connection moves to the Terminated state.
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the message
         can not be sent in this state. INVALID_MESSAGE if there was an 
         error in the message format.<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/sip/SipErrorListener.html" title="interface in javax.microedition.sip"><CODE>SipErrorListener</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="setHeader(java.lang.String, java.lang.String)"><!-- --></A><H3>
setHeader</H3>
<PRE>
public void <B>setHeader</B>(java.lang.String&nbsp;name,
                      java.lang.String&nbsp;value)
               throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Sets header value in SIP message. If the header does not exist it will 
 be added to the message, otherwise the existing header is overwritten.
 If multiple header field values exist the topmost is overwritten. 
 The implementations MAY restrict the access to some headers according 
 to RFC 3261 [1], see also 
 <A HREF="SipConnection.html#HEADERACCESS">"Restricted access to headers"</A>.
 <p>
 The implementations are free to store the multiple header field-values 
 either as separate rows or as comma-separated list (if the header type 
 follows the grammar defined in [RFC3261] section 7.3). 
 <p>
 The <tt>value</tt> argument of the method may contain a list of 
 comma-separated header values. Note that this feature should not be used 
 for headers (like the Authorization header) which use comma as parameter
 separator instead of semicolon. If there exist headers of the same type 
 then only the first (topmost) one will be overwritten, indifferently of 
 the number of header values in the comma-separated list. See exampe 
 3. below.
 <p>
 The method works atomically, that is if the <tt>value</tt> argument of 
 the method is a list of comma-separated values then the method should 
 either set all of them or none of them. That is if an exception is 
 thrown from the method then no headers are changed, even if the error 
 occurred when setting  the second, third etc header value.
 <p>
 <b>Example1:</b> Replacing single header field row. The message 
 already contains following headers: <br>
 <pre>
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 setHeader("Route", "&lt;sip:[e-mail]&gt;");
 
 the result will be
 
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 </pre>
 <p>
 <b>Example2:</b> Setting multiple header field rows as a comma-separated 
 list. The message already contains one header: <br>
 <pre>
 Route: &lt;sip:[e-mail]&gt;
 
 setHeader("Route", "&lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;");
 
 the result will be either
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 
 or
 
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 </pre>
 <p>
 <b>Example3:</b> Setting multiple header field rows as a comma-separated 
 list. The message already contains two headers: <br>
 <pre>
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 setHeader("Route", "&lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;");
 
 the result will be either
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 
 or
 
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 The result would be the same if the original message contained the 
 headers in a concatenated list form:
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 </pre>
 <p>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the header, either in full or compact form see [1] p.32<DD><CODE>value</CODE> - the header value. Empty string or null means a 
 header with no value.
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if name is null
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the header or value 
 is invalid.
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if header 
 can not be set in this state. INVALID_OPERATION if the system does 
 not allow to set this header.</DL>
</DD>
</DL>
<HR>

<A NAME="addHeader(java.lang.String, java.lang.String)"><!-- --></A><H3>
addHeader</H3>
<PRE>
public void <B>addHeader</B>(java.lang.String&nbsp;name,
                      java.lang.String&nbsp;value)
               throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Adds a header to the SIP message. 
 If multiple header field values exist 
 the header value is added topmost of this type of headers.
 The implementations MAY restrict the access to some headers 
 according to RFC 3261 [1], see also 
 <A HREF="SipConnection.html#HEADERACCESS">"Restricted access to headers"</A>.
 <p>
 Some SIP headers can occur only once in a message, for these it is 
 recommended that <tt>setHeader</tt> is used instead of <tt>addHeader</tt>.
 Implementations of this specification are not mandated to check that 
 the multiplicity of headers conform to the relevant RFCs when the message
 is composed. <p>
 The header value string may contain a single value or multiple values 
 as a comma-separated list (that is, if it follows the grammar defined 
 in [RFC3261] section 7.3). Note that this feature should not be used 
 for headers (like the Authorization header) which use comma as parameter
 separator instead of semicolon. The implementations are free to store the 
 multiple header field rows either as comma separated list or in separate 
 rows.<p>
 The method works atomically, that is if the <tt>value</tt> argument of 
 this method is a list of comma-separated values then the method should 
 either add all of them or none of them. That is if an exception is 
 thrown from the method then no headers are changed, even if the error 
 occurred when adding  the second, third etc header value.
 <p>
 <b>Example1:</b> Adding single header field row. The message already 
 contains header
 <pre>
 Route: &lt;sip:[e-mail]&gt;.
 
 addHeader("Route", " &lt;sip:[e-mail]&gt;");
 
 the result will be
 
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 or
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 </pre>
 <p>
 <b>Example2:</b> Adding multiple header field rows as a comma-separated 
 list. The message already contains header 
 <pre>
 Route: &lt;sip:[e-mail]&gt;.
 
 addHeader("Route", "&lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;");
 
 the result will be either
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 or
 
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 or
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 </pre>
 <p>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the header, either in full or compact form see [1] p.32<DD><CODE>value</CODE> - the header value. Empty string or null means a header with
 no value.
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if name is null
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the header or value 
 is invalid.
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if header can 
 not be added in this state. INVALID_OPERATION if the system does not 
 allow to add this header.</DL>
</DD>
</DL>
<HR>

<A NAME="removeHeader(java.lang.String)"><!-- --></A><H3>
removeHeader</H3>
<PRE>
public void <B>removeHeader</B>(java.lang.String&nbsp;name)
                  throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Removes header from the message. If multiple header field values exist
 the topmost is removed. If the named header is not found
 this method does nothing. The implementations MAY restrict the access to 
 some headers according to RFC 3261 [1], see also 
 <A HREF="SipConnection.html#HEADERACCESS">"Restricted access to headers"</A>.
 <p>
 The method only removes one header value even if the header values are 
 stored in a comma-separated list.
 <p>
 <b>Example1:</b> Removing header from a message that contains two Route 
 headers in separate header field rows.
 <p>
 <pre>
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 removeHeader("Route");
 
 the result is:
 
 Route: &lt;sip:[e-mail]&gt;
 </pre>
 <p>
 <b>Example2:</b> Removing header from a message that contains three 
 Route headers in a comma-separated header field value.
 <p>
 <pre>
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 
 removeHeader("Route");
 
 the result is:
 
 Route: &lt;sip:[e-mail]&gt;, &lt;sip:[e-mail]&gt;
 </pre>
 <p>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the header to be removed, either in full or compact form see [1] p.32
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if name is null
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if header 
 can not be removed in this state. INVALID_OPERATION if the system does 
 not allow to remove this header.</DL>
</DD>
</DL>
<HR>

<A NAME="getHeaders(java.lang.String)"><!-- --></A><H3>
getHeaders</H3>
<PRE>
public java.lang.String[] <B>getHeaders</B>(java.lang.String&nbsp;name)</PRE>
<DL>
<DD>Gets the header field value(s) of specified header type. The method 
 returns the header field-values separated in an array regardless of how 
 they are stored in the message. The implementations MAY restrict the 
 access to some headers according to RFC 3261 [1], see also 
 <A HREF="SipConnection.html#HEADERACCESS">"Restricted access to headers"</A>.
 <p>
 <b>Example1:</b> Get Route headers from a message that contains two 
 Route headers in separate header field rows.
 <p>
 <pre>
 Route: &lt;sip:[e-mail]&gt;
 Route: &lt;sip:[e-mail]&gt;
 
 getHeaders("Route");
 
 the result is a String array:
 
 {&quot;&lt;sip:[e-mail]&gt;&quot;, &quot;&lt;sip:[e-mail]&gt;&quot;}
 
 </pre>
 <p>
 <b>Example2:</b> Get Route headers from a message that contains three 
 Route headers in a comma-separated header field value.
 <p>
 <pre>
 Route: &lt;sip:[e-mail]&gt;,&lt;sip:[e-mail]&gt;,&lt;sip:[e-mail]&gt;
 
 getHeaders(&quot;Route&quot;);
 
 the result is a String array:
 
 {&quot;&lt;sip:[e-mail]&gt;&quot;, &quot;&lt;sip:[e-mail]&gt;&quot;, 
  &quot;&lt;sip:[e-mail]&gt;&quot;}
 </pre>
 <p>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the header type, either in full or compact form 
 see [1] p.32
<DT><B>Returns:</B><DD>array of header field values (topmost first), or <tt>null</tt> 
 if the current message does not have such a header or the header is
 for other reason not available (e.g. message is not initialized, the
 connection is closed or the 
 implementation does not allow this header to be read). The returned 
 array may contain empty strings.
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if name is null</DL>