Merge "Fix links in SIP API javadoc." into gingerbread

voip/java/android/net/sip/ISipSession.aidl

@@ -20,8 +20,8 @@ import android.net.sip.ISipSessionListener;
 import android.net.sip.SipProfile;
 
 /**
- * A SIP session that is associated with a SIP dialog or a transaction
+ * A SIP session that is associated with a SIP dialog or a transaction that is
- * (e.g., registration) not within a dialog.
+ * not within a dialog.
  * @hide
  */
 interface ISipSession {

voip/java/android/net/sip/SipAudioCall.java

@@ -96,8 +96,8 @@ public interface SipAudioCall {
     }
 
     /**
-     * The adapter class for {@link SipAudioCall#Listener}. The default
+     * The adapter class for {@link Listener}. The default implementation of
-     * implementation of all callback methods is no-op.
+     * all callback methods is no-op.
      */
     public class Adapter implements Listener {
         protected void onChanged(SipAudioCall call) {
@@ -134,7 +134,7 @@ public interface SipAudioCall {
 
     /**
      * Sets the listener to listen to the audio call events. The method calls
-     * {@link #setListener(Listener, false)}.
+     * {@code setListener(listener, false)}.
      *
      * @param listener to listen to the audio call events of this object
      * @see #setListener(Listener, boolean)
@@ -178,8 +178,8 @@ public interface SipAudioCall {
     void endCall() throws SipException;
 
     /**
-     * Puts a call on hold.  When succeeds,
+     * Puts a call on hold.  When succeeds, {@link Listener#onCallHeld} is
-     * {@link #Listener#onCallHeld(SipAudioCall)} is called.
+     * called.
      */
     void holdCall() throws SipException;
 
@@ -188,7 +188,7 @@ public interface SipAudioCall {
 
     /**
      * Continues a call that's on hold. When succeeds,
-     * {@link #Listener#onCallEstablished(SipAudioCall)} is called.
+     * {@link Listener#onCallEstablished} is called.
      */
     void continueCall() throws SipException;
 

voip/java/android/net/sip/SipErrorCode.java

@@ -18,10 +18,10 @@ package android.net.sip;
 
 /**
  * Defines error code returned in
- * {@link SipRegistrationListener#onRegistrationFailed(String, String, String)},
+ * {@link SipRegistrationListener#onRegistrationFailed},
- * {@link ISipSessionListener#onError(ISipSession, String, String)},
+ * {@link ISipSessionListener#onError},
- * {@link ISipSessionListener#onCallChangeFailed(ISipSession, String, String)} and
+ * {@link ISipSessionListener#onCallChangeFailed} and
- * {@link ISipSessionListener#onRegistrationFailed(ISipSession, String, String)}.
+ * {@link ISipSessionListener#onRegistrationFailed}.
  * @hide
  */
 public enum SipErrorCode {

voip/java/android/net/sip/SipException.java

@@ -17,6 +17,7 @@
 package android.net.sip;
 
 /**
+ * General SIP-related exception class.
  * @hide
  */
 public class SipException extends Exception {

voip/java/android/net/sip/SipManager.java

@@ -28,25 +28,22 @@ import java.text.ParseException;
 
 /**
  * The class provides API for various SIP related tasks. Specifically, the API
- * allows the application to:
+ * allows an application to:
  * <ul>
  * <li>register a {@link SipProfile} to have the background SIP service listen
  *      to incoming calls and broadcast them with registered command string. See
  *      {@link #open(SipProfile, String, SipRegistrationListener)},
- *      {@link #open(SipProfile)}, {@link #close(String)},
+ *      {@link #open(SipProfile)}, {@link #close}, {@link #isOpened} and
- *      {@link #isOpened(String)} and {@link isRegistered(String)}. It also
+ *      {@link #isRegistered}. It also facilitates handling of the incoming call
- *      facilitates handling of the incoming call broadcast intent. See
+ *      broadcast intent. See
- *      {@link #isIncomingCallIntent(Intent)}, {@link #getCallId(Intent)},
+ *      {@link #isIncomingCallIntent}, {@link #getCallId},
- *      {@link #getOfferSessionDescription(Intent)} and
+ *      {@link #getOfferSessionDescription} and {@link #takeAudioCall}.</li>
- *      {@link #takeAudioCall(Context, Intent, SipAudioCall.Listener)}.</li>
  * <li>make/take SIP-based audio calls. See
- *      {@link #makeAudioCall(Context, SipProfile, SipProfile, SipAudioCall.Listener)}
+ *      {@link #makeAudioCall} and {@link #takeAudioCall}.</li>
- *      and {@link #takeAudioCall(Context, Intent, SipAudioCall.Listener}.</li>
  * <li>register/unregister with a SIP service provider. See
- *      {@link #register(SipProfile, int, ISipSessionListener)} and
+ *      {@link #register} and {@link #unregister}.</li>
- *      {@link #unregister(SipProfile, ISipSessionListener)}.</li>
  * <li>process SIP events directly with a {@link ISipSession} created by
- *      {@link createSipSession(SipProfile, ISipSessionListener)}.</li>
+ *      {@link #createSipSession}.</li>
  * </ul>
  * @hide
  */
@@ -113,8 +110,7 @@ public class SipManager {
     /**
      * Opens the profile for making calls and/or receiving calls. Subsequent
      * SIP calls can be made through the default phone UI. The caller may also
-     * make subsequent calls through
+     * make subsequent calls through {@link #makeAudioCall}.
-     * {@link #makeAudioCall(Context, String, String, SipAudioCall.Listener)}.
      * If the receiving-call option is enabled in the profile, the SIP service
      * will register the profile to the corresponding server periodically in
      * order to receive calls from the server.
@@ -134,8 +130,7 @@ public class SipManager {
     /**
      * Opens the profile for making calls and/or receiving calls. Subsequent
      * SIP calls can be made through the default phone UI. The caller may also
-     * make subsequent calls through
+     * make subsequent calls through {@link #makeAudioCall}.
-     * {@link #makeAudioCall(Context, String, String, SipAudioCall.Listener)}.
      * If the receiving-call option is enabled in the profile, the SIP service
      * will register the profile to the corresponding server periodically in
      * order to receive calls from the server.
@@ -160,9 +155,7 @@ public class SipManager {
 
     /**
      * Sets the listener to listen to registration events. No effect if the
-     * profile has not been opened to receive calls
+     * profile has not been opened to receive calls (see {@link #open}).
-     * (see {@link #open(SipProfile, String, SipRegistrationListener)} and
-     * {@link #open(SipProfile)}).
      *
      * @param localProfileUri the URI of the profile
      * @param listener to listen to registration events; can be null
@@ -283,7 +276,7 @@ public class SipManager {
     /**
      * Creates a {@link SipAudioCall} to take an incoming call. Before the call
      * is returned, the listener will receive a
-     * {@link SipAudioCall#Listener.onRinging(SipAudioCall, SipProfile)}
+     * {@link SipAudioCall.Listener#onRinging}
      * callback.
      *
      * @param context context to create a {@link SipAudioCall} object
@@ -377,12 +370,11 @@ public class SipManager {
 
     /**
      * Registers the profile to the corresponding server for receiving calls.
-     * {@link #open(SipProfile, String, SipRegistrationListener)} is still
+     * {@link #open} is still needed to be called at least once in order for
-     * needed to be called at least once in order for the SIP service to
+     * the SIP service to broadcast an intent when an incoming call is received.
-     * broadcast an intent when an incoming call is received.
      *
      * @param localProfile the SIP profile to register with
-     * @param expiryTime registration expiration time (in second)
+     * @param expiryTime registration expiration time (in seconds)
      * @param listener to listen to the registration events
      * @throws SipException if calling the SIP service results in an error
      */
@@ -419,9 +411,9 @@ public class SipManager {
     /**
      * Gets the {@link ISipSession} that handles the incoming call. For audio
      * calls, consider to use {@link SipAudioCall} to handle the incoming call.
-     * See {@link #takeAudioCall(Context, Intent, SipAudioCall.Listener)}.
+     * See {@link #takeAudioCall}. Note that the method may be called only once
-     * Note that the method may be called only once for the same intent. For
+     * for the same intent. For subsequent calls on the same intent, the method
-     * subsequent calls on the same intent, the method returns null.
+     * returns null.
      *
      * @param incomingCallIntent the incoming call broadcast intent
      * @return the session object that handles the incoming call

voip/java/android/net/sip/SipProfile.java

@@ -61,7 +61,7 @@ public class SipProfile implements Parcelable, Serializable, Cloneable {
             };
 
     /**
-     * Class to help create a {@link SipProfile}.
+     * Class to help create a {@code SipProfile}.
      */
     public static class Builder {
         private AddressFactory mAddressFactory;
@@ -120,8 +120,8 @@ public class SipProfile implements Parcelable, Serializable, Cloneable {
          *
          * @param username username of the SIP account
          * @param serverDomain the SIP server domain; if the network address
-         *      is different from the domain, use
+         *      is different from the domain, use {@link #setOutboundProxy} to
-         *      {@link #setOutboundProxy(String)} to set server address
+         *      set server address
          * @throws ParseException if the parameters are not valid
          */
         public Builder(String username, String serverDomain)
@@ -309,6 +309,7 @@ public class SipProfile implements Parcelable, Serializable, Cloneable {
      * Gets the SIP URI of this profile.
      *
      * @return the SIP URI of this profile
+     * @hide
      */
     public SipURI getUri() {
         return (SipURI) mAddress.getURI();
@@ -327,6 +328,7 @@ public class SipProfile implements Parcelable, Serializable, Cloneable {
      * Gets the SIP address of this profile.
      *
      * @return the SIP address of this profile
+     * @hide
      */
     public Address getSipAddress() {
         return mAddress;

voip/java/android/net/sip/SipRegistrationListener.java

@@ -29,15 +29,15 @@ public interface SipRegistrationListener {
     void onRegistering(String localProfileUri);
 
     /**
-     * Called when registration is successfully done.
+     * Called when the registration succeeded.
      *
      * @param localProfileUri the URI string of the SIP profile to register with
-     * @param expiryTime duration in second before the registration expires
+     * @param expiryTime duration in seconds before the registration expires
      */
     void onRegistrationDone(String localProfileUri, long expiryTime);
 
     /**
-     * Called when the registration fails.
+     * Called when the registration failed.
      *
      * @param localProfileUri the URI string of the SIP profile to register with
      * @param errorCode error code of this error