即时通讯开发平台AnyChat的开发流程及应用

AnyChat开发流程指南
下面列出AnyChat Platform Core SDK基本开发流程，适用于开发视频会议系统、语音视频聊天系统、远程教育平台以及即时通讯平台（IM）等。

一、初始化
该部分是首先要完成的，用于设置SDK的一些行为，包括设置对应的回调函数、设置SDK组件路径、设置是否产生日志文件等，通常初始化AnyChat SDK的代码如下（C++）：

01.// 打开（关闭）SDK的日志记录功能
02.BRAC_ActiveCallLog(TRUE);
03.    
04.// 设置SDK核心组件所在目录
05.CHAR szCoreSDKPath[MAX_PATH] = {0};
06.GetModuleFileName(NULL,szCoreSDKPath,sizeof(szCoreSDKPath));
07.(strrchr(szCoreSDKPath,'\\'))[1] = 0;
08.BRAC_SetSDKOption(BRAC_SO_CORESDK_PATH,szCoreSDKPath,strlen(szCoreSDKPath));
09.    
10.// 根据BRAC_InitSDK的第二个参数：dwFuncMode，来告诉SDK该如何处理相关的任务（详情请参考开发文档）
11.DWORD dwFuncMode = BRAC_FUNC_VIDEO_CBDATA | BRAC_FUNC_AUDIO_AUTOPLAY | BRAC_FUNC_CHKDEPENDMODULE | BRAC_FUNC_AUDIO_VOLUMECALC | BRAC_FUNC_NET_SUPPORTUPNP | BRAC_FUNC_FIREWALL_OPEN |
12.BRAC_FUNC_AUDIO_AUTOVOLUME | BRAC_FUNC_CONFIG_LOCALINI;
13.BRAC_InitSDK(this->GetSafeHwnd()/*NULL*/,dwFuncMode);
14.    
15.// 设置录像临时文件保存路径
16.CHAR szRecordDirectory[MAX_PATH] = {0};
17.::GetModuleFileName(NULL,szRecordDirectory,MAX_PATH);
18.(strrchr(szRecordDirectory,'\\'))[1] = 0;
19.strcat(szRecordDirectory,"Record");
20.BRAC_SetSDKOption(BRAC_SO_RECORD_TMPDIR,szRecordDirectory,strlen(szRecordDirectory));
21.
22.// 设置录像文件质量参数
23.DWORD dwVideoBitrate = 200 * 1000;  // 200kbps
24.BRAC_SetSDKOption(BRAC_SO_RECORD_VIDEOBR,(PCHAR)&dwVideoBitrate,sizeof(DWORD));
25.DWORD dwAudioBitrate = 96 * 1000;   // 96kbps
26.BRAC_SetSDKOption(BRAC_SO_RECORD_AUDIOBR,(PCHAR)&dwAudioBitrate,sizeof(DWORD));
27.    
28.// 设置快照临时文件保存路径
29.CHAR szSnapShotDirectory[MAX_PATH] = {0};
30.::GetModuleFileName(NULL,szSnapShotDirectory,MAX_PATH);
31.(strrchr(szSnapShotDirectory,'\\'))[1] = 0;
32.strcat(szSnapShotDirectory,"SnapShot");
33.BRAC_SetSDKOption(BRAC_SO_SNAPSHOT_TMPDIR,szSnapShotDirectory,strlen(szSnapShotDirectory));
34.    
35.// 设置SDK临时文件路径
36.CHAR szTempPath[MAX_PATH] = {0};
37.::GetModuleFileName(NULL,szTempPath,MAX_PATH);
38.(strrchr(szTempPath,'\\'))[1] = 0;
39.strcat(szTempPath,"Temp");
40.BRAC_SetSDKOption(BRAC_SO_CORESDK_TMPDIR,szTempPath,strlen(szTempPath));
41.
42.// 启用音频自动参数功能（默认关闭）
43.DWORD bAudioAutoParam = TRUE;
44.BRAC_SetSDKOption(BRAC_SO_AUDIO_AUTOPARAM,(PCHAR)&bAudioAutoParam,sizeof(DWORD));

二、登录系统
当第一步初始化完成之后，便可以连接服务器、验证用户身份。通常调用代码如下（C++）：
1.// 连接服务器
2.BRAC_Connect("211.155.25.90",8906);
3.// 登录系统
4.BRAC_Login("testuser","",0);
连接服务器与登录系统都是一个异步的过程，调用后会立即返回，其中：
a、连接服务器成功，或是失败，将会触发异步消息
b、登录系统成功，或是失败，将会触发异步消息
所以应用程序需要响应这些异步消息才能知道连接服务器、登录系统是否成功。

登录系统成功后，如果需要实现即时通讯应用中的好友列表（AnyChat默认没有实现），则需要利用AnyChat的扩展API接口与Server SDK来配合实现，具体实现方案可参考SDK包中的：doc\server\目录下的《AnyChat Server SDK 开发指南》第6章节。

