public abstract static class Connection.VideoProvider extends Object
Connection
.
Implementations create a custom subclass of Connection.VideoProvider
and the
ConnectionService
creates an instance sets it on the Connection
using
Connection.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
.
Modifier and Type | Field and Description |
---|---|
static int |
SESSION_EVENT_CAMERA_FAILURE
A camera failure has occurred for the selected camera.
|
static int |
SESSION_EVENT_CAMERA_READY
Issued after
SESSION_EVENT_CAMERA_FAILURE when the camera is once again ready
for operation. |
static int |
SESSION_EVENT_RX_PAUSE
Video is not being received (no protocol pause was issued).
|
static int |
SESSION_EVENT_RX_RESUME
Video reception has resumed after a
SESSION_EVENT_RX_PAUSE . |
static int |
SESSION_EVENT_TX_START
Video transmission has begun.
|
static int |
SESSION_EVENT_TX_STOP
Video transmission has stopped.
|
static int |
SESSION_MODIFY_REQUEST_FAIL
Session modify request failed.
|
static int |
SESSION_MODIFY_REQUEST_INVALID
Session modify request ignored due to invalid parameters.
|
static int |
SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE
Session modify request rejected by remote user.
|
static int |
SESSION_MODIFY_REQUEST_SUCCESS
Session modify request was successful.
|
static int |
SESSION_MODIFY_REQUEST_TIMED_OUT
Session modify request timed out.
|
Constructor and Description |
---|
VideoProvider() |
VideoProvider(Looper looper)
Creates an instance of the
Connection.VideoProvider , specifying the looper to use. |
Modifier and Type | Method and Description |
---|---|
void |
changeCallDataUsage(long dataUsage)
Deprecated.
- Use
setCallDataUsage(long) instead. |
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. |
IVideoProvider |
getInterface()
Returns binder object which can be used across IPC methods.
|
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. |
static String |
sessionEventToString(int event)
Returns a string representation of a call session event.
|
void |
setCallDataUsage(long dataUsage)
Used to inform listening
InCallService implementations when the data usage of the
video associated with the current Connection has changed. |
public static final int SESSION_EVENT_RX_PAUSE
handleCallSessionEvent(int)
,
Constant Field Valuespublic static final int SESSION_EVENT_RX_RESUME
SESSION_EVENT_RX_PAUSE
.handleCallSessionEvent(int)
,
Constant Field Valuespublic static final int SESSION_EVENT_TX_START
handleCallSessionEvent(int)
,
Constant Field Valuespublic static final int SESSION_EVENT_TX_STOP
handleCallSessionEvent(int)
,
Constant Field Valuespublic static final int SESSION_EVENT_CAMERA_FAILURE
InCallService
can use
this as a cue to inform the user the camera is not available.handleCallSessionEvent(int)
,
Constant Field Valuespublic static final int SESSION_EVENT_CAMERA_READY
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.handleCallSessionEvent(int)
,
Constant Field Valuespublic static final int SESSION_MODIFY_REQUEST_SUCCESS
public static final int SESSION_MODIFY_REQUEST_FAIL
public static final int SESSION_MODIFY_REQUEST_INVALID
public static final int SESSION_MODIFY_REQUEST_TIMED_OUT
public static final int SESSION_MODIFY_REQUEST_REJECTED_BY_REMOTE
public VideoProvider()
public VideoProvider(Looper looper)
Connection.VideoProvider
, specifying the looper to use.looper
- The looper.public final IVideoProvider getInterface()
public abstract void onSetCamera(String cameraId)
The Connection.VideoProvider
should respond by communicating the capabilities of the chosen
camera via
changeCameraCapabilities(VideoProfile.CameraCapabilities)
.
Sent from the InCallService
via
InCallService.VideoCall.setCamera(String)
.
cameraId
- The id of the camera (use ids as reported by
CameraManager.getCameraIdList()
).public abstract void onSetPreviewSurface(Surface surface)
Sent from the InCallService
via
InCallService.VideoCall.setPreviewSurface(Surface)
.
surface
- The Surface
.public abstract void onSetDisplaySurface(Surface surface)
Sent from the InCallService
via
InCallService.VideoCall.setDisplaySurface(Surface)
.
surface
- The Surface
.public abstract void onSetDeviceOrientation(int rotation)
Sent from the InCallService
via
InCallService.VideoCall.setDeviceOrientation(int)
.
rotation
- The device orientation, in degrees.public abstract void onSetZoom(float value)
Sent from the InCallService
via InCallService.VideoCall.setZoom(float)
.
value
- The camera zoom ratio.public abstract void onSendSessionModifyRequest(VideoProfile fromProfile, VideoProfile toProfile)
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
InCallService.VideoCall.sendSessionModifyRequest(VideoProfile)
.
fromProfile
- The video profile prior to the request.toProfile
- The video profile with the requested changes made.public abstract void onSendSessionModifyResponse(VideoProfile responseProfile)
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.
responseProfile
- The response video profile.public abstract void onRequestCameraCapabilities()
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
InCallService.VideoCall.requestCameraCapabilities()
.
public abstract void onRequestConnectionDataUsage()
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
InCallService.VideoCall.requestCallDataUsage()
.
public abstract void onSetPauseImage(Uri uri)
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
InCallService.VideoCall.setPauseImage(Uri)
.
uri
- URI of image to display.public void receiveSessionModifyRequest(VideoProfile videoProfile)
InCallService
implementations when the
Connection.VideoProvider
receives a session modification request.
Received by the InCallService
via
InCallService.VideoCall.Callback.onSessionModifyRequestReceived(VideoProfile)
,
videoProfile
- The requested video profile.onSendSessionModifyRequest(VideoProfile, VideoProfile)
public void receiveSessionModifyResponse(int status, VideoProfile requestedProfile, VideoProfile responseProfile)
InCallService
implementations when the
Connection.VideoProvider
receives a response to a session modification request.
Received by the InCallService
via
InCallService.VideoCall.Callback.onSessionModifyResponseReceived(int,
VideoProfile, VideoProfile)
.
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.onSendSessionModifyRequest(VideoProfile, VideoProfile)
public void handleCallSessionEvent(int event)
InCallService
implementations when the
Connection.VideoProvider
reports a call session event.
Received by the InCallService
via
InCallService.VideoCall.Callback.onCallSessionEvent(int)
.
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 void changePeerDimensions(int width, int height)
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)
.
width
- The updated peer video width.height
- The updated peer video height.public void setCallDataUsage(long dataUsage)
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
InCallService.VideoCall.Callback.onCallDataUsageChanged(long)
.
dataUsage
- The updated data usage (in bytes). Reported as the cumulative bytes
used since the start of the call.public void changeCallDataUsage(long dataUsage)
setCallDataUsage(long)
instead.dataUsage
- The updated data usage (in byes).setCallDataUsage(long)
public void changeCameraCapabilities(VideoProfile.CameraCapabilities cameraCapabilities)
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
InCallService.VideoCall.Callback.onCameraCapabilitiesChanged(
VideoProfile.CameraCapabilities)
.
cameraCapabilities
- The new camera capabilities.public void changeVideoQuality(int videoQuality)
InCallService
implementations when the video quality
of the call has changed.
Received by the InCallService
via
InCallService.VideoCall.Callback.onVideoQualityChanged(int)
.
videoQuality
- The updated video quality. Valid values:
VideoProfile.QUALITY_HIGH
,
VideoProfile.QUALITY_MEDIUM
,
VideoProfile.QUALITY_LOW
,
VideoProfile.QUALITY_DEFAULT
.public static String sessionEventToString(int event)
event
- A call session event passed to handleCallSessionEvent(int)
.