Added in API level 23

Summary: Constants | Ctors | Methods | Inherited Methods

Connection.VideoProvider

---

Kotlin |Java

public static abstract class Connection.VideoProvider
extends Object

java.lang.Object
↳	android.telecom.Connection.VideoProvider

---

Provides a means of controlling the video session associated with a Connection.

Implementations create a custom subclass of VideoProvider and the ConnectionService creates an instance sets it on the Connection using Connection#setVideoProvider(VideoProvider). Any connection which supports video should set the VideoProvider.

The VideoProvider serves two primary purposes: it provides a means for Telecom and InCallService implementations to issue requests related to the video session; it provides a means for the ConnectionService to report events and information related to the video session to Telecom and the InCallService implementations.

InCallService implementations interact with the VideoProvider via InCallService.VideoCall.

Summary

Constants
int	SESSION_EVENT_CAMERA_FAILURE A camera failure has occurred for the selected camera.
int	SESSION_EVENT_CAMERA_PERMISSION_ERROR Session event raised by Telecom when InCallService.VideoCall.setCamera(String) is called and the caller does not have the necessary Manifest.permission.CAMERA permission.
int	SESSION_EVENT_CAMERA_READY Issued after SESSION_EVENT_CAMERA_FAILURE when the camera is once again ready for operation.
int	SESSION_EVENT_RX_PAUSE Video is not being received (no protocol pause was issued).
int	SESSION_EVENT_RX_RESUME Video reception has resumed after a SESSION_EVENT_RX_PAUSE.
int	SESSION_EVENT_TX_START Video transmission has begun.
int	SESSION_EVENT_TX_STOP Video transmission has stopped.
int	SESSION_MODIFY_REQUEST_FAIL Session modify request failed.
int	SESSION_MODIFY_REQUEST_INVALID Session modify request ignored due to invalid parameters.
int	SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE Session modify request rejected by remote user.
int	SESSION_MODIFY_REQUEST_SUCCESS Session modify request was successful.
int	SESSION_MODIFY_REQUEST_TIMED_OUT Session modify request timed out.

Public constructors
VideoProvider()

Public methods
void	changeCameraCapabilities(VideoProfile.CameraCapabilities cameraCapabilities) Used to inform listening InCallService implementations when the capabilities of the current camera have changed.
void	changePeerDimensions(int width, int height) Used to inform listening InCallService implementations when the dimensions of the peer's video have changed.
void	changeVideoQuality(int videoQuality) Used to inform listening InCallService implementations when the video quality of the call has changed.
void	handleCallSessionEvent(int event) Used to inform listening InCallService implementations when the VideoProvider reports a call session event.
abstract void	onRequestCameraCapabilities() Issues a request to the VideoProvider to retrieve the camera capabilities.
abstract void	onRequestConnectionDataUsage() Issues a request to the VideoProvider to retrieve the current data usage for the video component of the current Connection.
abstract void	onSendSessionModifyRequest(VideoProfile fromProfile, VideoProfile toProfile) Issues a request to modify the properties of the current video session.
abstract void	onSendSessionModifyResponse(VideoProfile responseProfile) Provides a response to a request to change the current video session properties.
abstract void	onSetCamera(String cameraId) Sets the camera to be used for the outgoing video.
abstract void	onSetDeviceOrientation(int rotation) Sets the device orientation, in degrees.
abstract void	onSetDisplaySurface(Surface surface) Sets the surface to be used for displaying the video received from the remote device.
abstract void	onSetPauseImage(Uri uri) Provides the VideoProvider with the Uri of an image to be displayed to the peer device when the video signal is paused.
abstract void	onSetPreviewSurface(Surface surface) Sets the surface to be used for displaying a preview of what the user's camera is currently capturing.
abstract void	onSetZoom(float value) Sets the camera zoom ratio.
void	receiveSessionModifyRequest(VideoProfile videoProfile) Used to inform listening InCallService implementations when the VideoProvider receives a session modification request.
void	receiveSessionModifyResponse(int status, VideoProfile requestedProfile, VideoProfile responseProfile) Used to inform listening InCallService implementations when the VideoProvider receives a response to a session modification request.
void	setCallDataUsage(long dataUsage) Used to inform listening InCallService implementations when the data usage of the video associated with the current Connection has changed.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

