Video Telephony接口和流程梳理
未经允许不能转载
本文内容主要是IMS ThinClient对应用程序公开的api的概述，通过这些api，应用程序可以通过modem进行视频通话，此外，本文仅提供Qualcomm的Android VideoTelephony方案。
第一部分：IMS ThinClient
这部分挑选了部分重要的API接口进行描述
1.initImsThinClient()/initImsThinClient2(unsigned short sessionID)
初始化IMS ThinClient，初始化成功了之后才能接收QMI指令进行更多的操作，返回值如下：
| Return value |
Value |
Description |
| IMS_ERROR_OK |
0 |
初始化成功 |
| IMS_GENERIC_ERROR |
-1 |
初始化失败 |
| IMS_MULTIPLE_INIT |
-2 |
重复初始化 |
该接口是整个VT call的第一步，这两个api的区别在于后者需要传入唯一的sessionID，为应用唯一识别码
2.deInitImsThinClient()
反初始化IMS ThinClient，也就是清空所有数据，关闭ThinClient，这是整个VT流程的最后一步，返回值如下:
| Return value |
Value |
Description |
| IMS_ERROR_OK |
0 |
成功 |
| IMS_GENERIC_ERROR |
-1 |
失败 |
| IMS_NOT_INITIALIZED |
-2 |
反初始化一个未初始化的库 |
3.setFarEndSurface(Surfacefar)
设置farend Surface，让设备可以解码和渲染，播放器可以开始工作，简单来说就是可以播放视频，返回值如下：
| Return value |
Value |
Description |
| IMS_ERROR_OK |
0 |
成功 |
| IMS_GENERIC_ERROR |
-1 |
失败 |
这里附加一个api 文档的流程图：
可以看到最后把surface的句柄传到了播放器，让其渲染，如果有视频过来就可以播放了
4.void registerAppEventCallback2(IMS_EVENT_NOTIFY_CALLBACK2 fnPtr)
注册APP的callback，其中IMS_EVENT_NOTIFY_CALLBACK2 的返回值如下：
| Return value |
Value |
Description |
| PARAM_READY_EVENT |
1 |
录制器的编码集 |
| RECORDER_START_EVENT |
2 |
录制器启动 |
| PLAYER_START_EVENT |
3 |
开始播放视频 |
| PLAYER_STOP_EVENT |
4 |
视频播放器停止 |
| DISP_MODE_EVENT |
5 |
可以在IMS ThinClient获取方向模式 |
| PEER_RESOLUTION_CHANGE_EVENT |
6 |
视频播放过程中有分辨率的变化的时候会有这个事件发出 |
| VIDEO_QUALITY_EVENT |
7 |
修改视频播放质量 |
| VT_RTP_DATA_USAGE_EVENT |
8 |
使用的流量报告 |
| RECORDER_STOP_EVENT |
9 |
录制器停止 |
| RECORDER_FPS_EVENT |
10 |
录制器的帧率变化事件 |
这里先解释一下，为什么这个callback是2，因为在Android L之后，registerAppEventCallback和IMS_EVENT_NOTIFY_CALLBACK就被废弃了，使用了现在这个接口，IMS ThinClient的部分接口需要返回对应的return value才可以使用
如int GetNegotiatedFPS()需要返回PARAM_READY_EVENT才能使用
short getUIOrientationMode()需要返回DISP_MODE_EVENT，具体需要看对应接口的要求
5.short getUIOrientationMode()
获取UI的方向是什么模式的，有如下返回值
| Return value |
Value |
Description |
| LANDSCAPE_MODE |
1 |
横向模式 |
| PORTRAIT_MODE |
2 |
纵向模式 |
| CVO_MODE |
3 |
自适应方向模式 |
当返回是CVO_MODE的时候可以使用如下接口：
6.void setDeviceOrientation(unsigned short rotation)
设置设备的方向，有如下rotation可以传入
| Rotation |
Value |
Description |
| IMS_ROTATION_0 |
0 |
旋转0度 |
| IMS_ROTATION_90 |
1 |
旋转90度 |
| IMS_ROTATION_180 |
2 |
旋转180度 |
| IMS_ROTATION_270 |
3 |
旋转270度 |
接下来是流量相关部分：
7.int requestRtpDataUsage2(int mediaID)
mediaID是区分多个通话的唯一id，该接口是向IMS ThinClient申请RTP 的数据使用情况，返回值如下：
| Return value |
Value |
Description |
| IMS_ERROR_OK |
0 |
请求已经正确发送 |
| IMS_GENERIC_ERROR |
-1 |
在RTP层请求错误 |
请求成功之后才可以获取相关数据，这里附上流程图：
当callback返回VT_RTP_DATA_USAGE_EVENT可以使用如下接口获取所需数据
8.unsigned long getRtpDataUsage2(unsigned short direction, int mediaID)
以及
9.unsigned long getRtpDataUsage3(unsigned short direction, int mediaID, int rat_type)
direction有如下参数
| Direction |
Description |
| 0 |
上行数据 |
| 1 |
下行数据 |
rat_type有如下参数
| Rat type |
Description |
| DATA_USAGE_LTE |
LTE使用的数据情况 |
| DATA_USAGE_WIFI |
Wi-Fi使用的数据情况 |
同样的，这里的接口是带“2”的，也就是Android L及以上的接口
Camera相关
使用Camera的相关方法在Camera2中，这里不做相关描述，只描述IMS ThinClient的Camera相关
10.void setCameraInfo(unsigned short facing,unsigned int mount)
在使用Camera的录像功能开启之前，必须使用这个接口设置是使用前置还是后置摄像头，摄像头旋转的角度这两个参数
| Facing |
Value |
Description |
| BACK_FACING |
0 |
后置摄像头 |
| FRONT_FACING |
1 |
前置摄像头 |
这个接口是MSM8998或者更新的芯片可以使用的，老芯片使用的是：void setCameraFacing(unsigned short facing)，参数如上表
| Mount |
Value |
Description |
| 0 degree |
0 |
不旋转 |
| 90 degree |
90 |
顺时针旋转90度 |
| 180 degree |
180 |
顺时针旋转180度 |
| 270 degree |
270 |
顺时针旋转270度 |
11.int setVideoImageBuffer(int *array, int size,int width, int height)
在VT call期间，应用希望发送静态图片取代视频流使用的接口，参数分别是：
图片的ARGB_8888 格式的bitmap 数组
图片数组的大小
图片的宽
图片的高
使用该接口最好是关闭Camera，当你不想再发送静态图片的时候可以传null关闭这个接口，这个时候就可以再次打开Camera发送视频流了，该接口返回值如下：
| Value |
Description |
| 0 |
成功 |
| -1 |
失败 |
| -2 |
Buffer 的大小和申请的空间不匹配 |
| -3 |
与申请的空间不匹配 |
12.uint32_t getRecorderFrameRate()
获取帧率的接口，获取了FPS之后，使用camere2的setRepeatingBurst()去计算应该跳过的帧数，如GetNegotiatedFPS()获取到是30，此接口获取到是15，那么需要配置camera为录制15 FPS的视频到解码器，跳过其中的15帧
第二部分：一个完整的VT通话的call flow
A）先上流程图，内容有点多，可以放大看：
这个是api文档的原图，解释如下：
这个接口调用流程图讲的是VT app，IMS的VT和Camera接口，以及SL服务层四者的调用关系
由VT app开始，MO（主叫）用户拨号到MT（被叫）用户开始讲起
- MO使用RIL接口拨号给MT，SL进行处理之后，MT接收到通话指示
- MO和MT的初始化IMS thinClient，setFarEndSurface以及注册回调函数registerAppEventCallback2/ registerAppEventCallback，同时使用cameraOpen开启camera
- IMS内部注册camera的回调，也就是IMS VT interface注册IMS Camera interface的callback
- MO接收通话指示（进行中/已连接），MT通过RIL接口应答VT通话
- SL给IMS VT接口发送视频的初始化和配置通知，IMS处理之后通过IMS VT接口通过第2步的回调函数返回了DISP_MODE_EVENT，使得VT app可以获取UI的方向模式（横/竖/自适应）
- 当IMS ThinClient准备完毕，利用2的回调函数返回PARAM_READY_EVENT事件之后，VT app就能从IMS ThinClient获取FPS，宽，高等内容
- VT app通过IMS Camera接口设置Camera的相关参数，并且启动Camera预览（startCameraPreview）
- 当视频解码器/播放器配置成功之后，IMS ThinClient通过2的回调函数返回PEER_RESOLUTION_CHANGE_EVENT，使得VT app能获取到对等通话方的视频的宽和高，这样便能调整视频的显示，使得显示正常
- 当IMS ThinClient和SL经过一系列请求之后，IMS ThinClient通过2的回调返回RECORDER_START_EVENT（也就是图上的START_READY_EVENT），VT app就可以开始视频的录制了
当播放器开始接收录制的视频的时候，IMS ThinClient通过回调返回PLAYER_START_EVENT，VT app就可以开始播放视频了。
B）在整个通话过程中，会遇到不同的情况，比如旋转手机，结束通话，停止录像之类的，看下图：
- 如果MT旋转屏幕了，MO的VT app接收到PEER_RESOLUTION_CHANGE_EVENT，那么MO就要获取MT的视频宽高，对UI调整，以正确显示视频
- 停止和开始传输视频，都会有对应的事件通知到VT app调整UI或者显示信息
结束通话需要释放camera和反初始化IMS ThinClient（deinitImsThinClient）
第三部分：升级方案和降级方案
升级方案和第二部分A）中的流程图差不多，区别在于通话指令部分的区别，可以看下图：
这是一个VOLTE升级到VT的flow，可以看到在alt框，也就是有一个MODIFY的指令的区别，其余比如升级到VS的就不一一列举了。
降级方案：
降级方案也是比较简单，先看图：
1.VS receive only 降级到VOLTE，VT接收到降级指令，设置视频为null，IMS ThinClient停止播放
2.VS transmit only降级到VOLTE，VT app接收到降级指令之后停止视频录制，IMS ThinClient停止录制视频
3.VT降级到VS transmit only，VT app接收到降级指令，停止播放视频，IMS ThinClient也停止播放和预览，但是还继续发送视频
4.VT降级到VS receive only，VT接收到指令之后，停止camera的预览和录制，并且释放camera，IMS ThinClient接收到停止录制的指令，然后停止录制
5.VT降级到VOLTE，VT接收到指令之后，停止camera，停止播放，IMS ThinClient也是一样的，停止录制，停止播放。
附录：
| Acronym or term |
Definition |
| CVO |
Coordinated video orientation |
| DPL |
Device portability layer |
| Fps |
Frames per second |
| IMS |
IP multimedia subsystem |
| JNI |
Java native interface |
| QMI |
Qualcomm messaging interface |
| QoS |
Quality of service |
| RIL |
Radio interface layer |
| RTP |
Real-Time Transport Protocol |
| SL |
Service layer |
| UE |
User equipment |
| VT |
Videotelephony |
| VoLTE |
Voice over LTE |
| VS |
Video share |