萤石开放平台SDK-Android开发文档

1、萤石云视频Android SDK接口使用说明合作伙伴交流使用版本日期修改人修改原因3.02015-10-15夏兴锁SDK大版本重构3.12015-12-05夏兴锁1 UI改版2增添广场接口3.22016-01-13夏兴锁增加设备操作/留言/等相关接口3.32016-01-28夏兴锁1,增加A1 探测器接口2,修正版本升级界面bug3,播放时给出终端绑定错误码1200314,修正其他bug特别说明1：本SDK只包含真机调试的功能，不支持任何模拟器的调试；特别说明2：本SDK提供的功能都已经在文档上说明，任何不在文档上说明的功能不支持，用户可以向我们提需求来完善功能；特别说明3：请频繁查看内容更新

2、，特别是FAQ栏目。1.简介32.名词解释33.功能介绍34.SDK配置35.快速接入示范55.1获取摄像头列表55.2添加设备75.3Wifi一键配置85.4设备预览126.接口146.1SDK整体接入流程146.2SDK初始化156.3登录模块156.4设备模块176.5设备升级246.6报警信息模块246.7留言消息模块256.8SD卡操作276.9录像相关模块286.10设备控制模块296.11EZPlayer模块306.12广场相关接口386.13安全验证接口406.14其他接口416.15实体类426.16EZOpenSDK枚举值44 45 / 451. 简介本文档用于说明萤石开放

3、平台SDK Android版本接口之间的关系以及接口调用顺序，对开放平台SDK Android版本各接口都有详细的说明。主要分为四个部分，第一部分为名词解释;第二部分为SDK环境配置；第三部阐述了开放SDK的主要调用流程;第四部分对各模块接口进行了详细的说明2. 名词解释名词释义accessToken访问令牌，由server返回给client用于认证camerId摄像头唯一标志AppKey应用程序keyAppKey的申请可以参阅deviceSerial设备唯一标志OSD视频当前时间PTZ云台控制，可以通过终端控制操作设备3. 功能介绍V3.0: 授权登录、获取摄像头列表、直播预览、查看回放（S

4、D卡、云存储）、设备添加删除、设备的设置功能（h5）、设备控制接口（云台、镜头画面）、WiFi配置、视频本地录像、视频截屏、报警消息等V3.1: 安全验证接口、获取设置设备验证码、数据解密接口、视频广场相关接口等，主要功能是完成UI版本的开源项目4. SDK配置1. 新建android app工程2. 导入EZOpenSDK.jar（拷贝到libs/下）3. 拷贝lib*.so到libs/armeabi/4. 设置AndroidManifest.xml权限： 应用组件： 用于sdk中间页显示，包含登录、设备添加、设备操作等页面 用于接收网络变化刷新SDK网络状态，接收中间页登录成功消息启动其他

5、界面5. 快速接入示范本节旨在引导开发者进行快速接入，通过介绍几个关键的接口，并给出对应的界面和接口，以及代码范例，让开发者对sdk有个初步了解首先请下载并安装萤石云app, 登陆以后，进入的是监控列表界面，如下所示 图中橙色矩形框仅作为标注，并非原生app界面5.1 获取摄像头列表try List result = null; result = mEZOpenSDK.getCameraList(0, 10); return result; catch (BaseException e) mErrorCode = e.getErrorCode(); return null;说明：通过调用get

6、CameraList，可以得到一个列表，列表每一项包含一个摄像头的信息。开发者可以通过list adapter将列表展示代码位于SrccomvideogouicameralistEZCameraListActivity.java5.2 添加设备说明：需要添加设备时，可以点击界面一中的加号(+)， 进入界面2界面二是一个二维码扫描，用户可以通过扫描二维码获取设备序列号，也可以点击界面右上角的图标(橙色标注)，进入界面3，界面3是一个手动输入序列号界面界面2(二维码扫描)代码在srccomvideogoscanmainCaptureActivity.java界面3(手动输入)代码在srccomvi

7、deogouidevicelist SeriesNumSearchActivity用户输入设备序列号，只有当设备没有被其他人添加，并且设备已经在线(注册上平台)时，才能够被添加，因此，必须要查询一下该设备状态，调用的接口是probeDeviceInfotry mEZProbeDeviceInfo = mEZOpenSDK.probeDeviceInfo(serialNo); sendMessage(MSG_QUERY_CAMERA_SUCCESS); LogULog(TAG, probeDeviceInfo success); catch (BaseException e) s

