Appearance
1. 概述
- 当前android googlecast sdk支持镜像投屏功能，不需要在线访问google服务。
- 支持使用chrome浏览器，Chromebook，Android手机（需支持googlecast）发起镜像投屏。
- 尚不支持youtube应用内投屏。
2. SDK交付物说明
- SDK库（两个AAR文件）：googlecast协议实现，是标准的android模块，供应用集成。
- DEMO源代码：基于SDK的实现android demo参考应用，提供源码。客户可参考此定制实现符合自身需求的应用。
- SDK接口文档：API接口描述文档。
3. API接口
3.1 GoogleCastModule接口
GoogleCastModule接口由上层APP调用，提供初始化模块、停止模块和强制退出投屏的接口。
3.1.1 初始化SDK
java
public int initModule(Context context, Properties paras, ToastLinstener ts)描述
初始化SDK，启动内部的googlecast相关服务。
参数
| 名称 | 描述 |
|---|---|
| context | Android应用上下文 |
| paras | 为SDK初始化属性集合，paras为Properties类型。 通过键值对的方式初始化sdk的参数。参考3.1.1部分详细描述。 |
| userdata | 特定用户对象。根据实际某些定制业务场景设计。 |
paras: 属性, 用于初始化googlecast, 所支持的属性有:
| 属性名 | 描述 | 必填 |
|---|---|---|
| name或BJGooglecastModule.PARA_NAME_DEVICE_NAME | 接收端名称，即在投射端设备上搜索时显示的Airplay接收端的名称。 | 是 |
| BJGooglecastModule.PARA_NAME_DEVICE_ID | 设备uuid标识符, 举例: fb40bc4b-1ef8-4e97-839f-b4a9cf8e5c10，用户应用生成并初始化，要求保持唯一性。 | 是 |
| secretkey | license Key，为使用必捷授权申请库或者申请工具申请的license授权。sdk内部会对此进行授权和校验。 | 是 |
| license_check_token | 由必捷分配，用于初始化SDK的license校验和包名认证，防止被他人盗用。 | 是 |
| license_check_pass | 由必捷分配，用于初始化SDK的license校验密码，防止盗用。 | 是 |
| BJGooglecastModule.PARA_NAME_GOOGLECAST_LATESTINFO | 投屏sdk需要的最新信息（需要在线获取）仅当需要支持android mirror/android youtube投屏时需要，1.0.36版本新增 | 否 |
| BJGooglecastModule.PARA_NAME_ENABLE_MUTI_SESSSION | 是否支持多路投屏，1:支持 0:不支持。默认为1。 | 否 |
返回值
0表示成功，其它表示初始化失败。
| 返回值 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 失败，常见端口绑定失败 |
| license授权错误码说明 | license授权相关的失败错误码请参考3.4节。 |
3.1.2 设置客户定制的模块实现类
java
public void setImp(ModuleImpItf imp)描述
设置用户自定义的模块接口实现实例。具体请参考3.2部分的接口。
参数
imp:用户实现的ModuleImpItf接口实例。具体请参考3.2部分的接口。
调用示例
请参考Demo部分代码。
3.1.3 强制中断投屏会话
java
public void kickOut(MediaChannel channel)描述
用于用户强制结束某个投屏会话。
参数
channel: 为ModuleImpItf reqMediaChannel创建的对应会话。
注意事项
kickOut函数的调用不能在SDK的回调接口调用，容易导致死锁。建议用户异步起一个子线程调用。具体请参考Demo源码中的调用示例。
3.1.4 更新设备名称
java
public int rename(String name)描述
接收端动态更新设备名称时调用。
参数
name: 接收端设备的名称。
注意事项
1.0.36版本开始支持。
3.1.5 停用googlecast功能
java
public void disable()描述
停用googlecast模块，外部用户无法发现接收端，也无法投屏成功。
当用户需要实时开关googlecast功能时可以调用disable/enable接口。
注意事项
1.0.36版本开始支持。
3.1.6 启用googlecast功能
java
public void enable()描述
启用googlecast模块。在调用disable后要恢复启用，则调用enable。
当用户需要实时开关googlecast功能时可以调用disable/enable接口。
注意事项
1.0.36版本开始支持。
3.1.7 更新投屏信息（支持youtube和android镜像需要调用）
java
public void UpdateLatestGoogleCastInfo(String info)描述
更新最新的投屏信息，需要对接在线服务申请获取。
若用户不需要支持Android手机投屏，不需要关注该接口。
注意事项
1.0.36版本开始支持。
3.2 ModuleImpItf接口说明
ModuleImpItf定义了一个接口类，需要用户去实现这些接口。SDK内部会回调ModuleImpItf中的相应接口。
3.2.1 会话接入接口
java
public MediaChannel reqMediaChannel(MediaChannelInfo channelInfo,UserInfo userInfo)描述
这是一个回调接口，由用户重载实现。
当SDK内部发现有会话接入时，SDK内部会主动调用此接口，需要在客户自身的ModuleItf实现类中去实现该接口，返回一个MediaChannel实例，后续sdk会通过MediaChannel接口反馈投屏会话信息。
参数
| 名称 | 描述 |
|---|---|
| channelInfo | 描述了投屏的类型、音视频参数等信息。 |
| userInfo | 描述了发射端的IP、设备型号、设备名称等信息 |
返回值
用户创建的自定义的MediaChannel实例对象，用户需按照3.3部分的接口实现自己的MediaChannel类，在此接口中创建对应的实例。
若返回null, sdk内部会自动断开此次投屏会话，当用户拒绝此次投屏或其它原因不允许投屏接入时，可直接返回null。
调用示例
请参考demo源码中的处理。
注意事项
若此接口返回null, sdk内部会自动断开此次投屏会话，当用户拒绝此次投屏或其它原因不允许投屏接入时，可直接返回null。
3.2.2 会话结束接口
java
public void relMediaChannel(MediaChannel channel)描述
这是一个回调接口，由用户重载实现。
当SDK内部收到会话结束时，SDK内部会主动调用此接口，需要在客户自身的ModuleItf实现类中去实现该接口，用户需要释放MediaChannel相关的资源。
参数
| 名称 | 描述 |
|---|---|
| channel | reqMediaChannel返回的MediaChannel实例 |
调用示例
具体实现可参考DEMO源代码。
3.2.3 事件通知接口
1.0.36新增接口
java
public void onEvent(int eventCode)描述
这是一个回调接口，由用户重载实现。
SDK内部通知应用某个事件发生，应用需要针对该事件进行处理。
参数
eventCode： 事件类型。 当前支持的事件有： BJGooglecastModule.EVENT_GOOGLECAST_LATESTINFO_EXPIRED，表示最近的GoogleCastInfo过期，应用需要在线申请。参考demo的实现。
注意事项
1.0.36版本开始支持。
3.3 MediaChannel会话处理接口
MediaChannel是一个媒体播放通道，其唯一对应一个投屏会话。
当会话建立成功后，协议栈会调用MediaChannel类中的相应接口回吐数据或者获取状态。以下接口需要在MediaChannel子类中实现，客户需要根据自身实际情况实现下列接口。
MediaChannel子类中重要的接口如下,接收端需要重点关注以下接口。
3.3.1 设置播放Surface
java
public void setSurface(Surface surface)描述
设置当前MediaChannel关联的显示相关的Surface，视频将显示到该Surface。该Surface来自用户用于显示视频的view。
参数
surface: 显示相关的Surface，通常来自用户用于显示视频的view。
调用示例
参考Demo中的实现。
3.3.2 音频数据回调接口
java
public abstract void onAudioFrame(byte[] buffer,int len,long ts);描述
镜像音频数据回调接口，音频是OPUS或AAC格式的数据，用户需要实现对音频数据的播放处理功能。
参数
| 名称 | 描述 |
|---|---|
| buffer | 音频数据数组,byte[]类型 |
| len | 数据块长度 |
| ts | 时间戳，时间戳单位为1/1000000秒 |
调用示例
参考Demo中的实现。
3.3.3 视频数据回调接口
java
public void onVideoFrame(byte[] buffer,int len,long ts)描述
镜像视频数据接口，该接口中吐出的是H264或VP8的视频数据，用户需要进行解码并播放。
参数
| 名称 | 描述 |
|---|---|
| buffer | 视频数据数组 |
| len | 数据块长度 |
| ts | 时间戳，时间戳单位为1/1000000秒 |
返回值
无
调用示例
具体实现可以参考SDK中DEMO源代码中GeneralScreenRenderChannel类的实现。
3.4 License授权校验错误码说明
| 错误码值 | 说明 |
|---|---|
| 801 | 输入deviceId 无效 |
| 802 | proGuardSalt输入无效 |
| 803 | proGuardMode输入无效 |
| 804 | 服务器返回值为空(请检查网络是否正常) |
| 810 | 获取本地 deviceId 地址失败 |
| 811 | 输入的deviceId无法通过验证（请检查本地设备初始化是否正常） |
| 812 | license 申请结果异常, 请检查网络状态 |
| 1001 | license_check_token校验失败，包名不匹配 |
| 1002 | license_check_token校验失败 |
| 1003 | license_check_pass密码校验失败 |
| 1004 | license_check_token校验失败，非法的校验类型 |
| -101 | 无法获取deviceId |
| -102 | 无法获取硬件信息 |
| -103 | 检验deviceId失败 |
| -104 | 校验硬件信息失败 |
| -105 | SDK类型不一致 |
| -106 | 授权（license Key）已过期 |
| -107 | 无法解析license |
| -108 | license Key解析错误, 请检查 license 是否读取成功,申请license过程是否出现异常 |
| -109 | license Key为空 |
| -110 | 平台类型不匹配(SDK用于windows, android平台必须匹配) |
| -111 | productId不匹配 |
4. 用户集成说明
4.1 混淆规则
-keepclasseswithmembernames class * {
native <methods>;
}
-keep class com.bjnet.googlecast.* { *; }
-keep class com.bjnet.cbox.module.* { *; }
-keep class com.bjnet.cbox.util.Log { *; }.4.2 Demo源码简要说明
Demo中GoogleCastModuleImp实现了ModuleImpItf接口，实现了reqMediaChannel,relMediaChannel方法，此处可以控制是否接入某个会话的逻辑控制(如最大接入2路这样的控制)。其中reqMediaChannel中创建了与会话类型对应的MediaChannel实现(参考GeneralScreenRenderChannel类)，并启动播放相关的View，创建用于播放的Surface。