萤石云视频Android SDK接口使用说明

1. 简介

本文档用于说明萤石开放平台SDK Android版本接口之间的关系以及接口调用顺序，对开放平台SDK Android版本各接口都有详细的说明。主要分为四个部分，第一部分为名词解释;第二部分为SDK环境配置；第三部阐述了开放SDK的主要调用流程;第四部分对各模块接口进行了详细的说明。

2. 名词解释

3. 功能介绍

V3.0: 账号对接(授权登录、sdk接口登录)、获取摄像头列表、直播预览、查看回放（SD卡、云存储）、设备添加删除、设备的设置功能（h5）、设备控制接口（云台、镜头画面）、WiFi配置、视频本地录像、视频截屏、告警消息等。

V3.1: 安全验证接口、获取设置设备验证码、数据解密接口等，主要功能是完成UI版本的开源项目。

4. SDK配置

1、新建android app工程

2、导入EZOpenSDK.jar（拷贝到libs/下）

3、拷贝lib*.so到libs/armeabi/

4、设置AndroidManifest.xml

权限：

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_OWNER_DATA" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.READ_LOGS" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    <uses-permission android:name="android.permission.CHANGE_CONFIGURATION" />

应用组件： 用于sdk中间页显示，包含登录、开通云存储等。

    <activity
        android:name="com.videogo.main.EzvizWebViewActivity"
        android:screenOrientation="portrait"
        android:configChanges="orientation|keyboardHidden"
    </activity>

用于接收网络变化刷新SDK网络状态，接收中间页登录成功消息启动其他界面。

   <receiver
       android:name=".EzvizBroadcastReceiver"
       android:exported="false" >
       <intent-filter>
            <action android:name="com.videogo.action.OAUTH_SUCCESS_ACTION" />
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        </intent-filter>
   </receiver>

5. 快速接入示范

本节旨在引导开发者进行快速接入，通过介绍几个关键的接口，并给出对应的界面和接口，以及代码范例，让开发者对sdk有个初步了解. 首先请下载并安装萤石云app, 登陆以后，进入的是监控列表界面，如下所示 [图中橙色矩形框仅作为标注，并非原生app界面]。

5.1 获取摄像头列表

new Thread(new Runnable() {
    @Override
    public void run() {
        try {
            List<EZCameraInfo> result = null;

            result = mEZOpenSDK.getCameraList(0, 10);

            return result;
        } catch (BaseException e) {
            mErrorCode = e.getErrorCode();
            return null;
        }
    }
}).start();

说明：通过调用getCameraList(接口中包含网络操作，需要在线程中调用)，可以得到一个列表，列表每一项包含一个摄像头的信息。开发者可以通过list adapter将列表展示

代码位于src\com\videogo\ui\cameralist\EZCameraListActivity.java

5.2 添加设备

说明：需要添加设备时，可以点击界面1中的加号(+)，进入界面2，界面2是一个二维码扫描，用户可以通过扫描二维码获取设备序列号，也可以点击界面右上角的图标(橙色标注)，进入界面3，界面3是一个手动输入序列号界面。

界面2(二维码扫描)代码在src\com\videogo\scan\main\CaptureActivity.java

界面3(手动输入)代码在src\com\videogo\ui\devicelist\ SeriesNumSearchActivity

用户输入设备序列号，只有当设备没有被其他人添加，并且设备已经在线(注册上平台)时，才能够被添加，因此，必须要查询一下该设备状态，调用的接口是probeDeviceInfo

try {
    mEZProbeDeviceInfo = mEZOpenSDK.probeDeviceInfo(serialNo);
    sendMessage(MSG_QUERY_CAMERA_SUCCESS);
    LogUtil.infoLog(TAG, "probeDeviceInfo success");
} catch (BaseException e) {
    sendMessage(MSG_QUERY_CAMERA_FAIL, e.getErrorCode());
    LogUtil.infoLog(TAG, " probeDeviceInfo fail :" + e.getErrorCode());
    e.printStackTrace();
}

如果该接口返回成功，则说明该设备状态正常，继续调用addDevice接口添加。

