docs: revise javadocs for sip (02b1d685) · Commits · e / os / android_frameworks_base

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

+31 −28

Original line number	Diff line number	Diff line
		@@ -37,20 +37,19 @@ import java.util.List;
		import java.util.Map;

		/**
		* Class that handles an Internet audio call over SIP. {@link SipManager}
		* facilitates instantiating a {@code SipAudioCall} object for making/receiving
		* calls. See {@link SipManager#makeAudioCall} and
		* {@link SipManager#takeAudioCall}.
		* Handles an Internet audio call over SIP. You can instantiate this class with {@link SipManager},
		* using {@link SipManager#makeAudioCall makeAudioCall()} and {@link SipManager#takeAudioCall
		* takeAudioCall()}.
		*
		* <p>Requires permissions to use this class:
		* <p class="note"><strong>Note:</strong> Using this class require the
		* {@link android.Manifest.permission#INTERNET} and
		* {@link android.Manifest.permission#USE_SIP}.
		* <br/>Requires permissions to {@link #startAudio}:
		* {@link android.Manifest.permission#USE_SIP} permissions.<br/><br/>In addition, {@link
		* #startAudio} requires the
		* {@link android.Manifest.permission#RECORD_AUDIO},
		* {@link android.Manifest.permission#ACCESS_WIFI_STATE} and
		* {@link android.Manifest.permission#WAKE_LOCK}.
		* <br/>Requires permissions to {@link #setSpeakerMode}:
		* {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}.
		* {@link android.Manifest.permission#ACCESS_WIFI_STATE}, and
		* {@link android.Manifest.permission#WAKE_LOCK} permissions; and {@link #setSpeakerMode
		* setSpeakerMode()} requires the
		* {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} permission.</p>
		*/
		public class SipAudioCall {
		private static final String TAG = SipAudioCall.class.getSimpleName();
		@@ -58,7 +57,10 @@ public class SipAudioCall {
		private static final boolean DONT_RELEASE_SOCKET = false;
		private static final int SESSION_TIMEOUT = 5; // in seconds

		/** Listener class for all event callbacks. */
		/** Listener for events relating to a SIP call, such as when a call is being
		* recieved ("on ringing") or a call is outgoing ("on calling").
		* <p>Many of these events are also received by {@link SipSession.Listener}.</p>
		*/
		public static class Listener {
		/**
		* Called when the call object is ready to make another call.
		@@ -199,7 +201,7 @@ public class SipAudioCall {

		/**
		* Sets the listener to listen to the audio call events. The method calls
		* {@code setListener(listener, false)}.
		* {@link #setListener setListener(listener, false)}.
		*
		* @param listener to listen to the audio call events of this object
		* @see #setListener(Listener, boolean)
		@@ -537,14 +539,14 @@ public class SipAudioCall {
		/**
		* Initiates an audio call to the specified profile. The attempt will be
		* timed out if the call is not established within {@code timeout} seconds
		* and {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* and {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* will be called.
		*
		* @param peerProfile the SIP profile to make the call to
		* @param sipSession the {@link SipSession} for carrying out the call
		* @param timeout the timeout value in seconds. Default value (defined by
		* SIP protocol) is used if {@code timeout} is zero or negative.
		* @see Listener.onError
		* @see Listener#onError
		* @throws SipException if the SIP service fails to create a session for the
		* call
		*/
		@@ -582,12 +584,12 @@ public class SipAudioCall {
		* Puts a call on hold. When succeeds, {@link Listener#onCallHeld} is
		* called. The attempt will be timed out if the call is not established
		* within {@code timeout} seconds and
		* {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* will be called.
		*
		* @param timeout the timeout value in seconds. Default value (defined by
		* SIP protocol) is used if {@code timeout} is zero or negative.
		* @see Listener.onError
		* @see Listener#onError
		* @throws SipException if the SIP service fails to hold the call
		*/
		public void holdCall(int timeout) throws SipException {
		@@ -604,12 +606,12 @@ public class SipAudioCall {
		/**
		* Answers a call. The attempt will be timed out if the call is not
		* established within {@code timeout} seconds and
		* {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* will be called.
		*
		* @param timeout the timeout value in seconds. Default value (defined by
		* SIP protocol) is used if {@code timeout} is zero or negative.
		* @see Listener.onError
		* @see Listener#onError
		* @throws SipException if the SIP service fails to answer the call
		*/
		public void answerCall(int timeout) throws SipException {
		@@ -628,12 +630,12 @@ public class SipAudioCall {
		* Continues a call that's on hold. When succeeds,
		* {@link Listener#onCallEstablished} is called. The attempt will be timed
		* out if the call is not established within {@code timeout} seconds and
		* {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* will be called.
		*
		* @param timeout the timeout value in seconds. Default value (defined by
		* SIP protocol) is used if {@code timeout} is zero or negative.
		* @see Listener.onError
		* @see Listener#onError
		* @throws SipException if the SIP service fails to unhold the call
		*/
		public void continueCall(int timeout) throws SipException {
		@@ -786,8 +788,8 @@ public class SipAudioCall {

		/**
		* Puts the device to speaker mode.
		* <p>Requires permission:
		* {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}.
		* <p class="note"><strong>Note:</strong> Requires the
		* {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} permission.</p>
		*/
		public void setSpeakerMode(boolean speakerMode) {
		synchronized (this) {
		@@ -797,20 +799,21 @@ public class SipAudioCall {
		}

		/**
		* Sends a DTMF code. According to RFC2833, event 0--9 maps to decimal
		* Sends a DTMF code. According to <a href="http://tools.ietf.org/html/rfc2833">RFC 2883</a>,
		* event 0--9 maps to decimal
		* value 0--9, '*' to 10, '#' to 11, event 'A'--'D' to 12--15, and event
		* flash to 16. Currently, event flash is not supported.
		*
		* @param code the DTMF code to send. Value 0 to 15 (inclusive) are valid
		* inputs.
		* @see http://tools.ietf.org/html/rfc2833
		*/
		public void sendDtmf(int code) {
		sendDtmf(code, null);
		}

		/**
		* Sends a DTMF code. According to RFC2833, event 0--9 maps to decimal
		* Sends a DTMF code. According to <a href="http://tools.ietf.org/html/rfc2833">RFC 2883</a>,
		* event 0--9 maps to decimal
		* value 0--9, '*' to 10, '#' to 11, event 'A'--'D' to 12--15, and event
		* flash to 16. Currently, event flash is not supported.
		*
		@@ -888,10 +891,10 @@ public class SipAudioCall {
		/**
		* Starts the audio for the established call. This method should be called
		* after {@link Listener#onCallEstablished} is called.
		* <p>Requires permission:
		* <p class="note"><strong>Note:</strong> Requires the
		* {@link android.Manifest.permission#RECORD_AUDIO},
		* {@link android.Manifest.permission#ACCESS_WIFI_STATE} and
		* {@link android.Manifest.permission#WAKE_LOCK}.
		* {@link android.Manifest.permission#WAKE_LOCK} permissions.</p>
		*/
		public void startAudio() {
		try {

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

+5 −5

Original line number	Diff line number	Diff line
		@@ -17,11 +17,11 @@
		package android.net.sip;

		/**
		* Defines error code returned in
		* {@link SipRegistrationListener#onRegistrationFailed},
		* {@link SipSession.Listener#onError},
		* {@link SipSession.Listener#onCallChangeFailed} and
		* {@link SipSession.Listener#onRegistrationFailed}.
		* Defines error codes returned during SIP actions. For example, during
		* {@link SipRegistrationListener#onRegistrationFailed onRegistrationFailed()},
		* {@link SipSession.Listener#onError onError()},
		* {@link SipSession.Listener#onCallChangeFailed onCallChangeFailed()} and
		* {@link SipSession.Listener#onRegistrationFailed onRegistrationFailed()}.
		*/
		public class SipErrorCode {
		/** Not an error. */

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

+1 −1

Original line number	Diff line number	Diff line
		@@ -17,7 +17,7 @@
		package android.net.sip;

		/**
		* General SIP-related exception class.
		* Indicates a general SIP-related exception.
		*/
		public class SipException extends Exception {
		public SipException() {

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

+28 −29

Original line number	Diff line number	Diff line
		@@ -29,30 +29,29 @@ import android.util.Log;
		import java.text.ParseException;

		/**
		* The class provides API for various SIP related tasks. Specifically, the API
		* allows an application to:
		* Provides APIs for SIP tasks, such as initiating SIP connections, and provides access to related
		* SIP services. This class is the starting point for any SIP actions. You can acquire an instance
		* of it with {@link #newInstance newInstance()}.</p>
		* <p>The APIs in this class allows you to:</p>
		* <ul>
		* <li>open a {@link SipProfile} to get ready for making outbound calls or have
		* the background SIP service listen to incoming calls and broadcast them
		* with registered command string. See
		* {@link #open(SipProfile, PendingIntent, SipRegistrationListener)},
		* {@link #open(SipProfile)}, {@link #close}, {@link #isOpened} and
		* {@link #isRegistered}. It also facilitates handling of the incoming call
		* broadcast intent. See
		* {@link #isIncomingCallIntent}, {@link #getCallId},
		* {@link #getOfferSessionDescription} and {@link #takeAudioCall}.</li>
		* <li>make/take SIP-based audio calls. See
		* {@link #makeAudioCall} and {@link #takeAudioCall}.</li>
		* <li>register/unregister with a SIP service provider manually. See
		* {@link #register} and {@link #unregister}.</li>
		* <li>process SIP events directly with a {@link SipSession} created by
		* {@link #createSipSession}.</li>
		* <li>Create a {@link SipSession} to get ready for making calls or listen for incoming calls. See
		* {@link #createSipSession createSipSession()} and {@link #getSessionFor getSessionFor()}.</li>
		* <li>Initiate and receive generic SIP calls or audio-only SIP calls. Generic SIP calls may
		* be video, audio, or other, and are initiated with {@link #open open()}. Audio-only SIP calls
		* should be handled with a {@link SipAudioCall}, which you can acquire with {@link
		* #makeAudioCall makeAudioCall()} and {@link #takeAudioCall takeAudioCall()}.</li>
		* <li>Register and unregister with a SIP service provider, with
		* {@link #register register()} and {@link #unregister unregister()}.</li>
		* <li>Verify session connectivity, with {@link #isOpened isOpened()} and
		* {@link #isRegistered isRegistered()}.</li>
		* </ul>
		* {@code SipManager} can only be instantiated if SIP API is supported by the
		* device. (See {@link #isApiSupported}).
		* <p>Requires permissions to use this class:
		* {@link android.Manifest.permission#INTERNET} and
		* {@link android.Manifest.permission#USE_SIP}.
		* <p class="note"><strong>Note:</strong> Not all Android-powered devices support VOIP calls using
		* SIP. You should always call {@link android.net.sip.SipManager#isVoipSupported
		* isVoipSupported()} to verify that the device supports VOIP calling and {@link
		* android.net.sip.SipManager#isApiSupported isApiSupported()} to verify that the device supports
		* the SIP APIs.<br/><br/>Your application must also request the {@link
		* android.Manifest.permission#INTERNET} and {@link android.Manifest.permission#USE_SIP}
		* permissions.</p>
		*/
		public class SipManager {
		/**
		@@ -160,7 +159,7 @@ public class SipManager {
		}

		/**
		* Opens the profile for making calls. The caller may make subsequent calls
		* Opens the profile for making generic SIP calls. The caller may make subsequent calls
		* through {@link #makeAudioCall}. If one also wants to receive calls on the
		* profile, use
		* {@link #open(SipProfile, PendingIntent, SipRegistrationListener)}
		@@ -179,7 +178,7 @@ public class SipManager {
		}

		/**
		* Opens the profile for making calls and/or receiving calls. The caller may
		* Opens the profile for making calls and/or receiving generic SIP calls. The caller may
		* make subsequent calls through {@link #makeAudioCall}. If the
		* auto-registration option is enabled in the profile, the SIP service
		* will register the profile to the corresponding SIP provider periodically
		@@ -296,7 +295,7 @@ public class SipManager {
		/**
		* Creates a {@link SipAudioCall} to make a call. The attempt will be timed
		* out if the call is not established within {@code timeout} seconds and
		* {@code SipAudioCall.Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* {@link SipAudioCall.Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* will be called.
		*
		* @param localProfile the SIP profile to make the call from
		@@ -307,7 +306,7 @@ public class SipManager {
		* SIP protocol) is used if {@code timeout} is zero or negative.
		* @return a {@link SipAudioCall} object
		* @throws SipException if calling the SIP service results in an error
		* @see SipAudioCall.Listener.onError
		* @see SipAudioCall.Listener#onError
		*/
		public SipAudioCall makeAudioCall(SipProfile localProfile,
		SipProfile peerProfile, SipAudioCall.Listener listener, int timeout)
		@@ -327,7 +326,7 @@ public class SipManager {
		* Creates a {@link SipAudioCall} to make an audio call. The attempt will be
		* timed out if the call is not established within {@code timeout} seconds
		* and
		* {@code SipAudioCall.Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* {@link SipAudioCall.Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
		* will be called.
		*
		* @param localProfileUri URI of the SIP profile to make the call from
		@@ -338,7 +337,7 @@ public class SipManager {
		* SIP protocol) is used if {@code timeout} is zero or negative.
		* @return a {@link SipAudioCall} object
		* @throws SipException if calling the SIP service results in an error
		* @see SipAudioCall.Listener.onError
		* @see SipAudioCall.Listener#onError
		*/
		public SipAudioCall makeAudioCall(String localProfileUri,
		String peerProfileUri, SipAudioCall.Listener listener, int timeout)
		@@ -449,7 +448,7 @@ public class SipManager {
		* receiving calls.
		* {@link #open(SipProfile, PendingIntent, SipRegistrationListener)} is
		* still needed to be called at least once in order for the SIP service to
		* notify the caller with the {@code PendingIntent} when an incoming call is
		* notify the caller with the {@link android.app.PendingIntent} when an incoming call is
		* received.
		*
		* @param localProfile the SIP profile to register with

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

+5 −2

Original line number	Diff line number	Diff line
		@@ -32,7 +32,10 @@ import javax.sip.address.SipURI;
		import javax.sip.address.URI;

		/**
		* Class containing a SIP account, domain and server information.
		* Defines a SIP profile, including a SIP account, domain and server information.
		* <p>You can create a {@link SipProfile} using {@link
		* SipProfile.Builder}. You can also retrieve one from a {@link SipSession}, using {@link
		* SipSession#getLocalProfile} and {@link SipSession#getPeerProfile}.</p>
		*/
		public class SipProfile implements Parcelable, Serializable, Cloneable {
		private static final long serialVersionUID = 1L;
		@@ -59,7 +62,7 @@ public class SipProfile implements Parcelable, Serializable, Cloneable {
		};

		/**
		* Class to help create a {@code SipProfile}.
		* Helper class for creating a {@link SipProfile}.
		*/
		public static class Builder {
		private AddressFactory mAddressFactory;