Open EZVIZ Platform SDK User Manual (PC)

Note 1： All the supported features are introduced in this manual. For any other feature, the users can request for us to add.
Note 2：Network Requirement: * .ezvizlife.com opens all ports (streaming ports vary randomly).

1.Overview

The user manual introduces the APIs’ definition of Open Platform SDK (PC) and the API calling sequences. The use manual consists of four parts: glossary, SDK environment configuration, main API calling flow, and APIs’ details.

This is C++ demo download url: Download SDK

2.Glossary

3.Configuration

1. Create a project in Visual Studio, and then add the library file and header file to the project.

2. There are two methods for calling DLL file: implicit loading and explicit loading. Implicit loading is generally easier than explicit loading, but the explicit loading is more flexible. For implicit loading, the DLL file is loaded when the program is starting. The follows are brief introduction about how to load implicitly.

3. Configure directory for header file （Configuration Properties->c/c++->General->Additional Include Directories）

4. Implicit loading configuration: configure the directory for the library file (Configuration Properties ->Linker->Additional Library Directories), and copy ”OpenNetStream.lib” to the path of Linker->Input->Additional Dependencies. Configuration completed.

4.Features

1. V1.0： Supports login, getting camera list, live view, playback, two-way audio, device management, PTZ control, clipping video files, and capture.
2. V2.5： Supports pushing alarm, device status, and transparent channel status to PC via push server.
3. V2.5： Supports replacing device serial No.+channel No. with CameraID, supports downloading alarm picture, supports getting the capabilities of live view definition, PTZ control, and two-way audio.
4. V3.1： Supports auto playback and micro-cloud service.
5. V3.2： Supports setting redirecting domain.
6. V4.0： Supports P2P streaming.
7. V4.2： Supports Mac operating system with 64-bit

5. Main Flow

5.1 Initialization

1.Session allocation is used for allocating resources. When there are multiple tasks to be executed, each task need to call OpenSDK_AllocSession to allocate a session, otherwise, unknown errors may occur. When allocating sessions, you should register callback function (OpenSDK_MessageHandler), which is generally used for returning error code and calling back information.
2.The results of live view, playback, two-way audio, and searching video file are retuned by the callback function (OpenSDK_MessageHandler).
3.SDK User Manual

Note: All APIs are defined in OpenNetStream.dll. Other packaged libraries are the dependent libraries of OpenNetStream.dll. You should load OpenNetStream.dll before calling APIs and you are recommended to load dynamically.

5.2 Authentication

1.Log in to the EZVIZ account on the login page, and after logging in, AccessToken will be returned.
2.call setAccessToken to set AccessToken and authenticate.

Perform the following operations after authentication：

1. Call API OpenSDK_Data_GetDevList to get the device list (supports paging) of the current account from the Hik-Connect server.
2. Call API OpenSDK_Data_GetAlarmListEx and set the parameters (deviceSerial and CameraNo) to implement the functions of live view, playback, two-way audio, PTZ control, viewing alarm list.
3. Set the parameter (deviceSerial ) to delete device(s) from the camera list.
4. Add device.

5.3 Live View

1. OpenSDK_StartRealPlayEx is an asynchronous API for live view. The live view result is determined by the value of MsgType in the callback function MessageHandler. If MsgType==3 (INS_PLAY_START), it indicates succeeded, if MsgType=0 (INS_PLAY_EXCEPTION), it indicates failed.
2. After starting live view, you can perform the following operations: recording videos, capturing pictures, two-way audio, PTZ control, and audio control. The APIs which control the PTZ, lens, and two-way audio are restricted APIs. You should call them based on the device capability. For getting device capability, call OpenSDK_Data_GetDevDetailInfo.
3. OpenSDK_SetVideoLevel is used to set video definition (videoLevel). You should set the video definition before playing video. And before setting definition, you should get videoQualityInfos from the device list or by calling OpenSDK_Data_GetDevDetailInfo. The input parameter bUpdate is valid only when the user login again or the device information is refreshed.
4. If MsgType==0 (INS_PLAY_EXCEPTION), you can call MessageInfo to get the error information. If the error information is UE105, you can call ErrorCode to get the error code.
5. all OpenSDK_SetDataCallBack to set data callback and record videos.

   5.4 Playback

1. Before starting playback, you should call OpenSDK_StartSearchEx (an asynchronous API) to search the video files. The search result is determined by the value of MsgType in the callback function MessageHandler. If MsgType==20 (INS_RECORD_FILE), it indicates searching succeeded; if MsgType==22(INS_RECORD_SEARCH_FAILED), it indicates searching failed. You can call ErrorCode to get the error code.
2. OpenSDK_StartPlayBackEx is an asynchronous API for playback. The playback result is determined by the value of MsgType in the callback function MessageHandler. If MsgType==3(INS_PLAY_START), it indicates that playback succeeded; if MsgType==0(INS_PLAY_EXCEPTION), it indicates that playback failed.
3. After starting playback, you can perform the further operations: recording video, capturing picture, and audio control. For details, see the SDK user manual.
4. Call OpenSDK_GetOSDTime to get the current playback time point. If the playback starts at 8:00, ends at 9:00, and the value of getOSDTime is 8:30, the playback progress is 50%.
5. After starting playback, you can call OpenSDK_PlayBackPause to stop playback or call OpenSDK_PlayBackResume to resume playback.
6. If MsgType==0, you can call MessageInfo to get the error information. If the error information is UE105, you can call ErrorCode to get the error code.
7. If MsgType==5(INS_PLAY_ARCHIVE_END), it indicates playback ended.
8. Call OpenSDK_SetDataCallBack to set data callback and record the videos.
9. As the limitation of cloud storage, the video search API OpenSDK_StartSearchEx only support searching video files within 24 hours.

   5.5 Two-Way Audio

