sipclientconnection.html

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

 <li>Initialize the original REGISTER request.
 <li>Set credentials <em>username</em>, <em>password</em> for some <em>realm</em>. 
 The credentials are saved by the system.
 <li>Application calls <tt>send()</tt>
 <li>The API implementation sends REGISTER request to the SIP server.
 <li>Application calls <tt>receive()</tt> to wait for the next response.
 <li>SIP server responds with the "401 Unauthorized". The response is not
 passed up to the application, since the API implementation either prompts for the 
 credentials (ask them with a dialog) or uses the previously saved credentials 
 set by the application.
 <li>The API implementation calculates the authorization headers and resends 
 the REGISTER.
 <li>Now the server accepts the REGISTER and responds with 200 OK. The response
 is passed to the application.
 <li>The <tt>receive()</tt> returns and the application calls <tt>getStatusCode()</tt>,
 which returns 200.
 <li>Application ends the connection by calling <tt>close()</tt>.
 </ol>
 <br><br>
 <img src="./jsr180-setcredentials1.gif">
 <p>
 <A NAME="CRED_EXAMPLE2">
 <h4>Example 2</h4>
 The following example shows how the credentials are set when the authentication 
 response is received by the application.
 <ol>
 <li>The application initializes the original REGISTER request.
 <li>Application calls <tt>send()</tt>
 <li>The API implementation sends REGISTER request to the SIP server.
 <li>Application calls <tt>receive()</tt> to wait for the next response.
 <li>SIP server responds with the "401 Unauthorized". The response is passed up 
 to the application, since the API implementation does not have the credentials
 or it is not able to collect them from the user.
 <li>The application calls <tt>getStatusCode()</tt>, which returns now 401.
 <li>The application gathers the credentials and calls <tt>setCredentials()</tt>.
 <li>The API implementation calculates the authorization headers and resends 
 the REGISTER.
 <li>Application calls <tt>receive()</tt> to wait for the next response.
 <li>The server accepts the REGISTER and responds with 200 OK. The response
 is passed to the application.
 <li>The <tt>receive()</tt> returns and the application calls <tt>getStatusCode()</tt>,
 which returns now 200.
 <li>Application ends the connection by calling <tt>close()</tt>.
 </ol>
 <p>
 <img src="./jsr180-setcredentials2.gif">
 <p>
 The following example code shows an outline how the application
 could send the REGISTER and handle the authentication responses as
 shown in the <A HREF="#CRED_EXAMPLE2">Example 2</A>.
 <pre>
 public void doRegister(String username, String password, String realm) {
	
  SipClientConnection scc = null;
  SipConnectionNotifier scn = null;
  String contact = null;
	
  try {
      // open listener in application specific port 5080
      scn = (SipConnectionNotifier) Connector.open("sip:5080");
	    
      // build the contact URI
      contact = new String("sip:user@"+scn.getLocalAddress()+
               ":"+scn.getLocalPort());
	    
      // open client connection to the SIP registrar 
      // in this case "host.com"	   
      scc = (SipClientConnection) Connector.open("sip:host.com");
      // initialize REGISTER with appropriate headers
      scc.initRequest("REGISTER", scn);
      scc.setHeader("From", "sip:[e-mail]");
      scc.setHeader("To", "sip:[e-mail]");
      scc.setHeader("Contact", contact);
	    
      scc.send();
	    
      boolean handled = false;
      int scode = 0;
	    
      while(!handled) {
          SipHeader sh;
          // wait max 30 secs for response
          scc.receive(30000);
          scode = scc.getStatusCode();
          switch(scode)
          {
              case 401:
                  sh = new SipHeader("WWW-Authenticate",
                     scc.getHeader("WWW-Authenticate"));
                  realm = sh.getParameter("realm");
                  // strip the quotation marks
                  realm = realm.substring(1, realm.length()-1);                
                  // here for example, prompt user for password 
                  // for this realm
                  // set credentials to initiate re-REGISTER
                  scc.setCredentials(username, password, realm);
                  break;
			
              case 407:
                  sh = new SipHeader("Proxy-Authenticate", 
                     scc.getHeader("Proxy-Authenticate"));
                  realm = sh.getParameter("realm");                
                  // strip the quotation marks
                  realm = realm.substring(1, realm.length()-1);                
                  // here for example, prompt user for password 
                  // for this realm
                  // set credentials to initiate re-REGISTER
                  scc.setCredentials(username, password, realm);
                  break;
			
              case 200:
                  // handle OK response
                  handled = true;
                  break;
              default:
                  // handle other responses
                  handled = true;
          }  
      }
      scc.close();
  } catch(Exception ex) {
      // handle Exceptions
  }
 }
 </pre>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>username</CODE> - username (for this protection domain)<DD><CODE>password</CODE> - user password (for this protection domain)<DD><CODE>realm</CODE> - defines the protection domain
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if the username, password or 
 realm is null
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the credentials can not
 be set in this state.</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;usernames,
                           java.lang.String[]&nbsp;passwords,
                           java.lang.String[]&nbsp;realms)
                    throws <A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></PRE>
<DL>
<DD>Sets multiple credential triplets for possible digest authentication.
 The username and password are specified for certain protection domain, 
 which is defined by the realm parameter. The parameters of this method
 are 3 parallel arrays where usernames[i] and passwords[i] are 
 interpreted as belonging to the protection domain in realms[i].<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. 
 The sequence is similar to what is shown in 
 <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. 
 The sequence is similar to <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>
 This method was added to the API in version 1.1.0. This is necessary in 
 the forking case when the received 401/407 error response may contain
 multiple authentication headers. For this case proper reauthentication 
 was not possible in the <em>Unauthorized</em> state using the other form
 of this method which allows setting only a single triplet at a time.
 <br>
 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.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>usernames</CODE> - array of user names. The array element <tt>username[i]</tt>
  is for the protection domain <tt>realm[i]</tt>.<DD><CODE>passwords</CODE> - array of user passwords. The array element 
 <tt>passwords[i]</tt> is for the protection domain <tt>realm[i]</tt>.<DD><CODE>realms</CODE> - array of protection domains
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if the usernames, passwords or 
 realms array is null or any of their elements is null
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the length of the parameter arrays are 
 not equal or the length of at least one of them is 0.
<DD><CODE><A HREF="../../../javax/microedition/sip/SipException.html" title="class in javax.microedition.sip">SipException</A></CODE> - INVALID_STATE if the credentials can not
 be set in this state.<DT><B>Since:</B></DT>
  <DD>1.1.0</DD>
</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>


<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" 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_bottom_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>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV CLASS&nbsp;
&nbsp;<A HREF="../../../javax/microedition/sip/SipClientConnectionListener.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>  &nbsp;
&nbsp;<A HREF="SipClientConnection.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<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:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

<HR>
<font size=-1>Copyright &copy; 2003-2007 Nokia Corporation. All Rights Reserved.<br/>   Java is a trademark of Sun Microsystems, Inc.
</BODY>
</HTML>