Android APIs
public static abstract class

Connection.VideoProvider

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

Class Overview

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

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

The Connection.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 Connection.VideoProvider via InCallService.VideoCall.

Summary

Constants
int SESSION_EVENT_CAMERA_FAILURE A camera failure has occurred for the selected camera.
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
Connection.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 Connection.VideoProvider reports a call session event.
abstract void onRequestCameraCapabilities()
Issues a request to the Connection.VideoProvider to retrieve the camera capabilities.
abstract void onRequestConnectionDataUsage()
Issues a request to the Connection.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 Connection.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 camera zoom ratio.
void receiveSessionModifyRequest(VideoProfile videoProfile)
Used to inform listening InCallService implementations when the Connection.VideoProvider receives a session modification request.
void receiveSessionModifyResponse(int status, VideoProfile requestedProfile, VideoProfile responseProfile)
Used to inform listening InCallService implementations when the Connection.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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int SESSION_EVENT_CAMERA_FAILURE

Added in API level 23

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

See Also
Constant Value: 5 (0x00000005)

public static final int SESSION_EVENT_CAMERA_READY

Added in API level 23

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

See Also
Constant Value: 6 (0x00000006)

public static final int SESSION_EVENT_RX_PAUSE

Added in API level 23

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

See Also
Constant Value: 1 (0x00000001)

public static final int SESSION_EVENT_RX_RESUME

Added in API level 23

Video reception has resumed after a SESSION_EVENT_RX_PAUSE.

See Also
Constant Value: 2 (0x00000002)

public static final int SESSION_EVENT_TX_START

Added in API level 23

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
Constant Value: 3 (0x00000003)

public static final int SESSION_EVENT_TX_STOP

Added in API level 23

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
Constant Value: 4 (0x00000004)

public static final int SESSION_MODIFY_REQUEST_FAIL

Added in API level 23

Session modify request failed.

See Also
Constant Value: 2 (0x00000002)

public static final int SESSION_MODIFY_REQUEST_INVALID

Added in API level 23

Session modify request ignored due to invalid parameters.

See Also
Constant Value: 3 (0x00000003)

public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE

Added in API level 23

Session modify request rejected by remote user.

See Also
Constant Value: 5 (0x00000005)

public static final int SESSION_MODIFY_REQUEST_SUCCESS

Added in API level 23

Session modify request was successful.

See Also
Constant Value: 1 (0x00000001)

public static final int SESSION_MODIFY_REQUEST_TIMED_OUT

Added in API level 23

Session modify request timed out.

See Also
Constant Value: 4 (0x00000004)

Public Constructors

public Connection.VideoProvider ()

Added in API level 23

Public Methods

public void changeCameraCapabilities (VideoProfile.CameraCapabilities cameraCapabilities)

Added in API level 23

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

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

Received by the InCallService via onCameraCapabilitiesChanged(VideoProfile.CameraCapabilities).

Parameters
cameraCapabilities The new camera capabilities.

public void changePeerDimensions (int width, int height)

Added in API level 23

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 onPeerDimensionsChanged(int, int).

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

public void changeVideoQuality (int videoQuality)

Added in API level 23

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

Received by the InCallService via onVideoQualityChanged(int).

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

public void handleCallSessionEvent (int event)

Added in API level 23

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

Received by the InCallService via onCallSessionEvent(int).

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

public abstract void onRequestCameraCapabilities ()

Added in API level 23

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

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

Sent from the InCallService via requestCameraCapabilities().

public abstract void onRequestConnectionDataUsage ()

Added in API level 23

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

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

Sent from the InCallService via requestCallDataUsage().

public abstract void onSendSessionModifyRequest (VideoProfile fromProfile, VideoProfile toProfile)

Added in API level 23

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 Connection.VideoProvider determines a request to be invalid, it should call receiveSessionModifyResponse(int, VideoProfile, VideoProfile) to report the invalid request back to the InCallService.

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

Sent from the InCallService via sendSessionModifyRequest(VideoProfile).

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

public abstract void onSendSessionModifyResponse (VideoProfile responseProfile)

Added in API level 23

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 STATE_AUDIO_ONLY. If the user had decided to accept the request, the video state would be STATE_BIDIRECTIONAL.

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

Parameters
responseProfile The response video profile.

public abstract void onSetCamera (String cameraId)

Added in API level 23

Sets the camera to be used for the outgoing video.

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

Sent from the InCallService via setCamera(String).

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

public abstract void onSetDeviceOrientation (int rotation)

Added in API level 23

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

Sent from the InCallService via setDeviceOrientation(int).

Parameters
rotation The device orientation, in degrees.

public abstract void onSetDisplaySurface (Surface surface)

Added in API level 23

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

Sent from the InCallService via setDisplaySurface(Surface).

Parameters
surface The Surface.

public abstract void onSetPauseImage (Uri uri)

Added in API level 23

Provides the Connection.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 setPauseImage(Uri).

Parameters
uri URI of image to display.

public abstract void onSetPreviewSurface (Surface surface)

Added in API level 23

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 setPreviewSurface(Surface).

Parameters
surface The Surface.

public abstract void onSetZoom (float value)

Added in API level 23

Sets camera zoom ratio.

Sent from the InCallService via setZoom(float).

Parameters
value The camera zoom ratio.

public void receiveSessionModifyRequest (VideoProfile videoProfile)

Added in API level 23

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

Received by the InCallService via onSessionModifyRequestReceived(VideoProfile),

Parameters
videoProfile The requested video profile.
See Also

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

Added in API level 23

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

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

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

public void setCallDataUsage (long dataUsage)

Added in API level 23

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 Connection.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 onCallDataUsageChanged(long).

Parameters
dataUsage The updated data usage (in bytes). Reported as the cumulative bytes used since the start of the call.
Get news & tips
Blog Support

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

Android 6.0 r1 —

About Android Auto TV Wear Legal