*********************
概述
*********************

.. contents:: Table of Contents

Open-AVD SDK业务概念
=======================

SDK中有三层业务对象，分别为AVD引擎、房间和功能模块；三层业务对象是向上依赖的，AVD引擎为唯一对象，房间对象依赖于AVD引擎，各功能模块依赖于某一房间。

AVD引擎(AVDEngine)
-------------------
AVD引擎是SDK中进程级、全局性的一个运行上下文环境，SDK的所有功能都必须在此环境中才能正确工作；如在这个环境中可以运行多个Room（房间）或者多个用户加入同一或不同房间。应用层可以给引擎设置一些默认参数，影响所有当前引擎环境的入会者房间。 客户应用层在使用SDK的第一步就是进行引擎初始化，初始化时需要杭州叁体网络提供的与客户相关的唯一appkey和对应的secretkey做授权验证；同时对SDK中的线程、设备等进行准备。引擎初始化成功后，即可使用AVD引擎接口中提供的接口进行安排、查询、删除房间等管理工作；可以同时加入多个Room（房间）或者多个用户加入多个房间中，做各种音视频和数据的房间内沟通；可以对房间中的音视频和数据做录制和直播等各种操作。

房间（room）
-------------------
房间是AVD SDK实时沟通功能的一个管理单元，房间中会有多个沟通参与者即用户，房间有各种沟通功能，如文字聊天、语音视频等，沟通是基于房间的。不同房间沟通是隔离的。 房间中重要属性如下： 
   * 房间Id：SDK生成，唯一标示一个房间的字符串。 
   * 房间名：应用层创建房间时设置，以可读方式定义的一个字符串。
   * 房间应用层Id：应用层创建房间时设置的标识一个房间的字符串。 
   * 房间模式
          MCU模式：房间中的数据通过服务器做路由转发，适合大规模房间，服务器将消耗带宽，需要保证带宽足够。
          
          P2P模式：房间中的数据不经过房间服务器，直接在房间若干客户端间做转发，适合小规模（如5人以下）房间。
   * 房间最大用户数：一个房间中可以同时参与的最大用户数，用于限制用户加入。
   * 房间最大话筒路数：一个房间中可以同时打开的话筒数量，用于限制音频输入数量。
   * 房间最大视频路数：一个房间中可以同时打开的视频数量，用于限制房间中视频数量。
   * 房间最大屏幕窗口共享路数：一个房间中可以同时打开的屏幕窗口共享数量。

用户（user）
-------------------
每个加入到房间的客户端作为一个房间用户，用户将会根据权限和设备情况执行房间中各种沟通功能。
    * 用户Id：唯一标示一个房间用户的Id，由应用层来设置，应用层可以与其业务系统用户相绑定。 
    * 用户状态：用户的设备拥有和开启情况。

设备（device）
-------------------

房间中设备指能开启各种沟通能力的逻辑对象，主要有音频设备话筒和扬声器，视频设备摄像头和屏幕窗口。 
   * 设备Id：唯一标识设备的编号，SDK内部生成。
   * 设备状态：当前设备的所处状态，主要有无设备、设备就绪、设备发布音频或视频、设备暂停等。

音频设备有话筒和扬声器，可以通过IAudioDevice接口对当前房间内的设备做管理。 视频设备有摄像头和屏幕窗口，屏幕窗口主要用于屏幕共享时使用。 视频设备有一些特性，如下： 
   * 设备Level：应用层对设备设置的数据，可用于表示视频权重等, 应用层开发可用 
   * 设备描述：应用层对设备的描述，应用层开发可用
   * 设备属性特性：视频设备质量类型集：摄像头通知时包含摄像头支持的视频质量集合 
   * 设备发布特性：视频发布质量类型集：设备发布时包含的发布视频的质量集合

摄像头 摄像头对应一个物理上的真实摄像头设备。 摄像头类型：前置摄像头，后置摄像头，未知类型（无法判断出来是前置还是后置）。 视频采集能力 * 分辨率：视频质量的 * 帧率

屏幕窗口操作系统中屏幕或者窗口区域对象。 屏幕：整个系统窗口。 应用程序窗口：某一个应用程序的窗口，如资源管理器的窗口。

房间内功能模块（module)
-------------------
1.用户管理模块（musermanager） 房间内用户及用户群体的操作、状态通知。

2.聊天模块（mchat) 公聊：整个房间内的一个所有用户参与的文字沟通渠道，每个用户可以根据权限接收和发送消息。 私聊：房间内两个用户间的私有文字沟通渠道。 聊天历史记录

3.音频模块（maudio) 音频模块通过对麦克风和扬声器的控制，实现房间内各用户的高清语音沟通。 移动端特殊功能：自动路由音频设备，自动在听筒、外放、外置耳机和蓝牙耳机等各种设备中播放和采集高清语音。 桌面端特殊功能：可以列出多个音频设备进行选择使用，支持设备的热插拔。

4.视频模块（mvideo) 预览（preview）：视频预览是一个本地视频操作，将本地的摄像头视频在窗口上展现出来。 发布（publish）：视频发布是将本地摄像头的视频发布到房间中，让所有房间中的用户可以订阅和显示当前发布的摄像头视频。 订阅（subscribe）：用户如果要查看房间中已发布视频，需要在房间中订阅此视频，让服务器将此视频的视频数据路由到用户客户端来。 视频切换摄像头： 显示对象（render） 显示模式：原图显示，适应窗口（比例不变），铺满窗口 显示角度：自动旋转

5.屏幕应用共享模块（mscreen) 共屏屏幕窗口（switch）

Open-AVD SDK语言概念
=======================

AVD SDK中涉及一些编程开发的语言概念，说明如下：

接口（I） 
-------------------
SDK内部实现了的，提供给应用层调用的的功能函数。C++ SDK以I字母开始来命名。
  * 同步调用接口：接口调用完成后马上就能知晓调用结果的接口。
  * 异步调用接口 接口调用后，部分操作结果不能即时知晓，需要等待一段时间才由回调函数返回的接口。一般都是涉及长时间操作或者网络通讯类操作。

远程指令（remotecmdxxx）
------------------
以remotecmd开始的接口函数为远程指令操作，这种操作一般是操作远端的用户和设备，是否操作成功与失败部分依赖于远端。

回调接口（IListener）
------------------
SDK内部调用，应用层实现的一组功能操作，主要用于异步调用返回、事件通知、通讯回调等。回调接口我们以IListener开做命名。按类型我们将这些接口分为以下几种：


回调异步返回（onxxxResult）
------------------
异步调用接口调用后通过回调异步返回来通知应用层调用的结果。

回调指示（onxxxIndication）
------------------

回调指示是服务器或者远端用户发送过来的一个操作命令，收到指示的用户需要执行特定操作。

回调通知（onxxxNotify)
------------------
当执行某一操作时候，设备、用户或者房间等对象的状态信息将会更新，所有用户将会收到回调通知，通知一般都是多人的。