try {
boolean result = mEZOpenSDK.addDevice(mSerialNoStr, mVerifyCode);
        // 添加成功
        sendMessage(MSG_ADD_CAMERA_SUCCESS);
    } catch (BaseException e) {
        sendMessage(MSG_ADD_CAMERA_FAIL, e.getErrorCode());
        LogUtil.errorLog(TAG, "add camera fail");
}

如果该接口返回错误，开发者需要处理以下几个错误码，告诉用户该设备不可添加的原因:

20020 设备在线，已经被自己添加 (给出提示)

20022 设备在线，已经被别的用户添加 (给出提示)

20023 设备不在线，未被用户添加 （这里需要调用wifi一键配置）

20024 设备不在线，已经被别的用户添加 (给出提示)

20029 设备不在线，已经被自己添加 (给出提示)

至此，一个简单的设备添加就完成了。

5.3 Wifi一键配置

在上述调用接口probeDeviceInfo过程中，如果返回的错误码是20023，说明设备还没有联网，这时需要让设备联网，如果是有线设备，需要提示用户插入网线。如果是无线设备，则需要进行wifi配置。

开始一键配置需要调用startConfigWifi接口：

new Thread(new Runnable() {

    @Override
    public void run() {
        mEZOpenSDK.startConfigWifi(AutoWifiConnectingActivity.this, wifiSSID, wifiPassword, deviceDiscoveryListener);
    }
}).start();

结束一键配置需要调用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 = deviceInfo;
        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.obj;
            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: 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().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(STATUS_ADDING_CAMERA);
                }
            }
        }
    };
};

该回调用于处理WIFI和PLAT事件。

WIFI表示设备已经连上WIFI， PLAT表示设备已经注册上平台。一旦设备注册上平台之后，就可以调用addDevice进行添加

5.4 设备预览

预览视频的代码参见src\com\videogo\ui\realplay\EZRealPlayActivity.java

if (mCameraInfo != null) {

    mEZPlayer = mEZOpenSDK.createPlayer(this, mCameraInfo.getCameraId());
    if(mEZPlayer == null)
        return;
    mEZPlayer.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_PLAY_SUCCESS:
            handlePlaySuccess(msg);
            break;
        case EZRealPlayConstants.MSG_REALPLAY_PLAY_FAIL:
            handlePlayFail(msg.arg1, msg.arg2);
            break;
}

3、播放需要一个surfaceView,因此在你的xml layout 文件重要放置一个SurfaceView

<RelativeLayout
    android:id="@+id/realplay_play_rl"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="center"
    android:background="@color/black_bg" >

    <SurfaceView
       android:id="@+id/realplay_sv"
       android:layout_width="600dp"
       android:layout_height="200dp"
       android:layout_alignParentTop="true"
       android:layout_centerInParent="false"
       android:background="@android:color/transparent" />
</RelativeLayout>

在surface创建的过程中，保存SurfaceHolder对象：

@Override
public void surfaceCreated(SurfaceHolder holder) {
    if (mEZPlayer != null) {
        mEZPlayer.setSurfaceHold(holder);
    }
    mRealPlaySh = holder;
}

4、调用startRealPlay（）

整个代码参见src\com\videogo\ui\realplay\EZRealPlayActivity.java

6. 接口

6.1 SDK整体接入流程

