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();
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.
/**
* 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)
/**
* 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
*/
* 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 {
/**
* 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 {
* 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 {
/**
* 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) {
}
/**
- * 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.
*
/**
* 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 {
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. */
package android.net.sip;
/**
- * General SIP-related exception class.
+ * Indicates a general SIP-related exception.
*/
public class SipException extends Exception {
public SipException() {
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 {
/**
}
/**
- * 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)}
}
/**
- * 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
/**
* 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
* 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)
* 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
* 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)
* 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
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;
};
/**
- * Class to help create a {@code SipProfile}.
+ * Helper class for creating a {@link SipProfile}.
*/
public static class Builder {
private AddressFactory mAddressFactory;
package android.net.sip;
/**
- * Listener class to listen to SIP registration events.
+ * Listener for SIP registration events.
*/
public interface SipRegistrationListener {
/**
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. */
}
/**
- * 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 {
/**
--- /dev/null
+<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>
\ No newline at end of file
OSDN Git Service