SESSION_EVENT_CAMERA_FAILURE

Added in API level 23

public static final int SESSION_EVENT_CAMERA_FAILURE

A camera failure has occurred for the selected camera. The VideoProvider can use this as a cue to inform the user the camera is not available.

See also:

• handleCallSessionEvent(int)

Constant Value: 5 (0x00000005)

SESSION_EVENT_CAMERA_PERMISSION_ERROR

Added in API level 26

public static final int SESSION_EVENT_CAMERA_PERMISSION_ERROR

Session event raised by Telecom when InCallService.VideoCall.setCamera(String) is called and the caller does not have the necessary Manifest.permission.CAMERA permission.

See also:

• handleCallSessionEvent(int)

Constant Value: 7 (0x00000007)

SESSION_EVENT_CAMERA_READY

Added in API level 23

public static final int SESSION_EVENT_CAMERA_READY

Issued after SESSION_EVENT_CAMERA_FAILURE when the camera is once again ready for operation. The VideoProvider can use this as a cue to inform the user that the camera has become available again.

See also:

• handleCallSessionEvent(int)

Constant Value: 6 (0x00000006)

SESSION_EVENT_RX_PAUSE

Added in API level 23

public static final int SESSION_EVENT_RX_PAUSE

Video is not being received (no protocol pause was issued).

See also:

• handleCallSessionEvent(int)

Constant Value: 1 (0x00000001)

SESSION_EVENT_RX_RESUME

Added in API level 23

public static final int SESSION_EVENT_RX_RESUME

Video reception has resumed after a SESSION_EVENT_RX_PAUSE.

See also:

• handleCallSessionEvent(int)

Constant Value: 2 (0x00000002)

SESSION_EVENT_TX_START

Added in API level 23

public static final int SESSION_EVENT_TX_START

Video transmission has begun. This occurs after a negotiated start of video transmission when the underlying protocol has actually begun transmitting video to the remote party.

See also:

• handleCallSessionEvent(int)

Constant Value: 3 (0x00000003)

SESSION_EVENT_TX_STOP

Added in API level 23

public static final int SESSION_EVENT_TX_STOP

Video transmission has stopped. This occurs after a negotiated stop of video transmission when the underlying protocol has actually stopped transmitting video to the remote party.

See also:

• handleCallSessionEvent(int)

Constant Value: 4 (0x00000004)

SESSION_MODIFY_REQUEST_FAIL

Added in API level 23

public static final int SESSION_MODIFY_REQUEST_FAIL

Session modify request failed.

See also:

• receiveSessionModifyResponse(int, VideoProfile, VideoProfile)

Constant Value: 2 (0x00000002)

SESSION_MODIFY_REQUEST_INVALID

Added in API level 23

public static final int SESSION_MODIFY_REQUEST_INVALID

Session modify request ignored due to invalid parameters.

See also:

• receiveSessionModifyResponse(int, VideoProfile, VideoProfile)

Constant Value: 3 (0x00000003)

SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE

Added in API level 23

public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE

Session modify request rejected by remote user.

See also:

• receiveSessionModifyResponse(int, VideoProfile, VideoProfile)

Constant Value: 5 (0x00000005)

SESSION_MODIFY_REQUEST_SUCCESS

Added in API level 23

public static final int SESSION_MODIFY_REQUEST_SUCCESS

Session modify request was successful.

See also:

• receiveSessionModifyResponse(int, VideoProfile, VideoProfile)

Constant Value: 1 (0x00000001)

SESSION_MODIFY_REQUEST_TIMED_OUT

Added in API level 23

public static final int SESSION_MODIFY_REQUEST_TIMED_OUT

Session modify request timed out.

See also:

• receiveSessionModifyResponse(int, VideoProfile, VideoProfile)

Constant Value: 4 (0x00000004)

Public constructors

VideoProvider

Added in API level 23

public VideoProvider ()

Public methods

changeCameraCapabilities

Added in API level 23

public void changeCameraCapabilities (VideoProfile.CameraCapabilities cameraCapabilities)

Used to inform listening InCallService implementations when the capabilities of the current camera have changed.

The VideoProvider should call this in response to VideoProvider#onRequestCameraCapabilities(), or when the current camera is changed via VideoProvider#onSetCamera(String).