登录系统成功后，服务器会返回一个32位的用户ID，如果登录时没有传入密码参数，则系统会认为是游客登录，并分配一个独立的用户ID（如-1、-2等），如果登录时传入了密码参数，则登录请求将会交给“SDK Filter Plus”接口，或“Server SDK”对应的接口，用户可开发一个自己的服务器插件“SDK Filter Plus”，或是调用“Server SDK”所对应的API来处理用户身份验证的请求，完成对用户ID的管理，实现与第三方系统的互联互通，详细内容可参考SDK包中的：doc\server\目录下的相关文档。

三、进入房间
在第二步登录系统成功之后，就可以进入房间，因为只有在房间中，才能完成语音和视频的交互。通常调用代码如下（C++）：
1.// 进入房间
2.BRAC_EnterRoom(1,"",0);
房间由服务器动态管理，由32位的房间ID号来唯一标示，当客户端指定的房间ID号不存在时，服务器将会自动创建。进入房间也是一个异步的过程，是否成功将会触发异步消息，进入房间成功后，服务器会把当前房间的在线用户列表传给客户端，传输完成后，将会触发异步消息（该消息只触发一次），只有收到服务器的在线用户列表后，才能对房间内的用户进行音视频的相关操作。

当自己进入房间成功，且收到服务器的在线用户消息后，有新的用户进入房间，或是老用户离开房间，将会触发异步消息，这样自己便知道谁进入，或是离开了房间。

1、打开自己的音视频
进入房间成功之后，便可以打开自己的音视频设备，通常调用代码如下（C++）：
1.// 打开自己的视频设备
2.BRAC_UserCameraControl(-1,TRUE);
3.// 打开自己的音频设备
4.BRAC_UserSpeakControl(-1,TRUE);
打开自己的设备后，并不会立即上传音视频流，只有当其它用户请求自己的音视频数据时（可单独请求音频流，或视频流）才对外传输，打开自己的音视频设备，默认是按服务器的配置信息来初始化设备（如采样分辨率、视频帧率、音频的采样频率等），如需要在客户端程序中调节音、视频质量。

2、请求其它用户的音视频
如果需要显示其它用户的音视频，则必须在收到房间用户列表消息后，请求对方的音视频流，然后对方才将音视频流传输过来，通常请求其它用户的音视频数据调用代码如下（C++）：
1.// 请求对方的视频流
2.BRAC_UserCameraControl(dwUserId,TRUE);
3.// 请求对方的音频流
4.BRAC_UserSpeakControl(dwUserId,TRUE);
数据传输优先P2P方式，只有当P2P不通时，才由服务器转发，P2P的NAT打洞过程，以及数据流传输策略均由服务器控制，只要有请求，而且对方已打开了自己的音视频设备，则就能收到对方的音视频流数据。

3、音视频的播放与显示
当收到其它用户的音频数据后：
a）如果在初始化时设置了“BRAC_FUNC_AUDIO_AUTOPLAY”标志，则SDK内部将会自动播放，自动混音；
b）如果在初始化时设置了“BRAC_FUNC_AUDIO_CBDATA”标志，则SDK会将解码后的音频数据（PCM格式）通过回调函数回调给上层应用。

当收到其它用户的视频数据后：
a）如果在初始化时设置了“BRAC_FUNC_VIDEO_AUTODISP”标志，并且调用了，则SDK内部将会把视频显示到指定的窗体的指定位置（在指定位置上自动迭加一个视频窗口）；
b）如果在初始化时设置了“BRAC_FUNC_VIDEO_CBDATA”标志，则SDK会将解码后的视频数据（RGB、YUV）通过回调函数回调给上层应用，由上层应用自己来绘制，或渲染，该模式适合于DirectX、HGE等没有窗口模式下的应用程序，或是上层应用需要对视频进行特殊处理的场合，如迭加文字、logo等。

4、文字交互
成功进入房间后， 便可以调用API接口向指定用户，或是房间中的所有用户发送文字消息：
1.// 发送文字消息
2.CString strInput = "hello world";
3.BRAC_SendTextMessage(-1,FALSE,strInput.GetBuffer(0),strInput.GetLength());
其它用户收到自己发送的文字消息后，便会触发回调函数，通过处理回调消息，然后将收到的文字消息显示在界面上，便可实现文字的交互。

5、业务逻辑处理

AnyChat SDK内置的基本逻辑是：当自己的音视频设备打开后，别的用户有请求，便会将流媒体数据传输给对方，而没有任何何业务逻辑。
a）如要实现视频会议系统，则用户进入房间后，就需要知道谁是主持人，然后打开主持人的视频；
b）如要实现视频聊天系统，则用户进入房间后，就需要知道当前房间有几个公麦，谁在公麦上，然后打开对应公麦用户的视频等；
c）……
这些业务逻辑需要与服务器端的“SDK Filter Plus”或“AnyChat Server SDK”互相配合来实现，具体的实现方案可参考SDK包中的：doc\server\目录下的《AnyChat Server SDK 开发指南》第6章节。

