讯通话音媒体交流程序员前端开发手册
(最后修改日期：2003.9.3)
声明：本手册为前端程序员开发用户界面提供帮助，如有修改会急时更新。若开发不当而造成的损失与提供者无关。
简介：本软件的前端开发将围绕客户端插件BDC进行，BDC内已封装了与server(服务器端程序，后统一称为server)通讯的必要机制，只需合理的调配方法，属性， 事件便可与server通讯。
基本流程：在与server通讯前必须先进行连接操作，BDC提供了Connect方法进行连接，连接后(收到OnConnect事件)必须调用Login进行登录。若未进行上述操作而调用其他接口都可能失败。登录成功后(收到OnLogin事件)用户状态变为房间外状态，此时用户可能调用如RoomList，CateRoomList获取房间列表，在收到OnRoomList后调用如GetRoomName，GetRoomInfo等方法来显示房间列表。之后利用EnterRoom请求进入房间。如果进房成功用户会收到OnEnterRoom事件。然后用户状态变成房间内，此时用户可以调用PubText(聊天)，PriText(悄悄话)，ChangeNick(改名)，ChangeUserDef(换像)，WantVPM(私聊)，RoomList(请求房间列表)，CateRoomList(请求区房间列表)等操作进行房间内的活动，管理员可以调用opGetMic(抢麦)，opKick(踢人)等操作进行管理。如果有新用户进行房间，那么将收到OnNewUser事件，同样聊天，改名等也会收到OnPubText，OnPriText，OnChangeNick等事件，在显示房间用户列表时，可以调用GetUserName，GetUserInfo，GetUserIDByIndex，GetUserNum等方法进行，具体可参阅默认提供的cp.html中的VBScript的DrawUserList过程，在收到OnUpdateUser事件时表示房间内用户信息列表有所改变，必须重新显示用户列表，当然前端程序员可以忽略该事件，自己进行必须的显示工作。
接口列表：
属性
operID roomID SelfID
RegNick RegUserDef  
方法
Connect ChangeNick opKick
Login PubText opGetMic
RoomList PriText opSetName
CateRoomList WantVPM opSetUserDef
EnumRoom ReqVPM opSetLevel
GetRoomName QuitVPM opSetTopic
GetRoomInfo GetTopic opVPM
EnterRoom GetUserName  
QuitRoom GetUserInfo  
GetUserNum ChangeUserDef  
GetUserIDByIndex    
事件
OnInit OnNewUser OnChangeTopic
OnConnect OnChangeNick OnOPVPM
OnLogin OnPubText OnBroadCast
OnError OnPriText  
OnRoomList OnWantVPM  
OnEnterRoom OnVPM  
OnQuitRoom OnQuitVPM  
  OnGetMic  
  OnPutMic  
  OnUpdateUser  
接口资料：
1.属性：
原型：long operID
适用状态：房间内
获取：得到OP的ID号
设置：无
说明：如果有OP操作，那么该属性可以知道是哪个OP的操作
 
原型：long roomID
适用状态：房间内，房间外
获取：获取当前所在的房间的ID号
设置：无
说明：获取当前所在的房间的ID号
 
 
原型：long SelfID
适用状态：房间内
获取：获取当前所在的房间中自己的ID号
设置：无
说明：获取当前所在的房间中自己的ID号
 
原型：BSTR RegNick
适用状态：任何
获取：获取用户最近一次修改的昵称
设置：无
说明：获取用户最近一次修改的昵称，该获取是从注册表中获取，这样可以在用户下次登录时用原来的昵称登录
 
原型：long RegUserDef
适用状态：任何
获取：获取用户最近一次修改的自定义数据
设置：无
说明：获取用户最近一次修改的自定义数据，该获取是从注册表中获取，这样可以在用户下次登录时用原来的自定义数据
 
2.方法：
原型：void Connect(BSTR szIP)
适用状态：连接前
参数：szIP：连接server的IP地址或域名
返回值：无
说明：一般为前端调用的第一个方法，用于连接server，调用该方法后无论成功与否，都会触发OnConnect事件
 