Received by the InCallService via InCallService.VideoCall.Callback#onCameraCapabilitiesChanged( VideoProfile.CameraCapabilities).

Parameters
cameraCapabilities	VideoProfile.CameraCapabilities: The new camera capabilities.

changePeerDimensions

Added in API level 23

public void changePeerDimensions (int width, 
                int height)

Used to inform listening InCallService implementations when the dimensions of the peer's video have changed.

This could occur if, for example, the peer rotates their device, changing the aspect ratio of the video, or if the user switches between the back and front cameras.

Received by the InCallService via InCallService.VideoCall.Callback#onPeerDimensionsChanged(int, int).

Parameters
width	int: The updated peer video width.
height	int: The updated peer video height.

changeVideoQuality

Added in API level 23

public void changeVideoQuality (int videoQuality)

Used to inform listening InCallService implementations when the video quality of the call has changed.

Received by the InCallService via InCallService.VideoCall.Callback#onVideoQualityChanged(int).

Parameters
videoQuality	int: The updated video quality. Valid values: VideoProfile#QUALITY_HIGH, VideoProfile#QUALITY_MEDIUM, VideoProfile#QUALITY_LOW, VideoProfile#QUALITY_DEFAULT.

handleCallSessionEvent

Added in API level 23

public void handleCallSessionEvent (int event)

Used to inform listening InCallService implementations when the VideoProvider reports a call session event.

Received by the InCallService via InCallService.VideoCall.Callback#onCallSessionEvent(int).

Parameters
event	int: The event. Valid values are: VideoProvider#SESSION_EVENT_RX_PAUSE, VideoProvider#SESSION_EVENT_RX_RESUME, VideoProvider#SESSION_EVENT_TX_START, VideoProvider#SESSION_EVENT_TX_STOP, VideoProvider#SESSION_EVENT_CAMERA_FAILURE, VideoProvider#SESSION_EVENT_CAMERA_READY, VideoProvider#SESSION_EVENT_CAMERA_FAILURE.

onRequestCameraCapabilities

Added in API level 23

public abstract void onRequestCameraCapabilities ()

Issues a request to the VideoProvider to retrieve the camera capabilities.

The VideoProvider should respond by communicating the capabilities of the chosen camera via VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities).

Sent from the InCallService via InCallService.VideoCall#requestCameraCapabilities().

onRequestConnectionDataUsage

Added in API level 23

public abstract void onRequestConnectionDataUsage ()

Issues a request to the VideoProvider to retrieve the current data usage for the video component of the current Connection.

The VideoProvider should respond by communicating current data usage, in bytes, via VideoProvider#setCallDataUsage(long).

Sent from the InCallService via InCallService.VideoCall#requestCallDataUsage().

onSendSessionModifyRequest

Added in API level 23

public abstract void onSendSessionModifyRequest (VideoProfile fromProfile, 
                VideoProfile toProfile)

Issues a request to modify the properties of the current video session.

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 InCallService is no longer the foreground application.

If the VideoProvider determines a request to be invalid, it should call receiveSessionModifyResponse(int, android.telecom.VideoProfile, android.telecom.VideoProfile) to report the invalid request back to the InCallService.

Where a request requires confirmation from the user of the peer device, the VideoProvider must communicate the request to the peer device and handle the user's response. receiveSessionModifyResponse(int, android.telecom.VideoProfile, android.telecom.VideoProfile) is used to inform the InCallService of the result of the request.

Sent from the InCallService via InCallService.VideoCall#sendSessionModifyRequest(VideoProfile).

Parameters
fromProfile	VideoProfile: The video profile prior to the request.
toProfile	VideoProfile: The video profile with the requested changes made.

onSendSessionModifyResponse

Added in API level 23

public abstract void onSendSessionModifyResponse (VideoProfile responseProfile)

Provides a response to a request to change the current video session properties.

For example, if the peer requests and upgrade from an audio-only call to a bi-directional video call, could decline the request and keep the call as audio-only. In such a scenario, the responseProfile would have a video state of VideoProfile#STATE_AUDIO_ONLY. If the user had decided to accept the request, the video state would be VideoProfile#STATE_BIDIRECTIONAL.

Sent from the InCallService via InCallService.VideoCall#sendSessionModifyResponse(VideoProfile) in response to a InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile) callback.