四、释放资源
与前面连接服务器、登录系统、进入房间对应的，退出系统的过程是：离开房间、注销系统、释放资源，通常调用代码如下（C++）：
1.// 离开房间
2.BRAC_LeaveRoom(-1);
3.// 注销系统（将关闭网络连接）
4.BRAC_Logout();
5.// 释放资源
6.BRAC_Release();
离开房间后，可以进入新的房间，系统注销之后，可以再次调用连接服务器的API接口，但是释放资源后，SDK将不再工作。
需要特别注意一下释放资源的时机。

Windows平台AnyChat视频显示
1、如何显示本地视频，或是其它计算机上的视频？
    a）AnyChat的客户端必须初始化、登录系统、进入房间成功之后，才能显示本地视频或是其它用户的视频。
    b）AnyChat有两种方式来显示视频，分别是：自动显示（BRAC_FUNC_VIDEO_AUTODISP）、回调视频数据（BRAC_FUNC_VIDEO_CBDATA）,应用程序需要在初始化（BRAC_InitSDK）时设置相关的标志来告诉AnyChat如何处理视频的显示。
当设置了自动显示（BRAC_FUNC_VIDEO_AUTODISP）时，应用程序需要设置视频显示位置（BRAC_SetVideoPos），当打开本地用户的视频，或是请求远程用户的视频时，AnyChat内部会自动将视频显示在指定的位置；
如果没有设置自动显示标志，而只设置了回调视频数据（BRAC_FUNC_VIDEO_CBDATA）标志时，AnyChat内部不会显示视频，而是将视频数据通过回调的方式提交给应用程序，由应用程序自己来绘制；
    c）当用户使用API接口（BRAC_UserCameraControl）打开本地摄像头后，本地计算机的视频即可显示出来；
    d）当用户使用API接口（BRAC_UserCameraControl）请求其它用户的视频数据时，只有该用户打开自己的摄像头之后，本地计算机才能收到对方用户的视频；


2、什么是视频显示驱动，如何选择？
    Windows平台有多种方式来实现视频的显示，常见的有GDI绘图和DirectShow两种模式。当设置AnyChat自动显示视频标志时，应用程序可以在这两种模式之间进行选择，视频显示驱动的选择需要在初始化（BRAC_InitSDK）成功之后设置，下面的代码演示了选择DirectShow显示驱动：

1.// 选择AnyChat显示驱动
2.DWORD dwVideoDriver = BRAC_VSD_DIRECTSHOW;
3.BRAC_SetSDKOption(BRAC_SO_VIDEOSHOW_DRIVERCTRL,(constchar*)&dwVideoDriver, sizeof(DWORD));
    AnyChat为了简化应用程序开发流程，同时也为了兼容更早期的版本，默认采用GDI绘图方式来显示视频；GDI绘图方式适合分辩率不大于CIF（352x288），同时帧率低于20FPS的视频显示；DirectShow显示模式适合高分辨率、高帧率的视频显示。

DirectShow显示模式在高视频质量下更节约资源；

    (*注：视频显示驱动选择功能为AnyChat Platform Core SDK V4.0版本新增功能)

3、显示的视频为何有些变形，如何设置？
    当视频显示区域的大小与视频的原始大小不成比例时，所显示的视频将会变形，所以要保证显示的视频不变形，则必须保证视频显示区域与视频的原始大小成正比关系；
    通过WM_GV_VIDEOSIZECHG消息（V4.0版本新增）可以知道每一个用户当前原始视频的大小，应用程序可以根据原始视频的大小来确定视频显示区域的大小，也可以通过API（BRAC_QueryUserState）来获取用户当前的视频大小；
    当用户进入房间时，AnyChat内部会每一个在线用户触发一次WM_GV_VIDEOSIZECHG消息；
    当用户修改视频采集分辨率时，房间内所有用户都将收到该用户的WM_GV_VIDEOSIZECHG消息；

4、为何有时视频被其它窗口覆盖，或是最小化后视频被遮挡，不能自动刷新？
    这主要出现在DirectShow显示模式下，主要原因是应用程序界面重绘之后，底层的DirectShow没有获得重绘的消息通知，所以导致视频被遮挡，解决方案是响应窗口的WM_PAINT消息，在消息处理函数中调用BRAC_RepaintVideo进行视频的重绘。
    AnyChat默认的GDI绘图模式下，不存在该问题。
    AnyChat底层的DirectShow是采用VMR的Windowless模式进行视频显示，有关该问题的详细信息可参考微软官方的开发文档。