原型：void Login(long nID, BSTR szPassWord, long nUserDef, BSTR szName)
适用状态：连接后(登录前)
参数：nID：用户的登录ID号
　　　szPassWord：ID号对应的密码
　　　nUserDef：用户自定义数据
　　　szName：用户昵称
返回值：无
说明：应该在OnConnect事件中调用此方法，该方法为用户登录server，如果用户为普通游客，请置nID为0，szPassWord为空。该方法调用成功的话会引发OnLogin事件
 
原型：void RoomList()
适用状态：房间外，房间内
参数：无
返回值：无
说明：向server请求全站的房间列表，该房间列表数据会保存在内存中，供GetRoomName，GetRoomInfo等方法使用。该方法的调用成功会触发OnRoomList事件。
 
原型：void CateRoomList(long nCateID)
适用状态：房间内，房间外
参数：nCateID：区ID号
返回值：无
说明：该办法同RoomList，但不同的是它并非向server索取全站的房间列表，而是指定区的房间列表，为了节约server的有限资源，意见使用该方法而非RoomList，注意，如果nCateID <= 0，那么server将返回所有房间的列表
 
原型：long EnumRoom(long nRoomID)
适用状态：房间内，房间外
参数：nRoomID：指定房间的ID号
返回值：返回nRoomID号房间的下一个房间ID号
说明：枚举房间列表(注意，该枚举并非向server请求，而是从内存中查找)，如果nRoomID为0，那么将返回房间列表中第一个房间的ID号，如果返回0表示已经没有房间可以枚举。
 
原型：BSTR GetRoomName(long nRoomID)
适用状态：房间内，房间外
参数：nRoomID：房间的ID号
返回值：房间的名称
说明：获取指定ID号房间的名称
 
原型：long GetRoomInfo(long nRoomID, long nIndex)
适用状态：房间内，房间外
参数：nRoomID：房间的ID号
　　　nIndex：属性索引值
nIndex 意义
0 区号
1 房间最多可容纳多少人
2 房间当前是多少人
返回值：房间的指定的属性的值
说明：获取指定房间的一些属性
 
原型：void EnterRoom(long nRoomID)
适用状态：房间外
参数：nRoomID：房间的ID号
返回值：无
说明：进入指定房间，如果成功，将会触发OnEnterRoom事件
 
原型：void QuitRoom(BSTR szQuitMsg)
适用状态：房间内
参数：szQuitMsg：离开房间时的留言
返回值：无
说明：离开当前房间，如果成功，将会触发OnQuitRoom事件
 
原型：long GetUserNum()
适用状态：房间内
参数：无
返回值：当前房间内的人数
说明：得到当前房间内的人数
 
原型：long GetUserIDByIndex(long nIndex)
适用状态：房间内
参数：nIndex：用户的索引值
返回值：指定nIndex对应的用户的ID号
说明：该方法一般和GetUserNum连用，例如，Ctrl.GetUserIDByIndex(1)，那么将返回第一个用户的ID值，依次类推，从而枚举所有房间内的用户
 
原型：BSTR GetTopic()
适用状态：房间内
参数：无
返回值：当前房间的主题
说明：得到当前房间的主题，如果没有主题，那么将返回空字符串
 
原型：BSTR GetUserName(long nID)
适用状态：房间内
参数：nID：用户的ID号
返回值：指定用户的昵称
说明：获取指定用户的昵称，如果用户不存在，将返回空字符串
 
原型：long GetUserInfo(long nID, long nIndex)
适用状态：房间内
参数：nID：用户的ID号
　　　nIndex：属性索引值
nIndex 意义
0 用户的用户号
1

用户的等级(游客为0)
2 用户的自定义数据
3 语音状态
返回值
0：一般语音状态
1：发言状态
2：私聊状态
返回值：指定属性的值
说明：获取指定用户的属性值
 
原型：void ChangeNick(BSTR szName)
适用状态：房间内
参数：szName：希望修改的昵称
返回值：无
说明：修改昵称，如果修改成功会触发OnChangeNick事件
 
原型：void ChangeUserDef(long nUserDef)
适用状态：房间内
参数：nUserDef：用户自定义数据
返回值：无
说明：修改自定义数据，该数据的具体含义前端程序员决定，如头像，性别等
 
原型：void PubText(long nID, BSTR szMsg)
适用状态：房间内
参数：nID：用户ID号
　　　szMsg：聊天信息
返回值：无
说明：向指定房间内的指定用户公开发送聊天信息，一般该方法会触发OnPubText事件
 