8、endMessage(MSG_QUERY_CAMERA_FAIL, e.getErrorCode(); LogULog(TAG, probeDeviceInfo fail : + e.getErrorCode(); e.printStackTrace();如果该接口返回成功，则说明该设备状态正常，继续调用addDevice接口添加。try boolean result = mEZOpenSDK.addDevice(mSerialNoStr, mVerifyCode); / 添加成功 sendMessage(MSG_ADD_CAMERA_SUCCESS); catch (Base

9、Exception e) sendMessage(MSG_ADD_CAMERA_FAIL, e.getErrorCode(); LogUtil.errorLog(TAG, add camera fail);如果该接口返回错误，开发者需要处理以下几个错误码，告诉用户该设备不可添加的原因：20020设备在线，已经被自己添加 (给出提示)20022设备在线，已经被别的用户添加 (给出提示)20023设备不在线，未被用户添加 （这里需要调用wifi一键配置）20024设备不在线，已经被别的用户添加 (给出提示)20029设备不在线，已经被自己添加 (给出提示)至此，一个简单的设备添加就完成了5.3 W

10、ifi一键配置在上述调用接口probeDeviceInfo过程中，如果返回的错误码是20023，说明设备还没有联网，这时需要让设备联网，如果是有线设备，需要提示用户插入网线。如果是无线设备，则需要进行wifi配置开始一键配置需要调用startConfigWifi接口new Thread(new Runnable() Override public void run() mEZOpenSDK.startConfigWifi(AutoWifiConnectingActivity.this, wifiSSID, wifiPassword, deviceDiscoveryListener); ).st

11、art();结束一键配置需要调用stopConfigWiFi接口需要传入一个回调函数，用于处理事件DeviceDiscoveryListener deviceDiscoveryListener = new DeviceDiscoveryListener() Override public void onDeviceLost(DeviceInfo deviceInfo) Override public void onDeviceFound(DeviceInfo deviceInfo) Message msg = new Message(); msg.what = 0; msg.obj = dev

12、iceInfo; defiveFindHandler.sendMessage(msg); Override public void onError(String error, int errorCode) LogUtil.errorLog(TAG, error + errorCode: + errorCode); ;Handler defiveFindHandler = new Handler() public void handleMessage(Message msg) if (msg.what = 0) DeviceInfo deviceInfo = (DeviceInfo) msg.o

13、bj; if (deviceInfo = null | deviceInfo.getState() = null) LogUtil.debugLog(TAG, 接收到无效的bonjour信息 为空); return; / 设备序列号 相等 说明是我们要添加的设备 否则不是 if (serialNo != null & serialNo.equals(deviceInfo.getSerialNo() if (WIFI.equals(deviceInfo.getState().name() if (isWifiConnected) LogUtil.i(TAG, defiveFindHandler:

14、 receiver WIFI while isWifiConnected is true); return; isWifiOkBonjourget = true; isWifiConnected = true; LogUtil.debugLog(TAG, 接收到设备连接上wifi信息 + deviceInfo.toString(); t2 = System.currentTimeMillis(); stopWifiConfigOnThread(); changeStatuss(STATUS_REGISTING); else if (PLAT.equals(deviceInfo.getState

15、().name() if (isPlatConnected) LogUtil.i(TAG, defiveFindHandler: receiver PLAT while isPlatConnected is true); return; isPlatBonjourget = true; isPlatConnected = true; LogUtil.debugLog(TAG, 接收到设备连接上PLAT信息 + deviceInfo.toString(); t3 = System.currentTimeMillis(); cancelOvertimeTimer(); changeStatuss(

16、STATUS_ADDING_CAMERA); ;该回调用于处理WIFI和PLAT事件WIFI表示设备已经连上WIFI， PLAT表示设备已经注册上平台。一旦设备注册上平台之后，就可以调用addDevice进行添加5.4 设备预览预览视频的代码参见srccomvideogouirealplayEZRealPlayActivity.java if (mCameraInfo != null) mEZPlayer = mEZOpenSDK.createPlayer(this, mCameraInfo.getCameraId(); if(mEZPlayer = null) return; mEZPlay

17、er.setHandler(mHandler); mEZPlayer.setSurfaceHold(mRealPlaySh); mEZPlayer.startRealPlay();代码说明：1，创建EZPlayer对象需要一个cameraId，即摄像头的唯一id，这个cameraId可从EZCameraInfo对象中获取2，需要创建一个handler,用于接收播放器消息，比如播放器播放成功，失败等消息public boolean handleMessage(Message msg) switch (msg.what) case EZRealPlayConstants.MSG_REALPLAY_

18、PLAY_SUCCESS: handlePlaySuccess(msg); break; case EZRealPlayConstants.MSG_REALPLAY_PLAY_FAIL: handlePlayFail(msg.arg1, msg.arg2); break;3，播放需要一个surfaceView,因此在你的xml layout 文件重要放置一个SurfaceView 在surface创建的过程中，保存SurfaceHolder对象：Overridepublic void surfaceCreated(SurfaceHolder holder) if (mEZPlayer != n

19、ull) mEZPlayer.setSurfaceHold(holder); mRealPlaySh = holder;4， 调用startRealPlay（）整个代码参见srccomvideogouirealplayEZRealPlayActivity.java6. 接口6.1 SDK整体接入流程1. 用户使用SDK初始化后的第一步是通过授权登录(中间页) openLoginPage 获取accessToken的对象，当然用户也可以通过平台与平台的私有云接口获取；2. 通过EZOpenSDK的setAccessToken方法向SDK设置AccessToken; 3. 然后可以通过设备列表接口

20、获取设备信息；4. 针对设备预览、回放、设备操作（云台控制、设备显示设置）、查看报警列表等功能接口调用；5. 预览成功以后才能抓图、录像、开关声音；6. 语音对讲操作；7. 回放成功以后才能抓图、录像、开关声音；8. WiFi配置之前要先通过设备序列号查询设备是否添加过。注意: 开发者调用的主要接口都在EZOpenSDK.java 和 EZPlayer.java这2个类中6.2 SDK初始化程序启动时初始化SDK, 初始化时需要设置AppKey。名称boolean initLib(Application application, String appKey, String loadLibrar

21、yAbsPath)参数param application 客戶端app的 Application 對象param appKey 客戶端app申請的app keyparam loadLibraryAbsPath 指定.so库在sd卡的路径返回值return true 表示成功， false 表示失败版本3.0说明SDK 初始化loadLibraryAbsPath 如果需要将.so文件放在sd卡上，该参数指定路径否则置空表示默认放在手机存储上示例在应用Application的onCreate回调函数中初始化SDK/正式平台设置EZOpenSDK.initLib(this, APP_KEY, nul

22、l); /设置APP_KEY6.3 登录模块说明：1，使用 openLoginPage 方法获取EZAccessToken对象accessToken; 2，把获取的AccessToken字符串通过 setAccessToken 方法对SDK进行accessToken设置；3，用户可以存储accessToken在本地，以便下次启动时直接把accessToken的值设置到SDK6.3.1 打开登陆页名称void openLoginPage()参数返回值void版本3.0说明打开授权登录中间页面登录成功后发送播放com.videogo.action.OAUTH_SUCCESS_ACTION示例在收到

23、OAUTH_SUCCESS_ACTION广播后的代码可以这么写:if(action.equals(Constant.OAUTH_SUCCESS_ACTION) Intent toIntent = new Intent(context, EZCameraListActivity.class); toIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK); /保存token及token超时时间 EZAccessToken token = mEZOpenSdk.getEZAccessToken(); /保存token，获取超时时间，在token过期时重新获取 c

24、ontext.startActivity(toIntent); /启动camera list6.3.2 setAccessToken名称void setAccessToken(String accessToken)参数String accessToken返回值param accessToken 授权登录获取的accessToken版本3.0说明授权登录以后给EZOpenSDK设置AccessToken示例6.3.3 getEZAccessToken名称EZAccessToken getEZAccessToken()参数返回值return token 版本3.0说明获取登录token包含2个字段

25、，一个是token string本身另外一个表示过期时间，单位为秒，获取到的值一般为 604800 秒，即7天。该函数一般在收到登陆成功的广播OAUTH_SUCCESS_ACTION 后调用。示例/保存token，获取超时时间，当token过期时重新登录EZAccessToken token = mEZOpenSdk.getEZAccessToken();6.3.4 登出名称void logout()参数返回值void版本3.0说明登出账号示例6.3.5 获取用户信息名称EZUserInfo getUserInfo()参数返回值return 返回 EZUserInfo 对象throws Bas

26、eExceptionthrows BaseException版本3.2说明获取用户信息；用户信息包含：用户名,头像地址等示例6.3.6 修改密码页面名称void openChangePasswordPage()参数返回值版本3.3说明可以通过该页面修改密码示例6.4 设备模块接口说明：1.通过获取摄像头列表的接口（支持分页），你可以从萤石云服务器获取当前登录账号的设备列表，你可以根把返回的EZCameraInfo的数组在你的UI展示设备，然后你可以通过cameraId进行预览、设备云存储录像或者SD卡录像列表获取等操作；2.通过deviceSerial对摄像头列表中的设备进行删除操作、中间页面

27、设置设备；3添加设备时，先调用getCameraInfo获取摄像头信息，该函数返回值（见函数详细说明 ）会提示摄像头是否已经添加。a) 如果该摄像头已经被添加，则添加流程中止，此时开发者应该提示用户已添加b) 如果摄像头未被添加，则调用无线配置wifiConfig, 并进一步通过addDevice来添加无线设备的添加，demo中有具体的例子。对于有线设备的添加，添加过程跟无线是一样的，先调getCameraInfo查询信息，如果设备没有被添加，则继续调用addDevice添加。只不过没有wifi配置这一步wifi一键配置流程：6.4.1 WiFi配置流程特别说明： 账户下删除设备重新wifi配

28、置并且添加过程中，请在重置设备等待2分钟以后再调用wifi配置的相关接口可以提高wifi配置的成功率，否则会降低成功率，因为重置设备以后我们平台将在2分钟内得到设备下线的状态，只有平台认为下线了，wifi配置成功率才会高。6.4.2 获取摄像头列表名称List getCameraList(int pageStart,int pageSize)throws BaseException参数param pageStart 分页当前页码（从0开始）param pageSize 分页每页数量 (建议20以内)返回值return 摄像头列表throws BaseException 版本3.0说明该接口用于

29、应用获取摄像头列表返回的结构类型可以参阅6.15.1示例6.4.3 获取摄像头信息名称EZCameraInfo getCameraInfo(String deviceSerial)throws BaseException参数param deviceSerial 设备序列号返回值return 摄像头信息throws BaseException版本3.0说明根据设备序列号查询摄像头信息，一般在设备添加WiFi配置之前先作一次查询。调用该函数时，有2种情况：1， 用户已经添加过该摄像头，那么该调用正常会返回EZCameraInfo2， 用户没有添加过该摄像头，比如第一次添加设备时，那么该调用返回如下

30、结果，获得的EZCameraInfo信息为空(因为添加之前，该摄像头还不属于你，所以会返回空)，同时抛出以下异常，开发者根据具体的异常决定进一步的流程:VIDEOGONETSDK_DEVICE_NOT_ONLINE:设备不在线，继续走添加流程。ERROR_WEB_DIVICE_ONLINE_NOT_ADD：在线未添加，继续走添加流程。ERROR_WEB_DIVICE_OFFLINE_NOT_ADD：不在线未添加，继续走添加流程。示例6.4.4 获取设备信息名称EZDeviceInfo getDeviceInfo(String cameraId)throws BaseException参数par

31、am cameraId 设备摄像头id返回值return 设备信息throws BaseException版本3.0说明获取设备详细信息示例 删除设备名称boolean deleteDevice(String deviceSerial)throws BaseException参数param deviceSerial 设备标志返回值return true 表示成功， false 表示失败throws BaseException版本3.0说明删除当前账号的设备示例6.4.5 openSettingDevicePage名称void openSettingDevicePage(Strin

32、g deviceSerial)参数param deviceSerial设备标志(列表接口返回的deviceSerial)返回值void版本3.0说明打开设备设置中间页示例6.4.6 添加设备名称boolean addDevice(String deviceSerial, String deviceCode) throws BaseException参数param deviceSerial 设备序列号param deviceCode 设备验证码返回值return true 表示成功， false 表示失败throws BaseException版本3.0说明添加设备示例6.4.7 startCo

33、nfigWiFi名称boolean startConfigWifi(Context context,String ssid, String password, DeviceDiscoveryListener l)参数param ssid 连接WiFi SSIDparam password 连接WiFi 密码param l 回调，用于处理连接设备的WiFi配置状态返回值return true 表示成功， false 表示失败版本3.0说明开始WiFi配置6.4.8 stopConfigWiFi名称boolean stopConfigWiFi()参数返回值return true 表示成功， fal

34、se 表示失败版本3.0说明停止Wifi配置示例6.4.9 尝试查询设备信息名称EZProbeDeviceInfo probeDeviceInfo(String deviceSerial)参数param deviceSerial 需要查询的设备序列号返回值return 返回 EZProbeDeviceInfo 对象，包含设备简单信息，用于添加目的throws BaseException版本3.2说明尝试查询设备信息（用于添加设备之前, 简单查询设备信息，如是否在线，是否添加等）示例6.4.10 开启布防(活动检测)名称boolean setDefence(boolean isDefence,S

35、tring deviceSerial)参数返回值return true 表示成功， false 表示失败throws BaseException版本3.2说明根据设备序列号控制设备的活动检测开关接口示例6.4.11 抓取摄像头图片名称String capturePicture(String deviceSerial,int channelNo)参数param deviceSerial 设备序列号param channelNo 通道号返回值return 图片urlthrows BaseException版本3.2说明获取抓取摄像头图片的url示例6.4.12 获取设备的版本信息名称EZDevic

36、eVersion getDeviceVersion(String deviceSerial)参数param deviceSerial 设备序列号返回值return 版本号EZDeviceVersion对象throws BaseException版本3.2说明获取设备的版本信息示例6.4.13 视频图片加解密名称boolean setDeviceEncryptStatus(boolean isEncrypt,String deviceSerial,String smsCode)参数param isEncrypt 是否加密param deviceSerial 设备序列号param smsCode

37、定手机号收到的设备操作短信验证码返回值return true 表示成功， false 表示失败throws BaseException版本3.2说明设备视频图片加解密开关接口示例6.4.14 修改设备名称名称boolean setDeviceName(String deviceSerial,String deviceName)参数param deviceSerial 设备序列号param deviceName 设备名称返回值return true 表示成功， false 表示失败throws BaseException版本3.2说明修改设备名称接口示例6.4.15 通过序列号获取设备信息名称E

38、ZDeviceInfo getDeviceInfoBySerial(String deviceSerial)参数param deviceSerial 设备序列号返回值return 设备信息throws BaseException版本3.2说明获取设备详细信息示例6.4.16 打开云存储页面名称void openCloudPage(String deviceSerial)参数param deviceSerial 设备序列号返回值throws BaseException版本3.2说明打开云存储页面示例6.4.17 获取设备列表名称List getDeviceList(int pageIndex,

39、int pageSize)参数param pageIndex 分页起始页，从0开始param pageSize 分页每页数量（建议20以内）返回值return 设备列表throws BaseException版本3.3说明获取用户的设备列表，返回EZDeviceInfo的对象数组示例6.4.18 根据序列号获取探测器列表名称List getDetectorList(String deviceSerial)参数param deviceSerial 设备序列号返回值return 探测器列表throws BaseException版本3.3说明根据设备序列号获取设备关联的探测器列表示例6.4.19

40、设备设置布防状态，兼容A1和IPC设备的布防名称Void setDeviceDefence(String deviceSerial, int defence)参数param deviceSerial 设备序列号param defence 布防状态, IPC布防状态只有0和1，A1有0:睡眠 8:在家 16:外出返回值throws BaseException版本3.3说明设备设置布防状态，兼容A1和IPC设备的布防示例6.4.20 根据序列号获取报警列表名称List getAlarmListBySerial(String deviceSerial,int pageIndex,int pageSi

41、ze,Calendar beginTime,Calendar endTime)参数param deviceSerial 设备序列号param pageIndex 分页当前页码（从0开始）param pageSize 分页每页数量（建议20以内）param beginTime 搜索时间范围开始时间param endTime 搜索时间范围结束时间返回值return EZAlarmInfo对象列表throws BaseException版本3.3说明根据设备序列号获取报警信息列表，序列号为null时查询整个账户下的报警信息列表示例6.5 设备升级6.5.1 获取设备升级状态名称EZDeviceUpg

42、radeStatus getDeviceUpgradeStatus(String deviceSerial)参数param deviceSerial 设备序列号返回值return EZDeviceUpgradeStatus 返回升级状态，包含升级进度等throws BaseException版本3.2说明获取设备升级状态示例6.5.2 开始升级设备名称void upgradeDevice(String deviceSerial)参数param deviceSerial 设备序列号返回值throws BaseException版本3.2说明开始升级设备示例6.6 报警信息模块6.6.1 获取报警

43、信息列表名称List getAlarmList(String cameraID, int pageStart, int pageSize,Calendar startTime, Calendar endTime) throws BaseException参数param cameraID 设备摄像头idparam pageStart 分页当前页码（从0开始）param pageSize 分页每页数量（建议20以内）param startTime 搜索时间范围开始时间param endTime 搜索时间范围结束时间返回值return 报警信息列表 throws BaseException版本3.0说明获取指定设备的报警信息列表示例6.6.2 设置报警条目状态名称boolean setAlarmStatus(List alarmIdList,EZAlarmStatus alarmStatus)throws BaseException参数param alarmIdList 报警信息Id数组(可以只有一个Id)param alarmStatus 报警状态,已读返回值