Merge "Add comments for RemoteCallVideoClient and RemoteCallVideoProvider." into lmp-dev

2 files changed, 124 insertions, 0 deletions

diff --git a/telecomm/java/android/telecomm/RemoteCallVideoClient.java b/telecomm/java/android/telecomm/RemoteCallVideoClient.java
index f0a3afc..aceba4d 100644
--- a/telecomm/java/android/telecomm/RemoteCallVideoClient.java
+++ b/telecomm/java/android/telecomm/RemoteCallVideoClient.java
@@ -23,6 +23,9 @@ import android.telecomm.VideoCallProfile;
 
 import com.android.internal.telecomm.ICallVideoClient;
 
+/**
+ * Remote class to invoke callbacks in InCallUI related to supporting video in calls.
+ */
 public class RemoteCallVideoClient implements IBinder.DeathRecipient {
     private final ICallVideoClient mCallVideoClient;
 
@@ -36,28 +39,77 @@ public class RemoteCallVideoClient implements IBinder.DeathRecipient {
         mCallVideoClient.asBinder().unlinkToDeath(this, 0);
     }
 
+    /**
+     * Called when a session modification request is received from the remote device.
+     * The remote request is sent via {@link CallVideoProvider#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 CallVideoProvider#onSendSessionModifyResponse} to indicate
+     * the video settings the user has agreed to.
+     *
+     * @param videoCallProfile The requested video call profile.
+     */
     public void receiveSessionModifyRequest(VideoCallProfile videoCallProfile)
             throws RemoteException {
         mCallVideoClient.receiveSessionModifyRequest(videoCallProfile);
     }
 
+    /**
+     * Called when a response to a session modification request is received from the remote device.
+     * The remote InCall UI sends the response using
+     * {@link CallVideoProvider#onSendSessionModifyResponse}.
+     *
+     * @param status Status of the session modify request.  Valid values are
+     *               {@link CallVideoClient#SESSION_MODIFY_REQUEST_SUCCESS},
+     *               {@link CallVideoClient#SESSION_MODIFY_REQUEST_FAIL},
+     *               {@link CallVideoClient#SESSION_MODIFY_REQUEST_INVALID}
+     * @param requestProfile The original request which was sent to the remote device.
+     * @param responseProfile The actual profile changes made by the remote device.
+     */
     public void receiveSessionModifyResponse(int status, VideoCallProfile requestedProfile,
             VideoCallProfile responseProfile) throws RemoteException {
         mCallVideoClient.receiveSessionModifyResponse(status, requestedProfile, 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.
+     * Valid values are: {@link CallVideoClient#SESSION_EVENT_RX_PAUSE},
+     * {@link CallVideoClient#SESSION_EVENT_RX_RESUME},
+     * {@link CallVideoClient#SESSION_EVENT_TX_START}, {@link CallVideoClient#SESSION_EVENT_TX_STOP}
+     *
+     * @param event The event.
+     */
     public void handleCallSessionEvent(int event) throws RemoteException {
         mCallVideoClient.handleCallSessionEvent(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.
+     *
+     * @param width  The updated peer video width.
+     * @param height The updated peer video height.
+     */
     public void updatePeerDimensions(int width, int height) throws RemoteException {
         mCallVideoClient.updatePeerDimensions(width, height);
     }
 
+    /**
+     * Handles an update to the total data used for the current session.
+     *
+     * @param dataUsage The updated data usage.
+     */
     public void updateCallDataUsage(int dataUsage) throws RemoteException {
         mCallVideoClient.updateCallDataUsage(dataUsage);
     }
 
+    /**
+     * Handles a change in camera capabilities.
+     *
+     * @param callCameraCapabilities The changed camera capabilities.
+     */
     public void handleCameraCapabilitiesChange(CallCameraCapabilities callCameraCapabilities)
             throws RemoteException {
         mCallVideoClient.handleCameraCapabilitiesChange(callCameraCapabilities);
diff --git a/telecomm/java/android/telecomm/RemoteCallVideoProvider.java b/telecomm/java/android/telecomm/RemoteCallVideoProvider.java
index a49076a..170cf04 100644
--- a/telecomm/java/android/telecomm/RemoteCallVideoProvider.java
+++ b/telecomm/java/android/telecomm/RemoteCallVideoProvider.java
@@ -22,6 +22,9 @@ import android.view.Surface;
 
 import com.android.internal.telecomm.ICallVideoProvider;
 
+/**
+ * Remote class for InCallUI to invoke functionality provided for video in calls.
+ */
 public class RemoteCallVideoProvider {
     private final ICallVideoProvider mCallVideoProvider;
 
@@ -38,6 +41,12 @@ public class RemoteCallVideoProvider {
         mCallVideoProvider.asBinder().linkToDeath(mDeathRecipient, 0);
     }
 
+    /**
+     * Sets a remote interface for invoking callback methods in the InCallUI after performing
+     * telephony actions.
+     *
+     * @param callVideoClient The call video client.
+     */
     public void setCallVideoClient(CallVideoClient callVideoClient) {
         try {
             mCallVideoProvider.setCallVideoClient(callVideoClient.getBinder());
@@ -45,10 +54,22 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * Sets the camera to be used for video recording in a video call.
+     *
+     * @param cameraId The id of the camera.
+     */
     public void setCamera(String cameraId) throws RemoteException {
         mCallVideoProvider.setCamera(cameraId);
     }
 
+    /**
+     * 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.
+     *
+     * @param surface The surface.
+     */
     public void setPreviewSurface(Surface surface) {
         try {
             mCallVideoProvider.setPreviewSurface(surface);
@@ -56,6 +77,11 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * Sets the surface to be used for displaying the video received from the remote device.
+     *
+     * @param surface The surface.
+     */
     public void setDisplaySurface(Surface surface) {
         try {
             mCallVideoProvider.setDisplaySurface(surface);
@@ -63,6 +89,12 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * Sets the device orientation, in degrees.  Assumes that a standard portrait orientation of the
+     * device is 0 degrees.
+     *
+     * @param rotation The device orientation, in degrees.
+     */
     public void setDeviceOrientation(int rotation) {
         try {
             mCallVideoProvider.setDeviceOrientation(rotation);
@@ -70,10 +102,24 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * Sets camera zoom ratio.
+     *
+     * @param value The camera zoom ratio.
+     */
     public void setZoom(float value) throws RemoteException {
         mCallVideoProvider.setZoom(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 CallVideoClient#onReceiveSessionModifyRequest}.
+     * Some examples of session modification requests: upgrade call from audio to video, downgrade
+     * call from video to audio, pause video.
+     *
+     * @param requestProfile The requested call video properties.
+     */
     public void sendSessionModifyRequest(VideoCallProfile requestProfile) {
         try {
             mCallVideoProvider.sendSessionModifyRequest(requestProfile);
@@ -81,6 +127,16 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * 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 CallVideoClient#onReceiveSessionModifyRequest}.
+     * The response is handled on the remove device by
+     * {@link CallVideoClient#onReceiveSessionModifyResponse}.
+     *
+     * @param responseProfile The response call video properties.
+     */
     public void sendSessionModifyResponse(VideoCallProfile responseProfile) {
         try {
             mCallVideoProvider.sendSessionModifyResponse(responseProfile);
@@ -88,6 +144,11 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * Issues a request to the video provider to retrieve the camera capabilities.
+     * Camera capabilities are reported back to the caller via
+     * {@link CallVideoClient#onHandleCameraCapabilitiesChange(CallCameraCapabilities)}.
+     */
     public void requestCameraCapabilities() {
         try {
             mCallVideoProvider.requestCameraCapabilities();
@@ -95,6 +156,11 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * 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 CallVideoClient#onUpdateCallDataUsage}.
+     */
     public void requestCallDataUsage() {
         try {
             mCallVideoProvider.requestCallDataUsage();
@@ -102,6 +168,12 @@ public class RemoteCallVideoProvider {
         }
     }
 
+    /**
+     * Provides the video telephony framework with the URI of an image to be displayed to remote
+     * devices when the video signal is paused.
+     *
+     * @param uri URI of image to display.
+     */
     public void setPauseImage(String uri) {
         try {
             mCallVideoProvider.setPauseImage(uri);