原型：void PriText(long nID, BSTR szMsg)
适用状态：房间内
参数：nID：用户ID号
　　　szMsg：聊天信息
返回值：无
说明：向指定房间内的指定用户悄悄发送聊天信息，如果指定用户不存在或nID为0，那么将向所有人发送，一般该方法会触发OnPriText事件
 
原型：void WantVPM(long nID, BSTR szMsg)
适用状态：房间内
参数：nID：用户ID号
　　　szMsg：私聊请求
返回值：无
说明：向用户发送私聊的请求，如果成功对方会收到OnWantVPM事件
 
原型：void ReqVPM(long nID)
适用状态：房间内
参数：nID：用户的ID号
返回值：无
说明：接收某用户的私聊邀请，如果接收成功会收到OnVPM事件
 
原型：void QuitVPM()
适用状态：房间内
参数：无
返回值：无
说明：用户要求退出私聊，如果成功用户将收到OnQuitVPM事件
 
原型：void opGetMic(long nID)
适用状态：房间内
参数：nID：用户ID
返回值：无
说明：递麦，此方法只有OP调用才有效
 
原型：void opKick(long nID, BSTR szCause)
适用状态：房间内
参数：nID：用户ID
　　　szCause：踢出聊天的理由
返回值：无
说明：踢人，此方法只有OP调用才可能有效，如果调用成功，会收到OnQuitRoom事件，并且事件的nErrorCode参数为1
 
原型：void opSetName(long nID, BSTR szNewName)
适用状态：房间内
参数：nID：用户ID
　　　szNewName：新的昵称
返回值：无
说明：为其他用户改名，只有OP调用此方法才有效，如果调用成功那么会收到OnChangeNick事件
 
原型：void opSetUserDef(long nID, long nUserDef)
适用状态：房间内
参数：nID：用户ID
　　　nUserDef：新用户自定义数据
返回值：无
说明：为其他用户修改自定义数据，只有OP调用此方法才有效，自定义数据含义由前端开发决定，请参阅ChangeUserDef
 
原型：void opSetLevel(long nID, short nLevel)
适用状态：房间内
参数：nID：用户ID
　　　nLevel：新用户等级
返回值：无
说明：修改用户的等级，相当于封临时OP，只有OP调用此方法才可能有效，注意，nLevel只有小于自己的nLevel才行
 
原型：void opSetTopic(BSTR szTopic)
适用状态：房间内
参数：szTopic：房间主题
返回值：无
说明：为房间设置主题，只有房主调用此方法才有效，如果调用成功，将收到OnChangeTopic事件
 
原型：void opVPM(long nID)
适用状态：房间内
参数：nID：用户ID号
返回值：无
说明：和用户强制私聊，只有OP调用此方法才可能有效，如果调用成功将收到OnOPVPM事件
 
3.事件
原型：void OnInit()
适用状态：无
参数：无
返回值：无
说明：该事件尚不会自己触发(正在改进中)，但用户可以在该事件中做一些初始化操作，如果以WEB页形式，可以在<body>的Onload事件中调用它
 
原型：void OnConnect(boolean bConnected)
适用状态：无
参数：bConnected：是否连接成功
返回值：无
说明：在调用Connect方法后，会产生此事件
 
原型：void OnLogin(BSTR szVer)
适用状态：无
参数：szVer：Server版权和版本信息
返回值：无
说明：Login登录成功后会触发该事件
 
原型：void OnRoomList()
适用状态：无
参数：无
返回值：无
说明：得到房间信息，该事件通知用户显示房间列表，在调用了RoomList或CateRoomList会产生此事件
 
原型：void OnError(long nErrorCode, long nID)
适用状态：无
参数：nErrorCode：错误代码
nErrorCode 意义
-1 非正常断线
0 站点客满
1 关闭应用程序
2 正常退出
3 不规范操作
4 不规范操作
5 房间客满
6 录音设备打开失败
7 放音设备打开失败
8 不规范操作，动作过快(刷平)
9 client与server的版本不兼容
10 用户号或密码错误
11 用户不能重复登录
12 指定房间不存在
13 被踢出房间(无法进入房间)
14 进房间所需级别不够
　　　nID：用户ID号
返回值：无
说明：如果触发该事件表示nID用户发生了nErrorCode错误，事实上并非所有该事件都是错误提示，如“关闭应用程序”和“正常退出”，有些错误的发生与nID无关，如，客满，这些错误只可能发送给发生错误的用户自己。
 