1. 用户使用SDK初始化后的第一步通过账号对接流程(参考http://service.ys7.com/question/answer.html?id=21222&user_type=0&selected_type=热门问题考) 获取accessToken的对象
2. 通过EZOpenSDK的setAccessToken方法向SDK设置AccessToken;
3. 然后可以通过设备列表接口获取设备信息；
4. 针对设备预览、回放、设备操作（云台控制、设备显示设置）、查看告警列表等功能接口调用；
5. 预览成功以后才能抓图、录像、开关声音；
6. 语音对讲操作；
7. 回放成功以后才能抓图、录像、开关声音；
8. WiFi配置之前要先通过设备序列号查询设备是否添加过。

注意: 开发者调用的主要接口都在EZOpenSDK.java 和 EZPlayer.java这2个类中

6.2 SDK初始化

6.3 账号对接模块

说明：

1、使用 openLoginPage 方法获取EZAccessToken对象accessToken;

2、把获取的AccessToken字符串通过 setAccessToken 方法对SDK进行accessToken设置;

3、用户可以存储accessToken在本地，以便下次启动时直接把accessToken的值设置到SDK;

4、6.3.1和6.3.2为两种不同的获取用户token方式，可以根据自己的业务选择一个，参考上面6.1.

6.3.1 授权登录-打开登录页，萤石标准

6.3.2 接口登录-调用sdk接口

6.3.2.1 获取开通萤石服务的短信

6.3.2.2 开通萤石服务

6.3.2 setAccessToken

6.3.3 getEZAccessToken

6.3.4 登出

6.3.5 获取用户信息

6.3.6 修改密码页面

6.4 设备模块

接口说明：

1. 通过获取摄像头列表的接口（支持分页），你可以从萤石云服务器获取当前登录账号的设备列表，你可以根把返回的EZCameraInfo的数组在你的UI展示设备，然后你可以通过cameraId进行预览、设备云存储录像或者SD卡录像列表获取等操作；
2. 通过deviceSerial对摄像头列表中的设备进行删除操作、中间页面设置设备；
3. 添加设备时，先调用getCameraInfo获取摄像头信息，该函数返回值（见函数详细说明 ）会提示摄像头是否已经添加。
   a) 如果该摄像头已经被添加，则添加流程中止，此时开发者应该提示用户已添加
   b) 如果摄像头未被添加，则调用无线配置wifiConfig, 并进一步通过addDevice来添加 无线设备的添加，demo中有具体的例子。

对于有线设备的添加，添加过程跟无线是一样的，先调getCameraInfo查询信息，如果设备没有被添加，则继续调用addDevice添加。只不过没有wifi配置这一步。

6.4.2 WiFi一键配置流程

特别说明： 账户下删除设备重新wifi配置并且添加过程中，请在重置设备等待2分钟以后再调用wifi配置的相关接口可以提高wifi配置的成功率，否则会降低成功率，因为重置设备以后我们平台将在2分钟内得到设备下线的状态，只有平台认为下线了，wifi配置成功率才会高。

6.4.3 获取摄像头列表

6.4.4 获取摄像头信息

6.4.5 获取设备信息

6.4.5.2 删除设备

6.4.6 openSettingDevicePage

6.4.7 添加设备

6.4.8 startConfigWiFi

6.4.9 stopConfigWiFi

6.4.10 尝试查询设备信息

6.4.11 开启布防(活动检测)

6.4.12 抓取摄像头图片

6.4.13 获取设备的版本信息

6.4.14 设置摄像机视频是否加密

6.4.15 修改设备名称

6.4.16 通过序列号获取设备信息

6.4.17 打开云存储页面

6.4.18 获取设备列表

6.4.19 根据序列号获取探测器列表

6.4.20 设备设置布防状态，兼容A1和IPC设备的布防

6.4.21 根据序列号获取告警列表

6.5 设备升级

6.5.2 获取设备升级状态

6.5.3 开始升级设备

6.6 告警信息模块

6.6.2 获取告警信息列表

6.6.3 设置告警条目状态

6.6.4 删除告警信息

6.7 留言消息模块

6.7.2 获取未读消息数

6.7.3 获取留言消息列表

6.7.4 批量设置留言消息已读

6.7.5 批量删除留言消息

6.7.6 获取语音留言数据

6.8 SD卡操作

6.8.2 获取存储介质状态

6.8.3 格式化分区(SD卡)

6.9 录像相关模块

6.9.2 搜索云存储录像

6.9.3 搜索SD卡录像

6.10 设备控制模块

接口说明：该接口的主要功能是云台控制和镜头显示功能，属于限制级接口，要优选通过判断设备的能力集来调用，设备能力集请查看EZDeviceInfo对象的属性值来判断

6.10.2 controlPTZ

6.10.3 controlDisplay

6.11 EZPlayer模块

6.11.2 预览流程

参数cameraId是摄像头ID，获取摄像头列表接口获得的数据

获得设备能力 后可通过调用以下函数获取设备一些能力信息：
videoLevel：当前清晰度等级2-高清，1-标清，0-流畅

成功消息：MSG_REALPLAY_PLAY_SUCCESS
失败消息：MSG_REALPLAY_PLAY_FAIL

6.11.3 回放流程

6.11.4 createPlayer

6.11.5 createPlayerWithUrl

