Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: revise javadocs for sip add a package description, revise class descriptions and edit some method docs" into gingerbread

Browse Source
This commit is contained in:
Scott Main
2010-10-29 10:03:36 -07:00
committed by Android (Google) Code Review
parent ed3c7be842 02b1d685cc
commit 1112632a41
8 changed files with 118 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
voip/java/android/net/sip/SipAudioCall.java
View File

@@ -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 {

10
voip/java/android/net/sip/SipErrorCode.java
View File

@@ -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. */

2
voip/java/android/net/sip/SipException.java
View File

@@ -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() {

57
voip/java/android/net/sip/SipManager.java
View File

@@ -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

7
voip/java/android/net/sip/SipProfile.java
View File

@@ -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;

2
voip/java/android/net/sip/SipRegistrationListener.java
View File

@@ -17,7 +17,7 @@
package android.net.sip;
/**
* Listener class to listen to SIP registration events.
* Listener for SIP registration events.
*/
public interface SipRegistrationListener {
/**

11
voip/java/android/net/sip/SipSession.java
View File

@@ -20,14 +20,17 @@ import android.os.RemoteException;
import android.util.Log;
/**
* A SIP session that is associated with a SIP dialog or a standalone
* Represents a SIP session that is associated with a SIP dialog or a standalone
* transaction not within a dialog.
* <p>You can get a {@link SipSession} from {@link SipManager} with {@link
* SipManager#createSipSession createSipSession()} (when initiating calls) or {@link
* SipManager#getSessionFor getSessionFor()} (when receiving calls).</p>
*/
public final class SipSession {
private static final String TAG = "SipSession";
/**
* Defines {@link SipSession} states.
* Defines SIP session states, such as "registering", "outgoing call", and "in call".
*/
public static class State {
/** When session is ready to initiate a call or transaction. */
@@ -98,7 +101,9 @@ public final class SipSession {
}
/**
* Listener class that listens to {@link SipSession} events.
* Listener for events relating to a SIP session, such as when a session is being registered
* ("on registering") or a call is outgoing ("on calling").
* <p>Many of these events are also received by {@link SipAudioCall.Listener}.</p>
*/
public static class Listener {
/**

39
voip/java/android/net/sip/package.html Normal file
View File

@@ -0,0 +1,39 @@
<HTML>
<BODY>
<p>Provides access to Session Initiation Protocol (SIP) functionality, such as
making and answering VOIP calls using SIP.</p>
<p>To get started, you need to get an instance of the {@link android.net.sip.SipManager} by
calling {@link android.net.sip.SipManager#newInstance newInstance()}.</p>
<p>With the {@link android.net.sip.SipManager}, you can initiate SIP audio calls with {@link
android.net.sip.SipManager#makeAudioCall makeAudioCall()} and {@link
android.net.sip.SipManager#takeAudioCall takeAudioCall()}. Both methods require
a {@link android.net.sip.SipAudioCall.Listener} that receives callbacks when the state of the
call changes, such as when the call is ringing, established, or ended.</p>
<p>Both {@link android.net.sip.SipManager#makeAudioCall makeAudioCall()} also requires two
{@link android.net.sip.SipProfile} objects, representing the local device and the peer
device. You can create a {@link android.net.sip.SipProfile} using the {@link
android.net.sip.SipProfile.Builder} subclass.</p>
<p>Once you have a {@link android.net.sip.SipAudioCall}, you can perform SIP audio call actions with
the instance, such as make a call, answer a call, mute a call, turn on speaker mode, send DTMF
tones, and more.</p>
<p>If you want to create generic SIP connections (such as for video calls or other), you can
create a SIP connection from the {@link android.net.sip.SipManager}, using {@link
android.net.sip.SipManager#open open()}. If you only want to create audio SIP calls, though, you
should use the {@link android.net.sip.SipAudioCall} class, as described above.</p>
<p class="note"><strong>Note:</strong>
Not all Android-powered devices support VOIP functionality with SIP. Before performing any SIP
activity, you should 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 in order to use the SIP APIs.
</p>
</BODY>
</HTML>