在开始使用BVCU SDK进行开发之前，需要了解SDK涉及的几个概念。
BVCU SDK涉及了这样几个概念：Session、Dialog、Command，了解了这些概念，也就掌握了整个SDK。
Session
SDK是作为客户端的一端，作为客户端（CU），BVCU必须登录服务器（Server），而且支持同时登录多个服务器。在BVCU每次登录服务器成功之后，就会创建一个Session对象，在BVCU.h中用 BVCU_HSession 表示。
调用接口 BVCU_Login 成功后登录服务器并创建一个Session对象。调用接口 BVCU_Logout 成功后退出服务器并销毁Session对象。
由此，Session起到了登录连接服务器的唯一标识作用。
Dialog
BVCU的最重要的功能就是预览（或监视）服务器（Server）传过来的设备（PU）音视频。一台设备可以有多个通道，每个通道可能有音频或者视频。预览PU通道的视音频时，BVCU需要
向服务器发起预览请求，这种预览的请求称为“会话”（Dialog）。在BVCU.h中用 BVCU_HDialog 表示。在实际使用中，根据媒体方向的不同，Dialog有以下几种常见的类型：
类型1：Dilaog请求接收1路视频流，或者额外再接收2路音视频。这是最常见的情况。
类型2：Dialog请求接收设备的1路音频流，并发送1路本地音频给设备，这被称为语音对讲。
类型3：Dialog请求发送1路本地音频流给多个设备。这被称为语音广播。
开发者应该注意，类型2和类型3（语音对讲）的Dialog在整个BVCU库只能有一个。
在开发中，调用 BVCU_Dialog_Open 向服务器请求发起一个Dialog并创建一个Dialog对象。Dialog的目标由 BVCU_DialogParam 结构体中的 iTargetCount.pTarget指定。
对类型1和类型2的Dialog，iTargetCount总是1，对于类型3，iTargetCount可以大于1.Dialog的类型由 BVCU_DialogParam.iAVStreamDir决定。
BVCU_DialogControlParam_Render参数决定了是否在窗口中播放音视频，BVCU_DialogControlParam_Storage 决定了是否存储接收到的音视频数据及存储路径。
BVCU_Dialog_Update 函数通过更改 BVCU_DialogParam.iAVStreamDir 来改变一个已经建立的Dialog的媒体方向，这只对类型1有意义。例如可以去掉/增加一个音频流等。
BVCU_Dialog_Control 函数更改会话的本地设置，包括接收、存储和回放等。
BVCU_Dialog_Snapshot 函数抓取会话中接收到的一帧视频，存为图像文件。
BVCU_Dialog_Close 函数关闭Dialog并摧毁Dialog对象。
Command
除了上述预览音视频外，BVCU还需要通过和服务器通讯来支持其他功能。BVCU需要向服务器发送命令包，每条命令对应一个Command对象，在BVCU.h中用BVCU_Command表示。
调用者通过调用 BVCU_SendCommand 接口向服务器发送命令。
注意：在BVCU 库中，Session对象中包括Dialog对象和Command对象，当Session对象销毁时，所有已存在的Dialog对象和Command对象都将被销毁。
在对Session、Dialog、Command有了大致的了解后，下面是对SDK调用流程和涉及到的相关接口的介绍（接口涉及到的数据结构这里不做赘述，可在客户端开发手册或相关头文件中查阅）
SDK调用主要流程如下图所示：
其中的虚线部分的流程模块是可选部分，不会影响其他流程和模块的功能使用。按功能实现的不同可分为以上几个模块。
左侧部分是会话相关的功能模块，包括预览、更改和关闭音视频通道、打开和关闭GPS通道、打开和关闭透明串口通道和向透明串口通道中写入数据。
右侧包括接收服务器通知、向服务器发送命令、平台或者前端文件的检索与下载（FTP）以及回放录像文件和GPS轨迹。调用BVCU实现以上每个功能模块的时候，初始化SDK、登录服务器、获取设备列表、退出服务器和释放SDK这5个流程都是必不可少的。
在实际调用接口开发过程中，BVCU库有以下几个通用的使用原则：
所有需要发送网络数据的函数（包括 BVCU_Login、BVCU_Logout、BVCU_Dialog_Open、BVCU_Dialog_Update、BVCU_Dialog_Close 和 BVCU_SendCmd），都支持异步回调。如果函数返回失败，则并没有发送网络命令包给服务器，也不会调用回调函数。如果函数返回成功，则意味着函数发出了网络命令包给服务器，但命令执行结果通过回调函数来通知应用程序。
不可以在回调中调用除了 BVCU_GetSessionInfo、BVCU_GetDialogInfo、BVCU_SetLogLevel、BVCU_GetLogLevel 之外的任何BVCU函数。
不可以在回调函数中执行任何可能导致阻塞的操作，例如执行 Windows API MessageBox 等。
① 初始化SDK（BVCU_Initialize）：对整个BVCU库进行初始化，分配内部相关结构内存，初始化网络接口和协议相关数据，初始化并启动各线程，这些线程包括：网络传输线程、数据存储线程、编解码线程、视频播放线程、音频采集线程和音频播放线程。此外，初始化FTP相关数据，启动FTP内部线程。
开发者在调用初始化接口时，需要分配该接口的参数，参数包括全局事件回调，此回调需要开发者自己定义。如果初始化成功，则 BVCU_Initialize 返回 BVCU_RESULT_S_OK，返回其他值则失败。初始化成功，BVCU SDK会把库内部检测到的全局事件通过事件回调通知应用程序。（注：回调函数中不可阻塞）。
释放SDK（BVCU_Finish）：释放BVCU库内部分配的数据内存，结束内部线程，释放资源。
/**
*初始化BVCU库，只能在应用程序启动时调用一次。
任何其他BVCU库函数只有在BVCU_Initialize成功后才可以调用
*/
LIBBVCU_API BVCU_Result BVCU_Initialize(const BVCU_GlobalParam* pParam);
② 登录服务器（BVCU_Login）：开发者调用此接口成功，则将BVCU与服务器建立连接，并创建一个 Session 对象，在建立连接后，服务器通过参数中的回调通知应用软件。同时，服务器也会通过onNotify通知本地应用程序，
其中，第二个参数 BVCU_ServerParam 结构体中的 OnEvent 回调用于该 Session 相关的的事件。例如登录成功或者失败，退出事件等。BVCU_ServerParam 结构中的 OnNotify 回调用于服务器向应用程序发送通知，
例如设备上下线通知，报警通知等。（注：回调函数中不可阻塞）。
退出服务器（BVCU_Logout）：调用此接口断开与服务器的连接，释放网络资源，销毁Session对象。
/**
*登录Server。该函数是异步的。如果登录成功，在返回前或者返回后会产生OnEvent回调。
* @param[out] phSession: 返回登录Session
* @param[in] pParam: Server信息
* @return: 常见返回值
* BVCU_RESULT_S_OK: 正确完成。结果通过OnEvent通知调用者。
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_Login(BVCU_HSession* phSession, BVCU_ServerParam* pParam);
③ 获取设备列表是在登录服务器成功后，发送命令来获取注册该服务器上的设备。获取设备列表则需要调用BVCU_SendCmd()来发送命令。
发送命令需要通过填写 BVCU_Command 结构，在获取设备列表时，BVCU_Command 的主命令字段填 BVCU_METHOD_QUERY， 子命令填 BVCU_SUBMETHOD_PU_LIST。
服务器处理成功后，通过 BVCU_Command 中的回调通知应用层。（注：回调函数中不可阻塞）。
/**
* CU发送命令。该函数是异步的，命令完成后触发BVCU_Command.OnEvent回调通知。
* @param[in] hSession: BVCU_Login返回的登录Session.
* @return: 常见返回值
* BVCU_RESULT_S_OK: 调用正确完成。结果通过OnEvent通知调用者。
* BVCU_RESULT_E_NOTEXIST: 登录Session不存在，即未登录
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_SendCmd(BVCU_HSession hSession, BVCU_Command* pCommand);
④ 虚线部分的流程模块是可选部分，也是最主要的功能模块。对Dialog的操作 、 命令操作 、 接收通知， FTP操作。
1、Dialog的操作， 分为创建（打开），更改会话状态，写入，关闭
/**
* 创建（打开）会话（视频、TSP串口、）。该函数是异步的，如果创建会话成功，在返回前或者返回后会产生OnEvent回调函数，
* 事件码是BVCU_EVENT_DIALOG_OPEN，如果事件参数的iResult是失败代码，则会话创建失败，调用者不必调用BVCU_Dialog_Close
* @param[out] phDialog: 返回会话句柄.
* @param[in] pParam: 会话参数。
* @param[in] pControl: 控制参数。
* @return: 常见返回值
* BVCU_RESULT_S_OK: 调用正确完成。结果通过OnEvent通知调用者。
* BVCU_RESULT_E_UNSUPPORTED: 不支持的操作，例如在不支持对讲的通道上要求对讲
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_Dialog_Open(BVCU_HDialog* phDialog, BVCU_DialogParam* pParam, BVCU_DialogControlParam* pControl);
/**
* 更改会话的本地设置，包括接收/存储/回放等。此函数不需要与Server通讯。
* @param[in] hDialog: BVCU_Dialog_Open返回的Dialog句柄.
* @param[in] pParam: 控制参数。
* @return: 常见返回值
* BVCU_RESULT_S_OK: 成功
* BVCU_RESULT_E_NOTEXIST: 会话不存在
* BVCU_RESULT_E_UNSUPPORTED: 不支持的操作
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_Dialog_Control(BVCU_HDialog hDialog, BVCU_DialogControlParam* pParam);
/**
* 向会话通道中写数据。目前只支持含BVCU_MEDIADIR_DATASEND方向的会话通道。
* @param[in] hDialog: BVCU_Dialog_Open返回的Dialog句柄.
* @param[in] pData: 写入的数据。
* @return: 常见返回值
* BVCU_RESULT_S_OK: 成功
* BVCU_RESULT_E_NOTEXIST: 会话不存在
* BVCU_RESULT_E_UNSUPPORTED: 不支持的操作
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_Dialog_Write(BVCU_HDialog hDialog, SAV_Packet* pData);
/**
* 关闭会话。该函数是异步的，在返回前或者返回后会产生OnEvent回调函数，
* 注意：(1)该函数必须在BVCU_Dialog_Open成功且BVCU_Dialog_Open的OnEvent回调函数被调用之后才可以调用
* (2)不能在任何OnEvent/OnNotify中调用BVCU_Dialog_Close
* @param[in] hDialog: BVCU_Dialog_Open返回的Dialog句柄.
* @return: 常见返回值
* BVCU_RESULT_S_OK: 正确完成。结果通过OnEvent通知调用者。
* BVCU_RESULT_S_IGNORE: 会话不存在
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_Dialog_Close(BVCU_HDialog hDialog);
2、命令操作
/**
* CU发送命令。该函数是异步的，命令完成后触发BVCU_Command.OnEvent回调通知。
* @param[in] hSession: BVCU_Login返回的登录Session.
* @return: 常见返回值
* BVCU_RESULT_S_OK: 调用正确完成。结果通过OnEvent通知调用者。
* BVCU_RESULT_E_NOTEXIST: 登录Session不存在，即未登录
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_SendCmd(BVCU_HSession hSession, BVCU_Command* pCommand);
3、接收通知、接收通知， FTP操作和录像 请参阅客户端开发手册。
⑤ 退出服务器（BVCU_Logout）：调用此接口断开与服务器的连接，释放网络资源，销毁Session对象。
/**
* 退出登录。该函数是异步的，在返回前或者返回后会产生OnEvent回调。
* 注意：(1)该函数必须在BVCU_Login登录成功且BVCU_Login的OnEvent回调函数被调用之后才可以调用
* (2)不能在任何OnEvent/OnNotify中调用BVCU_Logout
* @param[in] hSession: BVCU_Login返回的登录Session.
* @return: 常见返回值
* BVCU_RESULT_S_OK: 正确完成。结果通过OnEvent通知调用者。
* BVCU_RESULT_E_FAILED或其他： 其他错误导致失败
*/
LIBBVCU_API BVCU_Result BVCU_Logout(BVCU_HSession hSession);
poston 2017-3-21 14:43
favor
poston 2018-4-13 11:46
