sipclientconnection.html

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

             throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Convenience method to initialize <tt>SipClientConnection</tt> 
 with SIP request method ACK. ACK can be applied only to INVITE
 request. The method is available when a successful final response (2xx) 
 has been received.
 The header fields of the ACK are constructed in the same way as for any request sent 
 within a dialog with the exception of the CSeq and the header fields related to authentication
 (RFC 3261 [1], p.82).
 The Request-URI and headers will be initialized automatically.
 After this the <tt>SipClientConnection</tt> is in <em>Initialized</em> state.
 <p>At least Request-URI and following headers will be set by the method (RFC 3261 [1] 12.2.1.1 Generating the Request p.73 and 8.1.1 Generating the Request p.35).<br>
 See also RFC 3261 [1] 13.2.2.4 2xx Responses (p.82)<br>
 <pre>
    Request-URI  // system uses the remote target and route set to
                    build the Request-URI
    To           // remote URI from the dialog state + remote tag 
                    of the dialog ID
    From         // local URI from the dialog state + local tag of 
                    the dialog ID
    CSeq         // the sequence number of the CSeq header field 
                    MUST be the same as the INVITE being 
                    acknowledged, but the CSeq method MUST be ACK.
    Call-ID      // Call-ID of the dialog
    Via          // Via header field indicates the transport used 
                    for the transaction and identifies the location
                    where the response is to be sent
    Route        // system uses the remote target and route set 
                    (if present) to build the Route header
    Contact      // SHOULD include a Contact header field in any 
                    target refresh requests within a dialog, and 
                    unless there is a need to change it, the URI 
                    SHOULD be the same as used in previous 
                    requests within the dialog
    Max-Forwards // header field serves to limit the number of 
                    hops a request can transit on the way to its 
                    destination.
 </pre>
 <p>
 These headers will be set on behalf of the user by the implementation 
 the latest when sending the request. It implies that the header values
 may not be available for reading right after the <tt>initAck</tt>
 method returns. The user may also set (overwrite) these headers, in this
 case the values set by the user take precedence over the values set by
 the implementation.
 <p>
 The following rules also apply:<br>
 For error responses (3xx-6xx) the ACK is sent automatically by the 
 system in transaction level. If the user initializes an ACK which has 
 already been sent an Exception will be thrown.<p>
 The <tt>SipClientConnection</tt> remains in <tt>Completed</tt> state
 if sending ACK fails and there is forking case. It allows trying to send 
 ACK again, wait for more 2xx responses or close the connection. If the 
 application (after investigating the error code) finds out that the 
 error is irrevocable, it can close the connection.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>

<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the request can not be set, because of wrong state, INVALID_OPERATION if the ACK request can not be initialized for other reason (already sent or the original request is non-INVITE).</DL>
</DD>
</DL>
<HR>

<A NAME="initCancel()"><!-- --></A><H3>
initCancel</H3>
<PRE>
public <A HREF="../../../javax/microedition/sip/SipClientConnection.html" title="interface in javax.microedition.sip">SipClientConnection</A> <B>initCancel</B>()
                               throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Convenience method to initialize <tt>SipClientConnection</tt> 
 with SIP request method CANCEL. The method is available when a provisional response has been received. The CANCEL request starts a new transaction,
 that is why the method returns a new <tt>SipClientConnection</tt>.
 The CANCEL request will be built according to the original INVITE request 
 within this connection. The RequestURI and headers will be initialized 
 automatically. After this the <tt>SipClientConnection</tt> is in 
 <em>Initialized</em> state. The message is ready to be sent.
 <p>The following information will be set by the method:<br>
 <pre>
    Request-URI  // copy from original request
    To           // copy from original request
    From         // copy from original request
    CSeq         // same value for the sequence number as was 
                    present in the original request, but the 
                    method parameter MUST be equal to "CANCEL"
    Call-ID      // copy from original request
    Via          // single value equal to the top Via header field 
                    of the request being cancelled
    Route        // If the request being cancelled contains a Route 
                    header field, the CANCEL request MUST include 
                    that Route header field's values
    Max-Forwards // header field serves to limit the number of hops 
                    a request can transit on the way to its 
                    destination. 
 </pre>
 <p>
 These headers will be set on behalf of the user by the implementation 
 the latest when sending the request. It implies that the header values
 may not be available for reading right after the <tt>initCancel</tt>
 method returns. The user may also set (overwrite) these headers, in this
 case the values set by the user take precedence over the values set by
 the implementation.
 Reference RFC 3261 [1] p.53-54
 <p>
 <b>Note:</b> CANCEL request SHOULD NOT be sent to cancel a request other than INVITE.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>

<DT><B>Returns:</B><DD>A new <tt>SipClientConnection</tt> with preinitialized CANCEL request.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the request 
 can not be set, because of wrong state (in <tt>SipClientConnection</tt>) 
 or the system has already got a final response (even if not read with 
 <tt>receive()</tt> method). INVALID_OPERATION if CANCEL method can not 
 be applied to the current request method.</DL>
</DD>
</DL>
<HR>

<A NAME="receive(long)"><!-- --></A><H3>
receive</H3>
<PRE>
public boolean <B>receive</B>(long&nbsp;timeout)
                throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A>,
                       java.io.IOException</PRE>