原型：void OnEnterRoom()
适用状态：无
参数：无
返回值：无
说明：进入了某房间(EnterRoom)只将触发此事件
 
原型：void OnQuitRoom(long nID, long nErrorCode, BSTR szQuitMsg)
适用状态：无
参数：nID：用户ID号
　　　nErrorCode：错误代码(现在只有0和1)
　　　szQuitMsg：离开的原因
返回值：无
说明：离开房间的事件，该事件指某用户离开聊天室，当然也可能是自己，如果nErrorCode为1，表示用户是被踢出聊天室，此时szQuitMsg是踢出的原因，否则为用户离开房间时的留言
 
原型：void OnNewUser(long nID)
适用状态：无
参数：nID：用户ID号
返回值：无
说明：当有用户进入聊天室时会触发该事件，表示有新用户进入本聊天室，nID为该用户的ID号
 
原型：void OnChangeNick(long nID, BSTR szNewName)
适用状态：无
参数：nID：用户ID号
　　　szNewName：新昵称
返回值：无
说明：当有用户修改昵称(ChangeNick)时会触发此事件，在处理OnChangeNick时，用户可以用GetUserName来获取用户的旧用户名，当事件处理结束后，BDC会自动将用户的昵称更新
 
原型：void OnPubText(long nFromID, long nToID, BSTR szMsg)
适用状态：无
参数：nFromID：源用户ID号
　　　nToID：目标用户ID号
　　　szMsg：聊天信息
返回值：无/td>
说明：调用PubText后，会触发该事件，程序员可以处理此事件来显示聊天信息
 
原型：void OnPriText(long nFromID, long nToID, BSTR szMsg)
适用状态：nFromID：源用户ID号
　　　nToID：目标用户ID号
　　　szMsg：聊天信息
参数：
返回值：无
说明：调用PriText后，会触发该事件，程序员可以处理此事件来显示聊天信息，注意，该聊天信息与OnPubText不同在与，只有nFromID和nToID用户才能收到该事件。
 
原型：void OnGetMic(long nID)
适用状态：无
参数：nID：用户ID号
返回值：无
说明：当一个用户得到发言权时，会触发该事件，nID为得到发言权的用户ID号
 
原型：void OnPutMic(long nID)
适用状态：无
参数：nID：用户ID号
返回值：无
说明：当一个用户放弃发言权时，会触发该事件，nID为放弃发言权的用户ID号
 
原型：void OnWantVPM(long nID, BSTR szMsg)
适用状态：无
参数：nID：用户ID号
　　　szMsg：请求私聊
返回值：无
说明：如果有用户发来私聊的邀请，那么将会触发该事件
 
原型：void OnVPM(long nID1, long nID2)
适用状态：无
参数：nID1：第一个用户的ID号
　　　nID2：第二个用户的ID号
返回值：无
说明：当有两个用户进入私聊时，会触发该事件。
 
原型：void OnQuitVPM(long nID1, long nID2)
适用状态：无
参数：nID1：同OnVPM
　　　nID2：同OnVPM
返回值：无
说明：当两个正在私聊的用户中其中一个用户调用了QuitVPM时，会触发该事件
 
原型：void OnUpdateUser()
适用状态：无
参数：无
返回值：无
说明：当房间内有用户改名，进入，离开，得到或放弃发言权等时，会触发该事件，用户可以在该事件中集中处理用户界面的显示
 
原型：void OnChangeTopic()
适用状态：无
参数：无
返回值：无
说明：当当前房间的主题会改时会触发该事件，用户可以调用GetTopic方法来获取主题
 
原型：void OnOPVPM(long nID1, long nID2)
适用状态：无
参数：nID1：同OnVPM
　　　nID2：同OnVPM
返回值：无
说明：当OP调用opVPM强制与某用户私聊时，会触发该事件
 
原型：void OnBroadCast(long nArea, BSTR szCastInfo)
适用状态：无
参数：nArea：广播范围
nArea 意义
=0 全站广播
<0

地区广播(-nArea为区号)
>0 房间广播(nArea为房间号)
　　　szCastInfo：广播信息
返回值：无
说明：当后台管理进行广播时，可能会触发该事件