Cleanup Video API javadoc.
- Cleaned up documentation and added more details where possible.
- Also added cross references from the VideoProvider and VideoCall
APIs to make it more clear what the link is between the two.
Bug: 21520606
Change-Id: I0a79450d69841df5850061311a523b37688efc49
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java
index e37cff7..f7f4425 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -20,6 +20,7 @@
import android.annotation.SystemApi;
import android.app.Service;
import android.content.Intent;
+import android.hardware.camera2.CameraManager;
import android.net.Uri;
import android.os.Handler;
import android.os.IBinder;
@@ -387,7 +388,8 @@
}
/**
- * Class to invoke functionality related to video calls.
+ * Used to issue commands to the {@link Connection.VideoProvider} associated with a
+ * {@link Call}.
*/
public static abstract class VideoCall {
@@ -410,14 +412,17 @@
public abstract void registerCallback(VideoCall.Callback callback, Handler handler);
/**
- * Clears the video call listener set via {@link #registerCallback}.
+ * Clears the video call callback set via {@link #registerCallback}.
*/
public abstract void unregisterCallback(VideoCall.Callback callback);
/**
- * Sets the camera to be used for video recording in a video call.
+ * Sets the camera to be used for the outgoing video.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onSetCamera(String)}.
*
- * @param cameraId The id of the camera.
+ * @param cameraId The id of the camera (use ids as reported by
+ * {@link CameraManager#getCameraIdList()}).
*/
public abstract void setCamera(String cameraId);
@@ -425,21 +430,27 @@
* Sets the surface to be used for displaying a preview of what the user's camera is
* currently capturing. When video transmission is enabled, this is the video signal which
* is sent to the remote device.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onSetPreviewSurface(Surface)}.
*
- * @param surface The surface.
+ * @param surface The {@link Surface}.
*/
public abstract void setPreviewSurface(Surface surface);
/**
* Sets the surface to be used for displaying the video received from the remote device.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onSetDisplaySurface(Surface)}.
*
- * @param surface The surface.
+ * @param surface The {@link Surface}.
*/
public abstract void setDisplaySurface(Surface surface);
/**
* Sets the device orientation, in degrees. Assumes that a standard portrait orientation of
* the device is 0 degrees.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onSetDeviceOrientation(int)}.
*
* @param rotation The device orientation, in degrees.
*/
@@ -447,109 +458,145 @@
/**
* Sets camera zoom ratio.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onSetZoom(float)}.
*
* @param value The camera zoom ratio.
*/
public abstract void setZoom(float value);
/**
- * Issues a request to modify the properties of the current session. The request is sent to
- * the remote device where it it handled by
- * {@link VideoCall.Callback#onSessionModifyRequestReceived}.
- * Some examples of session modification requests: upgrade call from audio to video,
- * downgrade call from video to audio, pause video.
+ * Issues a request to modify the properties of the current video session.
+ * <p>
+ * Example scenarios include: requesting an audio-only call to be upgraded to a
+ * bi-directional video call, turning on or off the user's camera, sending a pause signal
+ * when the {@link InCallService} is no longer the foreground application.
+ * <p>
+ * Handled by
+ * {@link Connection.VideoProvider#onSendSessionModifyRequest(VideoProfile, VideoProfile)}.
*
* @param requestProfile The requested call video properties.
*/
public abstract void sendSessionModifyRequest(VideoProfile requestProfile);
/**
- * Provides a response to a request to change the current call session video
- * properties.
- * This is in response to a request the InCall UI has received via
- * {@link VideoCall.Callback#onSessionModifyRequestReceived}.
- * The response is handled on the remove device by
- * {@link VideoCall.Callback#onSessionModifyResponseReceived}.
+ * Provides a response to a request to change the current call video session
+ * properties. This should be called in response to a request the {@link InCallService} has
+ * received via {@link VideoCall.Callback#onSessionModifyRequestReceived}.
+ * <p>
+ * Handled by
+ * {@link Connection.VideoProvider#onSendSessionModifyResponse(VideoProfile)}.
*
* @param responseProfile The response call video properties.
*/
public abstract void sendSessionModifyResponse(VideoProfile responseProfile);
/**
- * Issues a request to the video provider to retrieve the camera capabilities.
- * Camera capabilities are reported back to the caller via
- * {@link VideoCall.Callback#onCameraCapabilitiesChanged(CameraCapabilities)}.
+ * Issues a request to the {@link Connection.VideoProvider} to retrieve the capabilities
+ * of the current camera. The current camera is selected using
+ * {@link VideoCall#setCamera(String)}.
+ * <p>
+ * Camera capabilities are reported to the caller via
+ * {@link VideoCall.Callback#onCameraCapabilitiesChanged(VideoProfile.CameraCapabilities)}.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onRequestCameraCapabilities()}.
*/
public abstract void requestCameraCapabilities();
/**
- * Issues a request to the video telephony framework to retrieve the cumulative data usage for
- * the current call. Data usage is reported back to the caller via
- * {@link VideoCall.Callback#onCallDataUsageChanged}.
+ * Issues a request to the {@link Connection.VideoProvider} to retrieve the cumulative data
+ * usage for the video component of the current call (in bytes). Data usage is reported
+ * to the caller via {@link VideoCall.Callback#onCallDataUsageChanged}.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onRequestConnectionDataUsage()}.
*/
public abstract void requestCallDataUsage();
/**
- * Provides the video telephony framework with the URI of an image to be displayed to remote
- * devices when the video signal is paused.
+ * Provides the {@link Connection.VideoProvider} with the {@link Uri} of an image to be
+ * displayed to the peer device when the video signal is paused.
+ * <p>
+ * Handled by {@link Connection.VideoProvider#onSetPauseImage(Uri)}.
*
* @param uri URI of image to display.
*/
public abstract void setPauseImage(Uri uri);
/**
- * Callback class which invokes callbacks after video call actions occur.
+ * The {@link InCallService} extends this class to provide a means of receiving callbacks
+ * from the {@link Connection.VideoProvider}.<p>
+ * When the {@link InCallService} receives the
+ * {@link Call.Callback#onVideoCallChanged(Call, VideoCall)} callback, it should create an
+ * instance its {@link VideoCall.Callback} implementation and set it on the
+ * {@link VideoCall} using {@link VideoCall#registerCallback(Callback)}.
*/
public static abstract class Callback {
/**
- * Called when a session modification request is received from the remote device.
- * The remote request is sent via
- * {@link Connection.VideoProvider#onSendSessionModifyRequest}. The InCall UI
- * is responsible for potentially prompting the user whether they wish to accept the new
- * call profile (e.g. prompt user if they wish to accept an upgrade from an audio to a
- * video call) and should call
- * {@link Connection.VideoProvider#onSendSessionModifyResponse} to indicate
- * the video settings the user has agreed to.
+ * Called when the {@link Connection.VideoProvider} receives a session modification
+ * request is received from the peer device.
+ * <p>
+ * The {@link InCallService} may potentially prompt the user to confirm whether they
+ * wish to accept the request, or decide to automatically accept the request. In either
+ * case the {@link InCallService} should call
+ * {@link VideoCall#sendSessionModifyResponse(VideoProfile)} to indicate the video
+ * profile agreed upon.
+ * <p>
+ * Callback originates from
+ * {@link Connection.VideoProvider#receiveSessionModifyRequest(VideoProfile)}.
*
- * @param videoProfile The requested video call profile.
+ * @param videoProfile The requested video profile.
*/
public abstract void onSessionModifyRequestReceived(VideoProfile videoProfile);
/**
- * Called when a response to a session modification request is received from the remote
- * device. The remote InCall UI sends the response using
- * {@link Connection.VideoProvider#onSendSessionModifyResponse}.
+ * Called when the {@link Connection.VideoProvider} receives a response to a session
+ * modification request previously sent to the peer device.
+ * <p>
+ * The new video state should not be considered active by the {@link InCallService}
+ * until the {@link Call} video state changes (the
+ * {@link Call.Callback#onDetailsChanged(Call, Call.Details)} callback is triggered
+ * when the video state changes).
+ * <p>
+ * Callback originates from
+ * {@link Connection.VideoProvider#receiveSessionModifyResponse(int, VideoProfile,
+ * VideoProfile)}.
*
* @param status Status of the session modify request. Valid values are
- * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
- * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
- * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_INVALID}
- * @param requestedProfile The original request which was sent to the remote device.
- * @param responseProfile The actual profile changes made by the remote device.
+ * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS},
+ * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_FAIL},
+ * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_INVALID},
+ * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_TIMED_OUT},
+ * {@link Connection.VideoProvider#SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE}.
+ * @param requestedProfile The original request which was sent to the peer device.
+ * @param responseProfile The actual profile changes made by the peer device.
*/
public abstract void onSessionModifyResponseReceived(int status,
VideoProfile requestedProfile, VideoProfile responseProfile);
/**
- * Handles events related to the current session which the client may wish to handle.
- * These are separate from requested changes to the session due to the underlying
- * protocol or connection.
+ * Handles events related to the current video session which the {@link InCallService}
+ * may wish to handle. These are separate from requested changes to the session due to
+ * the underlying protocol or connection.
+ * <p>
+ * Callback originates from
+ * {@link Connection.VideoProvider#handleCallSessionEvent(int)}.
*
- * Valid values are:
- * {@link Connection.VideoProvider#SESSION_EVENT_RX_PAUSE},
- * {@link Connection.VideoProvider#SESSION_EVENT_RX_RESUME},
- * {@link Connection.VideoProvider#SESSION_EVENT_TX_START},
- * {@link Connection.VideoProvider#SESSION_EVENT_TX_STOP},
- * {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
- * {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_READY}
- *
- * @param event The event.
+ * @param event The event. Valid values are:
+ * {@link Connection.VideoProvider#SESSION_EVENT_RX_PAUSE},
+ * {@link Connection.VideoProvider#SESSION_EVENT_RX_RESUME},
+ * {@link Connection.VideoProvider#SESSION_EVENT_TX_START},
+ * {@link Connection.VideoProvider#SESSION_EVENT_TX_STOP},
+ * {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_FAILURE},
+ * {@link Connection.VideoProvider#SESSION_EVENT_CAMERA_READY}.
*/
public abstract void onCallSessionEvent(int event);
/**
- * Handles a change to the video dimensions from the remote caller (peer). This could
- * happen if, for example, the peer changes orientation of their device.
+ * Handles a change to the video dimensions from the peer device. This could happen if,
+ * for example, the peer changes orientation of their device, or switches cameras.
+ * <p>
+ * Callback originates from
+ * {@link Connection.VideoProvider#changePeerDimensions(int, int)}.
*
* @param width The updated peer video width.
* @param height The updated peer video height.
@@ -558,20 +605,41 @@
/**
* Handles a change to the video quality.
+ * <p>
+ * Callback originates from {@link Connection.VideoProvider#changeVideoQuality(int)}.
*
- * @param videoQuality The updated peer video quality.
+ * @param videoQuality The updated peer video quality. Valid values:
+ * {@link VideoProfile#QUALITY_HIGH},
+ * {@link VideoProfile#QUALITY_MEDIUM},
+ * {@link VideoProfile#QUALITY_LOW},
+ * {@link VideoProfile#QUALITY_DEFAULT}.
*/
public abstract void onVideoQualityChanged(int videoQuality);
/**
- * Handles an update to the total data used for the current session.
+ * Handles an update to the total data used for the current video session.
+ * <p>
+ * Used by the {@link Connection.VideoProvider} in response to
+ * {@link VideoCall#requestCallDataUsage()}. May also be called periodically by the
+ * {@link Connection.VideoProvider}.
+ * <p>
+ * Callback originates from {@link Connection.VideoProvider#setCallDataUsage(long)}.
*
- * @param dataUsage The updated data usage.
+ * @param dataUsage The updated data usage (in bytes).
*/
public abstract void onCallDataUsageChanged(long dataUsage);
/**
- * Handles a change in camera capabilities.
+ * Handles a change in the capabilities of the currently selected camera.
+ * <p>
+ * Used by the {@link Connection.VideoProvider} in response to
+ * {@link VideoCall#requestCameraCapabilities()}. The {@link Connection.VideoProvider}
+ * may also report the camera capabilities after a call to
+ * {@link VideoCall#setCamera(String)}.
+ * <p>
+ * Callback originates from
+ * {@link Connection.VideoProvider#changeCameraCapabilities(
+ * VideoProfile.CameraCapabilities)}.
*
* @param cameraCapabilities The changed camera capabilities.
*/