6.11.6 releasePlayer

6.11.7 setSurfaceHolder

6.11.8 setHandler

6.11.9 startRealPlay

6.11.10 stopRealPlay

6.11.11 setVideoLevel

6.11.12 capturePicture

Thread thr = new Thread() {
    @Override
    public void run() {
        Bitmap bmp = mEZMediaPlayer.capturePicture();
        FileOutputStream fos = null;
        if(bmp != null) {
            try {
                fos = new FileOutputStream("/sdcard/video_snapshots.jpg");
                bmp.compress(CompressFormat.JPEG, 100, fos);
                bmp.recycle();
                bmp = null;
            } catch (FileNotFoundException e) {
                e.printStackTrace();
            } finally {
                if(fos != null) {
                    try {
                        fos.close();
                    } catch (IOException e) {
                        e.printStackTrace();
                    }
                }
            }
        }
        super.run();
    }};
thr.start();

6.11.13 openSound

6.11.14 closeSound

6.11.15 getOSDTime

6.11.16 startVoiceTalk

6.11.17 stopVoiceTalk

6.11.18 setVoiceTalkStatus

6.11.19 startLocalRecordWithFile

6.11.20 stopLocalRecord

6.11.21 startPlayback

6.11.22 startPlayback

6.11.23 stopPlayback

6.11.24 pausePlayback

6.11.25 resumePlayback

6.11.26 setDisplayRegion

6.12 安全验证接口

6.12.2 获取验证短信

6.12.4 验证安全短信

6.12.5 向SDK设置验证码

6.12.6 向SDK获取验证码

6.12.7 解密数据

private void test_decryptData() {
    // url是加密后的告警图片url， EZAlarmInfo.alarmPicUrl
    String url = "https://i.ys7.com/streamer/alarm/url/get?fileId=562bf00c-daec-11e5-8000-e02ec7d605d5&deviceSerialNo=497413200&isEncrypted=1&isCloudStored=1";
    RestfulUtils restfulUtils = RestfulUtils.getInstance();
    {
        //1, 下载数据，可能需要自己实现, 我这里调用的是postForStream
//            InputStream is = restfulUtils.postForStream(null, url);
        InputStream is = null;//restfulUtils.postForStream(null, url);
        try {
            byte data[] = new byte[500 * 1024];
            int len = 0, size = 0;
            while (size != -1) {
                size = is.read(data, len, data.length - len);
                if (size != -1)
                    len += size;
            }
            byte pureContent[] = Arrays.copyOf(data, len);

            // 2, 调用decryptData得到解密后的bitmap数据, NXXJOO为密码(默认是设备验证码)
            byte[] decryptData = EZOpenSDK.getInstance().decryptData(pureContent, "NXXJOO");
            LogUtil.i(TAG, "test_decryptData: decrypt finish");

            // 3, 将解密后的数据写到文件中，看是否解密成功
//                FileOutputStream fos2 = new FileOutputStream(new File("/sdcard/decrypt_img.jpg"));
//                LogUtil.i(TAG, "test_decryptData: fos2 created");
//                Bitmap bmp = BitmapFactory.decodeByteArray(decryptData, 0, decryptData.length);
//                LogUtil.i(TAG, "test_decryptData: bitmap created");
//                bmp.compress(Bitmap.CompressFormat.JPEG, 100, fos2);
//                LogUtil.i(TAG, "test_decryptData:compressed to file");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

6.13 实体类

6.13.2 EZCameraInfo

6.13.3 EZDeviceInfo

6.13.4 EZAlarmInfo

6.13.5 EZCloudRecordFile

6.13.6 EZDeviceRecordFile

6.14 EZOpenSDK枚举值

6.14.2 EZOpenSDKError

6.14.3 EZPlayerError

详见EZConstants.java

6.14.4 WiFi配置设备状态

6.14.5 其他

详见 EZConstants.java

6.14.6 其他说明

设备序列号与验证码(如图所示，位于摄像头机身)：

WiFi配置界面流程：

6.14.7 错误代码说明及分析

在demo目录下有个文件《Android开放平台错误码.xlsx》，里面有比较详细的错误码说明。ErrorCode.java也有错误定义，可作为参考

以下供开发者参考：

其他错误请参考ErrorCode类。