Parameters
responseProfile	VideoProfile: The response video profile.

onSetCamera

Added in API level 23

public abstract void onSetCamera (String cameraId)

Sets the camera to be used for the outgoing video.

The VideoProvider should respond by communicating the capabilities of the chosen camera via VideoProvider#changeCameraCapabilities(VideoProfile.CameraCapabilities).

Sent from the InCallService via InCallService.VideoCall#setCamera(String).

Parameters
cameraId	String: The id of the camera (use ids as reported by CameraManager#getCameraIdList()).

onSetDeviceOrientation

Added in API level 23

public abstract void onSetDeviceOrientation (int rotation)

Sets the device orientation, in degrees. Assumes that a standard portrait orientation of the device is 0 degrees.

Sent from the InCallService via InCallService.VideoCall#setDeviceOrientation(int).

Parameters
rotation	int: The device orientation, in degrees.

onSetDisplaySurface

Added in API level 23

public abstract void onSetDisplaySurface (Surface surface)

Sets the surface to be used for displaying the video received from the remote device.

Sent from the InCallService via InCallService.VideoCall#setDisplaySurface(Surface).

Parameters
surface	Surface: The Surface.

onSetPauseImage

Added in API level 23

public abstract void onSetPauseImage (Uri uri)

Provides the VideoProvider with the Uri of an image to be displayed to the peer device when the video signal is paused.

Sent from the InCallService via InCallService.VideoCall#setPauseImage(Uri).

Parameters
uri	Uri: URI of image to display.

onSetPreviewSurface

Added in API level 23

public abstract void onSetPreviewSurface (Surface surface)

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.

Sent from the InCallService via InCallService.VideoCall#setPreviewSurface(Surface).

Parameters
surface	Surface: The Surface.

onSetZoom

Added in API level 23

public abstract void onSetZoom (float value)

Sets the camera zoom ratio.

Sent from the InCallService via InCallService.VideoCall#setZoom(float).

Parameters
value	float: The camera zoom ratio; for the current camera, should be a value in the range defined by CameraCharacteristics.CONTROL_ZOOM_RATIO_RANGE.

receiveSessionModifyRequest

Added in API level 23

public void receiveSessionModifyRequest (VideoProfile videoProfile)

Used to inform listening InCallService implementations when the VideoProvider receives a session modification request.

Received by the InCallService via InCallService.VideoCall.Callback#onSessionModifyRequestReceived(VideoProfile),

Parameters
videoProfile	VideoProfile: The requested video profile.

See also:

• onSendSessionModifyRequest(VideoProfile, VideoProfile)

receiveSessionModifyResponse

Added in API level 23

public void receiveSessionModifyResponse (int status, 
                VideoProfile requestedProfile, 
                VideoProfile responseProfile)

Used to inform listening InCallService implementations when the VideoProvider receives a response to a session modification request.

Received by the InCallService via InCallService.VideoCall.Callback#onSessionModifyResponseReceived(int, VideoProfile, VideoProfile).

Parameters
status	int: Status of the session modify request. Valid values are VideoProvider#SESSION_MODIFY_REQUEST_SUCCESS, VideoProvider#SESSION_MODIFY_REQUEST_FAIL, VideoProvider#SESSION_MODIFY_REQUEST_INVALID, VideoProvider#SESSION_MODIFY_REQUEST_TIMED_OUT, VideoProvider#SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE
requestedProfile	VideoProfile: The original request which was sent to the peer device.
responseProfile	VideoProfile: The actual profile changes agreed to by the peer device.

See also:

• onSendSessionModifyRequest(VideoProfile, VideoProfile)

setCallDataUsage

Added in API level 23

public void setCallDataUsage (long dataUsage)

Used to inform listening InCallService implementations when the data usage of the video associated with the current Connection has changed.

This could be in response to a preview request via onRequestConnectionDataUsage(), or as a periodic update by the VideoProvider. Where periodic updates of data usage are provided, they should be provided at most for every 1 MB of data transferred and no more than once every 10 sec.

Received by the InCallService via InCallService.VideoCall.Callback#onCallDataUsageChanged(long).

Parameters
dataUsage	long: The updated data usage (in bytes). Reported as the cumulative bytes used since the start of the call.