diff options
Diffstat (limited to 'telecomm/java/android/telecom/InCallService.java')
| -rw-r--r-- | telecomm/java/android/telecom/InCallService.java | 190 |
1 files changed, 129 insertions, 61 deletions
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java index e37cff763b34..f7f442549cdb 100644 --- a/telecomm/java/android/telecom/InCallService.java +++ b/telecomm/java/android/telecom/InCallService.java @@ -20,6 +20,7 @@ import android.annotation.SdkConstant; 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 @@ public abstract class InCallService extends Service { } /** - * 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 class InCallService extends Service { 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 @@ public abstract class InCallService extends Service { * 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 @@ public abstract class InCallService extends Service { /** * 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 @@ public abstract class InCallService extends Service { /** * 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. */ |