<DL>
<DD>Receives SIP response message. The receive method will update the 
 <tt>SipClientConnection</tt> with the last new received response.
 The implementation places the responses in a FIFO queue and when this 
 method is called it fetches the 
 least recently arrived response which has not been fetched already.<br> 
 If no message is received the method will block until something 
 is received or the specified amount of time has elapsed.
 <br><br>
 The <tt>SipClientConnection</tt> is always associated with the latest 
 response received succesfully by calling the <tt>receive()</tt> method.
 <p>
 100 (Trying) responses for Non-INVITE transactions are not passed 
 up to the application level in <tt>receive()</tt> as these responses are
 not explicitly required/expected by RFC 3261 and they are only useful 
 information for the transaction layer which takes care of request resends.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>timeout</CODE> - the maximum time to wait in milliseconds. 0 = do not 
 wait, just poll
<DT><B>Returns:</B><DD>Returns <tt>true</tt> if response was received. Returns 
 <tt>false</tt> if the given timeout elapsed and no response was received.
<DT><B>Throws:</B>
<DD><CODE>java.io.IOException</CODE> - if the message could not be received
          or because of network failure. When an IOException is thrown
          the connection moves to Terminated state. This exception is 
          thrown regardless of there is a <tt>SipErrorListener</tt> set
          or not for the connection.
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the receive can not 
 be called because of wrong state.<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/sip/SipConnection.html#send()"><CODE>SipConnection.send()</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="setListener(javax.microedition.sip.SipClientConnectionListener)"><!-- --></A><H3>
setListener</H3>
<PRE>
public void <B>setListener</B>(<A HREF="../../../javax/microedition/sip/SipClientConnectionListener.html" title="interface in javax.microedition.sip">SipClientConnectionListener</A>&nbsp;sccl)
                 throws java.io.IOException</PRE>
<DL>
<DD>Sets the listener for incoming responses. If a listener is already set 
 it will be overwritten. Setting listener to <tt>null</tt> will remove 
 the current listener.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>sccl</CODE> - reference to the listener object. Value <tt>null</tt> will 
 remove the existing listener.
<DT><B>Throws:</B>
<DD><CODE>java.io.IOException</CODE> - if the connection is closed</DL>
</DD>
</DL>
<HR>

<A NAME="enableRefresh(javax.microedition.sip.SipRefreshListener)"><!-- --></A><H3>
enableRefresh</H3>
<PRE>
public int <B>enableRefresh</B>(<A HREF="../../../javax/microedition/sip/SipRefreshListener.html" title="interface in javax.microedition.sip">SipRefreshListener</A>&nbsp;srl)
                  throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Enables the refresh for the request to be sent. The method
 return a refresh ID, which can be used to update or stop
 the refresh. Passing <tt>null</tt> as listener does not clear a 
 previously set listener and does not stop a refresh. Refreshing should 
 be stopped by calling <tt>stop</tt>. Calling <tt>enableRefresh</tt> for 
 the second time with a non-null value does not overwrite the previously 
 set listener. In this case the previously set listener remains valid, 
 and the method throws <tt>SipException.INVALID_STATE</tt>.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>srl</CODE> - callback interface for refresh events, if this is <tt>null</tt>
 the method returns 0 and refresh is not enabled.
<DT><B>Returns:</B><DD>refresh ID. If the request is not refreshable returns 0.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the 
 refresh can not be enabled in this state.<DT><B>See Also:</B><DD><A HREF="../../../javax/microedition/sip/SipRefreshHelper.html" title="class in javax.microedition.sip"><CODE>SipRefreshHelper</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="setCredentials(java.lang.String, java.lang.String, java.lang.String)"><!-- --></A><H3>
setCredentials</H3>
<PRE>
public void <B>setCredentials</B>(java.lang.String&nbsp;username,
                           java.lang.String&nbsp;password,
                           java.lang.String&nbsp;realm)
                    throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Sets credentials for possible digest authentication.
 The username and password are specified for certain protection domain, 
 which is defined by the realm parameter.<br><br>
 The credentials can be set:
 <ul>
 <li>before sending the original request in <em>Initialized</em> state. 
 The API implementation caches the credentials for later use. 
 See <A HREF="#CRED_EXAMPLE1">Example 1</A>
 <li>when 401 (Unauthorized) or 407 (Proxy Authentication Required) 
 response is received in the <em>Unauthorized</em> state. The API 
 implementation uses the given credentials to re-originate the request 
 with proper authorization header. After that the
 <tt>SipClientConnection</tt> will be in <em>Proceeding</em> state. 
 See <A HREF="#CRED_EXAMPLE2">Example 2</A>
 </ul>
 Implementations of this specification must support setting the 
 credentials in both states described above.<p>
 See also <A HREF="#CLIENT_STATE_DIAGRAM"><tt>SipClientConnection</tt> 
 state diagram</A>.<p>
 See <A HREF="../../../overview-summary.html#AUTH_REQ">Authentication 
 requirements</A> for the authentication methods supported.<br>
 The application can set multiple credential triplets
 (username, password, realm) for one <tt>SipClientConnection</tt> in the 
 <em>Initialized</em> state, however it can not set mulitple triplets in 
 the <em>Unauthorized</em> state using this method, as in this case the 
 request would be automatically resent after the first execution of this
 method. For setting multiple credentials in the <em>Unauthorized</em> 
 state the application should use the SetCredentials(String[], String[],
 String[]) method.  
 <p>
 When setting the credentials in the <em>Unautorized</em> state the 
 request is automatically resent which implies that the application is 
 unable to further modify the request headers before sending. Calling
 <tt>getHeader</tt> immediately after <tt>setCredentials</tt> returns the 
 value of the authentication headers as they were set by the user before 
 sending the 
 original request. The updated value of the authentication headers set by
 the API implementation are not available at this point and can be
 examined after a response is received to the reoriginated request.  
 <br>
 <A NAME="CRED_EXAMPLE1">
 <h4>Example 1</h4>
 The following simplified example shows how the credentials are set before sending the 
 original request.
 <ol>