1. Call OpenSDK_StartVoiceTalkEx to start two-way audio (an asynchronous API). The result is determined by the value of MsgType in the callback function MessageHandler. If MsgType==16(INS_VOICETALK_START), it indicates that the two-way audio is started. If MsgType==18(INS_VOICETALK_EXCEPTION), it indicates that starting two-way audio failed.
2. Call OpenSDK_StopVoiceTalk to stop two-way audio (an asynchronous API). The result is determined by the value of MsgType in the callback function MessageHandler. If MsgType=17(INS_VOICETALK_START), it indicates that the two-way audio is stopped.
3. Two-way audio is started by the PC. The SDK will automatically adjust the microphone to acquire audio data, and then transmit the data to the device. The device receives the audio via the earphone. The current supported two-way audio devices includes double-orifice earphone, one orifice is earphone, and the other orifice is microphone.
4. If the video contains sound, you should mute the video sound (closeSound) before starting two-way audio. After stopping two-way audio, turn on the video sound (openSound). For details, see the demo.

5.6 Push Information

To receive the message notified by device to PC, you should send email to open-team.com for applying for pushSercret. The required information when applying is as follows (# is required):

1. Environment (test2 /online)
2. Valid appKey (Registered in the Open platform). The appKey should be consistent with your country or region.
3. Name of the third-party application
4. (Optional) Description of the third-party application

Note: There’re two alarm modes, active mode and passive mode. In active mode, when the alarm is triggered, the device will automatically upload alarm information to the callback function. And in passive mode, when the alarm is triggered, you should recall the API to get the alarm information.

5.7 Get Data

5.8 Device Control

1. Call OpenSDK_PTZCtrlEx (an asynchronous API) to perform PTZ control. The result is determined by the value of MsgType in the callback function MessageHandler. If MsgType==46(INS_PTZCTRL_SUCCESS), it indicates that performing PTZ control succeeded. If MsgType==47(INS_PTZCTRL_FAILED), it indicates that performing PTZ control failed.
2. Call OpenSDK_DevDefenceEx (an asynchronous API) to arm or disarm. The result is determined by the value of MsgType in the callback function MessageHandler. If MsgType==23(INS_DEFENSE_SUCCESS), it indicates armed or disarmed. If MsgType==24(INS_DEFENSE_FAILED), it indicates arming or disarming failed.

6.Quick Start Guide

This chapter introduces the definitions of the important APIs, typical applications, and code examples for the developer to quick start the development. Download [Qt Demo] first.

6.1 Qt Demo Function Overview

1. Function Show, SDK Test Tool
2. Debug, Bug Verification
3. Demo (Example Source Code)

6.2 Qt Demo Project Environment

1. Qt SDK Version：Qt4.8.5
2. Two Modes for Developing Qt Demo:
   1). Download Qt Creator for Windows, open OpenSDK_Demo_Qt.pro and develop in Qt Creator
   2). Add Qt4 module to Visual Studio 2008, and then open OpenSDK_Demo_Qt.sln to compile it.

6.3 Configure Demo Configuration File（OpenSDK_Demo_Qt.ini）

6.4 Steps of Demo Operations

1. get the AppKey and AppSecret.
2. Open OpenSDK_Demo_Qt.ini by Notepad to configure.
3. Live view, playback, two-way audio, and PTZ control are available after login.
4. You can get Demo or OpenSDK by DebugView for troubleshooting. Note: The directory of the Demo project should not contain Chinese.

6.5 Get Camera List

int OpenSDK_Data_GetDevList( const char* szAccessToken, int iPageStart, int iPageSize, void** pBuf, int* iLength);

Note: Call OpenSDK_Data_GetDevList to get strings in JSON format, which contains the camera list information.

6.6 Live View

1. Configure isPlay field in OpenSDK_Demo_Qt.ini. For example, ”isPlay =true”.
2. Start Demo, and log in to your account.
3. Select cameras and start live view.

int OpenSDK_StartRealPlayEx(const char* szSessionId, HWND hPlayWnd, const char* szDevSerial, const int iChannelNo, const char* szSafeKey);

Note: Call OpenSDK_StartRealPlayEx to input device serial No., channel No., and window handle. If the device is encrypted, you should enter the device verification code.

6.7 Playback

1. Configure isPlay field in OpenSDK_Demo_Qt.ini. For example, ”isPlay =true”
2. Start Demo and log in to your account.
3. Select cameras and configure the time for searching video files, and then start searching.
4. Select a found video file and then start playing.

int OpenSDK_StartPlayBackEx(const char* szSessionId, HWND hPlayWnd, const char* szDevSerial, const int iChannelNo, const char* szSafeKey, const char* szStartTime, const char* szStopTime);

Note: Call OpenSDK_StartPlayBackEx to input device serial No., channel No., and window handle. If the device is encrypted, you should enter the device verification code.

6.8 Recording

1. Configure saveData field in OpenSDK_Demo_Qt.ini. For example, ”saveData=true”.
2. Start Demo and log in to your account.. After starting live view and playback, the following file is generated in the directory of executable program:
   

int OpenSDK_SetDataCallBack(const char* szSessionId, OpenSDK_DataCallBack pDataCallBack, void* pUser);

Note: Currently, downloading video files is not supported by EZVIZSDK, only the recording is supported. Recording depends on the data callback function, for details, refer to the SDK user manual.

7.FAQ

1. Why the system returns the error code 3 on the login page of Qt Demo? Answer: The value of appkey is not configured in the configuration file of Qt Demo.

2. Why the system returns the error code 2012 during live view. Answer: The verification code is incorrect.

3. How to check the OpenSDK’s version information? Answer: Select OpenSDK, right click Properties and click Details to view the version.