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 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.
Constants | |
|---|---|
int |
SESSION_EVENT_CAMERA_FAILURE
A camera failure has occurred for the selected camera. |
int |
SESSION_EVENT_CAMERA_READY
Issued after |
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 |
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 |
void
|
changePeerDimensions(int width, int height)
Used to inform listening |
void
|
changeVideoQuality(int videoQuality)
Used to inform listening |
void
|
handleCallSessionEvent(int event)
Used to inform listening |
abstract
void
|
onRequestCameraCapabilities()
Issues a request to the |
abstract
void
|
onRequestConnectionDataUsage()
Issues a request to the |
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 |
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 |
void
|
receiveSessionModifyResponse(int status, VideoProfile requestedProfile, VideoProfile responseProfile)
Used to inform listening |
void
|
setCallDataUsage(long dataUsage)
Used to inform listening |
Inherited methods | |
|---|---|
 From
class
java.lang.Object
| |
int SESSION_EVENT_CAMERA_FAILURE
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)
int SESSION_EVENT_CAMERA_READY
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)
int SESSION_EVENT_RX_PAUSE
Video is not being received (no protocol pause was issued).
See also:
Constant Value: 1 (0x00000001)
int SESSION_EVENT_RX_RESUME
Video reception has resumed after a SESSION_EVENT_RX_PAUSE.
See also:
Constant Value: 2 (0x00000002)
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:
Constant Value: 3 (0x00000003)
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:
Constant Value: 4 (0x00000004)
int SESSION_MODIFY_REQUEST_FAIL
Session modify request failed.
Constant Value: 2 (0x00000002)
int SESSION_MODIFY_REQUEST_INVALID
Session modify request ignored due to invalid parameters.
Constant Value: 3 (0x00000003)
int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE
Session modify request rejected by remote user.
Constant Value: 5 (0x00000005)
int SESSION_MODIFY_REQUEST_SUCCESS
Session modify request was successful.
Constant Value: 1 (0x00000001)
int SESSION_MODIFY_REQUEST_TIMED_OUT
Session modify request timed out.
Constant Value: 4 (0x00000004)
void changeCameraCapabilities (VideoProfile.CameraCapabilities cameraCapabilities)
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 |
VideoProfile.CameraCapabilities:
The new camera capabilities.
|
Developers
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
onPeerDimensionsChanged(int, int).
| Parameters | |
|---|---|
width |
int:
The updated peer video width. |
height |
int:
The updated peer video height.
|
void changeVideoQuality (int videoQuality)
Used to inform listening InCallService implementations when the video quality
of the call has changed.
Received by the InCallService via
onVideoQualityChanged(int).
| Parameters | |
|---|---|
videoQuality |
int:
The updated video quality. Valid values:
QUALITY_HIGH,
QUALITY_MEDIUM,
QUALITY_LOW,
QUALITY_DEFAULT.
|
void handleCallSessionEvent (int event)
Used to inform listening InCallService implementations when the
Connection.VideoProvider reports a call session event.
Received by the InCallService via
onCallSessionEvent(int).
| Parameters | |
|---|---|
event |
int:
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.
|
void onRequestCameraCapabilities ()
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().
void onRequestConnectionDataUsage ()
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().
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 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 |
VideoProfile:
The video profile prior to the request. |
toProfile |
VideoProfile:
The video profile with the requested changes made.
|
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
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 |
VideoProfile:
The response video profile.
|
void onSetCamera (String cameraId)
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 |
String:
The id of the camera (use ids as reported by
getCameraIdList()).
|
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
setDeviceOrientation(int).
| Parameters | |
|---|---|
rotation |
int:
The device orientation, in degrees.
|
void onSetDisplaySurface (Surface surface)
Sets the surface to be used for displaying the video received from the remote device.
Sent from the InCallService via
setDisplaySurface(Surface).
| Parameters | |
|---|---|
surface |
Surface:
The Surface.
|
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.
Sent from the InCallService via
setPauseImage(Uri).
| Parameters | |
|---|---|
uri |
Uri:
URI of image to display.
|
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
setPreviewSurface(Surface).
| Parameters | |
|---|---|
surface |
Surface:
The Surface.
|
void onSetZoom (float value)
Sets camera zoom ratio.
Sent from the InCallService via setZoom(float).
| Parameters | |
|---|---|
value |
float:
The camera zoom ratio.
|
void receiveSessionModifyRequest (VideoProfile videoProfile)
Used to inform listening InCallService implementations when the
Connection.VideoProvider receives a session modification request.
Received by the InCallService via
onSessionModifyRequestReceived(VideoProfile),
| Parameters | |
|---|---|
videoProfile |
VideoProfile:
The requested video profile. |
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.
Received by the InCallService via
onSessionModifyResponseReceived(int, VideoProfile, VideoProfile).
| Parameters | |
|---|---|
status |
int:
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 |
VideoProfile:
The original request which was sent to the peer device. |
responseProfile |
VideoProfile:
The actual profile changes agreed to by the peer device. |
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
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 |
long:
The updated data usage (in bytes). Reported as the cumulative bytes
used since the start of the call.
|