莲塘光之流实时交互媒体系统程序员手册

最后修改时间: 2002年6月24日

声明

这段文档的所有信息如有改变将不另行通知。除非特别指出。使用者有义务遵守一切版权规定。该文档任何一部份在未经北京莲塘软件技术有限公司授权之前不得将其用作他用。

文档的有些部分的资料及附带例程还在完善中。有些部分有错误及功能表达上有错误。北京莲塘软件技术有限公司将不会对由该错误所产生的后果或损坏负责。

北京莲塘软件技术有限公司在该文档拥有应用程序、商标、版权及其他知识产权的一切权利。除此之外一切书面上许可并不包括给予应用程序、商标、版权及其他知识产权的所有权。

北京莲塘软件技术有限公司保留一切权利。

简介

本系统的目标是提供一套基于因特网的用户实时交流平台底层框架。本框架适用于建立基于因特网的实时网络教育平台、网上会议系统、语音聊天室、企业客服系统、网上议价及销售平台等。

体系结构

本系统可分为两部份：服务器端及用户端。

服务器端提供了用户注册及用户身份认证，房间（教室/会议室/聊天室）管理，各种用户实时交流功能、日志、Web服务等项功能。服务器端的核心是莲塘光之流实时交互媒体服务程序（以下简称为：服务程序）。服务程序接收IE浏览器发来的用户请求和用户端控件(见下)发来的请求，并自动区别处理，最后视情况将处理后的结果返还用户端，或丢弃请求，又或直接断开与用户端的连接。服务器对于用户IE浏览器发来的请求，总是查找相应的网页文件，并传送给用户IE浏览器，如果文件不存在，则按照HTTP协议返回错误信息。这与普通的Apache或IIS完全兼容。服务器对于用户端控件发来的请求的处理相对要复杂很多，大致可分为用户注册，用户登录，用户请求，用户管理，房间管理等部分。用户通过登录认证之后，控件与服务器会一直保持连线，一直到用户退出登录才断开连接。服务程序可同时处理数百至数千个这样的用户请求。

用户端的核心是一组API(应用开发接口)，这组API被封装在一个ActiveX控件（以下简称：用户端控件）中，用户端控件的运行环境是IE浏览器5.0版本以上。通过本系统提供的用户端应用开发接口，可以根据用户的不同需要，结合本系统已有功能，开发出各种不同外观、不同效果的各类用户界面及相应的功能。

系统工作流程

在本系统的一般性应用中，工作流程如下：

1. 用户端通过IE浏览器访问运行本系统的服务器网址，下传最初的用户登录网页，该网页中包含了供用户键入用户号及用户密码的输入及提交界面。

2. 当用户输入用户登录信息并提交时，用户登录网页将用户登录信息保存在后台（方式很多，例如作为全局变量）并加载包含用户端控件的页面。

3. 包含用户端控件的页面加载完成后，控件自动初始化，并触发初始化完成事件(OnInit事件)，告知初始化对用户系统的检测结果。

4. 用户端网页脚本程序调用用户端控件的连接方法(Connect方法)发起对服务器端的连接。

5. 服务程序接收到该用户端的连接请求之后，检查该用户端对应IP的最大连接数没有达到系统上限，则接受用户端的连接请求。如果连接成功，用户端应收到连接成功事件(OnConnect事件)，否则会收到错误事件(OnError)。

6. 用户端网页脚本程序调用用户端控件的登录方法(Login方法)，以用户号及用户密码作为参数，向服务器端请求登录。

7. 服务程序接收到用户登录数据后，进行用户验证。如果验证通过，返回用户登录成功及用户的级别、登录次数、上次登录时间等信息(SelfInfo、lastVisitDate)；如果验证失败，返回用户登录失败并主动断开与用户端的网络连接。无论是否通过验证，用户端应收到登录结果事件(OnLogin)。

8. 用户登录成功后，处于“在房间外”的状态。这时候可做的操作有：请求房间列表(RoomList)、修改用户注册名及密码(ChangePasswd)、新建房间(AddRoom)（需要有新建房间的权限）、进入房间(EnterRoom)；站长还有更改用户密码(ChangePasswd)、任命/撤消管理员(ChangeUserLevel)、全站/分区/房间文字广播(OPCastText)、建立永久房间(AddRoom)、更改房间区号/序号(ChangeRoomCate)、删除房间(DelRoom)等功能。

9. 用户发出进入房间的请求，服务程序收到请求后验证房间否在与否及用户权限，通过验证则用户进入房间，否则返回进房间失败的错误信息。无论成功与否，用户端接收到进入房间事件(OnEnterRoom)。如果进房成功，用户端还收到房间状态事件(OnRoomStat)、新用户进入事件(OnNewUser)。

10. 用户端控件在收到新用户进入事件，用户状态改变事件(OnUserStat)、用户改名事件(OnChangeNick)、用户退出事件(OnQuitRoom)、得到话筒事件(OnGetMic)、正在请求话筒事件(OnWantMic)(注)、释放话筒事件(OnDropMic)、进入语音私聊事件(OnVPMEnter)、退出语音私聊事件(OnVPMLeave)、进入管理员强制语音私聊事件(OnVPMOpEnter)时，用户端控件内部维护的用户名单均会有所更新，开发者可以选择在这些事件发生时刷新用户名单。刷新用户名单要用到的属性和方法有：cUser, Nickbyid, UserDef, UserLevel, UserInfo, Idx2id。

11. 用户在房间内可以发送文字(PubText,PrivText)、语音发言、改昵称(ChangeNick)、邀请语音私聊(VPMRequest )、接受语音私聊(VPMPermit) 、退出语音私聊(VPMLeave)、关闭语音文字或私聊接收(SetSelfPriv)、屏蔽/允许某用户的语音文字的发送或接收(SetUserRela)、请求房间列表(RoomList)、查询用户信息(QueryUser)等。

用户端

用户端又称为前端，用户端的状态包括：连接前、登录前、在房间外、在房间内，不同的状态下可用的方法、有效的属性和可能触发的事件各有差异。下表列出各状态下控件的全部属性方法和事件。

	连接前	登录前	在房间外	在房间内
属性	bConnected	bConnected	bConnected regNick createDate lastVisitDate bInRoom cRoom	bConnected regNick createDate lastVisitDate bInRoom cRoom	bInVPM selfUID cUser roomID talkMode
方法	Connect	Login Register SetParam NewPasswd	EnterRoom AddRoom Logout ChangeRoomCate SetUserDef EnumCate EnumRoom RoomName RoomInfo RoomCUser RoomList RoomIdx2id RoomCate RoomSort RoomTopic DelRoom ChangeUserLevel ChangePasswd SelfInfo SetTopic OPCastText NewPasswd new	QuitRoom Logout ChangeNick PubText PrivText QueryUser Idx2id Nickbyid UserDef SetUserDef SetUserRela SetSelfPriv UserLevel UserInfo SelfInfo RoomInfo EnumCate EnumRoom QueryUser	RoomName RoomCUser RoomList RoomIdx2id RoomCate RoomSort RoomTopic VPMRequest VPMPermit VPMLeave OPKick OPGetMic OPSetNick OPSetUserPriv OPForceVPM OPSetRoomParam OPBanIP OPLockRoom SetTopic
事件	OnInit	OnError OnConnect OnLogin OnLogout OnRegister new OnNewPasswd	OnError OnLogin OnRoomAdd OnChangeRoomCate OnQuitRoom OnRoomList OnRoomDel OnChangeUserLevel OnChangePasswd OnNewPasswd new	OnError OnEnterRoom OnUserStat OnGetMic OnWantMic OnDropMic OnNewUser OnChangeNick OnPubText OnPrivText OnQueryUser	OnRoomStat OnRoomList OnSelfStat OnQueryUser OnVPMRequest OnVPMEnter OnVPMLeave OnVPMOpEnter OnCastText OnUpdateUL

属性

long cUser
适用状态：房间内
描述：房间内用户个数。用户列表在进入房间时自动获得，用户列表的接收过程是在收到OnEnterRoom后开始的。在收到第一个OnNewUser事件时，用户名单已经就绪，读得的cUser即是房间内真实的用户个数。

long cRoom
适用状态：房间外、房间内
描述：房间列表中的房间个数。房间列表由RoomList方法向服务器请求，服务器的房间列表全部送达用户端时，会触发OnRoomList事件，至此cRoom值有效。

long roomID
适用状态：房间内
描述：当前所在房间的房间号。在进入房间时房间号就立刻有效。

boolean bInVPM
适用状态：房间内
描述：用户处于语音私聊状态时，此属性值为真。

BSTR regNick
适用状态：房间外、房间内
描述：如果以注册用户身份登录，在登录成功后，此属性值为注册用户保留在服务器端的注册昵称。如果为游客身份登录，在本地注册表保留用户昵称的开关置1时，此属性值为本台计算机当前登录用户上次采用的游客昵称。游客昵称在本地注册表保留请参见SetParam。

DATE createDate
适用状态：房间外、房间内
描述：如果以注册用户身份登录，在登录成功后，此属性值为注册用户保留在服务器端的帐号建立日期。对于游客此属性没有意义。

DATE lastVisitDate
适用状态：房间外、房间内
描述：如果以注册用户身份登录，在登录成功后，此属性值为注册用户保留在服务器端的上次登录日期。对于游客此属性没有意义。

boolean bInRoom
适用状态：房间外、房间内
描述：此属性值为真时表明目前处在房间内，为假时若属性bConnected为真，则目前处于房间外。

long selfUID
适用状态：房间内
描述：自己的用户号。用户号由1开始，用户号为0则表示“所有人”，在此属性值中，0是无效值，如果当前处于房间内，此属性性不可能为0。

boolean bConnected
适用状态：登录前、房间外、房间内
描述：此属性为真则目前与服务器正处于连接状态。

long talkMode
适用状态：间内
描述：此属性为0则目前处于自由讨论模式，为1则处于主席发言模式。进入及退出主席发言模式可以由OPSetUserPriv来指定。

方法

void Login(long ugidLo, BSTR logstring)
适用状态：登录前
参数：
ugidLo 用户注册ID号的低32位。
logstring 与用户注册ID号对应的登录验证串，通常为用户密码。
描述：在用户端收到OnConnect事件，与服务器成功建立连接之后，调用此方法进行用户登录。无论登录成功与否，服务器端会触发OnLogin事件。例外：在用户登录过程中如果网络连接意外断开，则不会触发OnLogin事件，意外错误事件OnError会被触发。

void EnterRoom(long roomid, long userlevel, BSTR usernick)
适用状态：房间外
参数：
roomid 请求进入房间的房间号。
userlevel 进入房间时希望的用户级别。
usernick 用户进入房间时的昵称。长度限制在16个汉字。
描述：在用户处于房间外时，可以调用此方法请求进入指定房间号的房间。进入房间时的用户级别等于或小于用户的实际级别。当设定的级别高于用户实际级别时，系统会将进入房间时的自动级别调整为用户的实际级别。此方法的用户昵称即为用户进入房间后的实际显示昵称。如果进房请求成功，则OnEnterRoom事件被触发，如果失败OnError事件被触发。

void Connect()
适用状态：连接前、登录前、房间外、房间内
描述：在连接前发起向服务器的连接请求。如果连接成功，OnConnect事件将被触发。若失败则OnError事件将被触发。如果连接已经建立，再次调用此方法，则用户端将首先断开与服务器的连接，再次发起连接请求。

void AddRoom(BSTR roomname, short permanent, short invisible, short max_user, short mic_count, short mic_time, short vhostmaster, short voperator, short vuser, short vguest)
适用状态：房间外
参数：
roomname 要新建的房间名称，允许与已经存在的房间重名，最长32汉字。
permanent 有效值为0/1，是否为永久房间，值1仅对站长建房有效。
invisible 房间是否可见，此值目前保留未用。
max_user 房间最大用户数目。游客在房间内人数为此值减5时，即不能入内。其他级别用户按级别决定是否可以入内。
mic_count 话筒个数有效值为1/4，目前话筒个数应置为1，其它数目仅供测试之用。
mic_time 话筒持有时间，有效值为1/16，乘5为实际的话筒时间。
vhostmaster 新建房间内站长的权限
voperator 新建房间内管理员的权限
vuser 新建房间内用户的权限
vguest 新建房间内游客的权限
描述：调用此方法向服务器请求新建房间，调用者应有建立房间的权限，本权限在服务器端设定。各级用户权限为完全权限时值为15，无权限时值为0。无论建房间成功与否，事件OnRoomAdd将被触发。此方法的接口参数不保证在将来不作更改。

void QuitRoom(BSTR msgtext)
适用状态：房间内
参数：
msgtext 退出留言
描述：请求退出当前房间。在适用状态时调用此方法总是成功。完成用户退出房间后，将会触发OnQuitRoom事件。

void QueryUser(long uid, long reserved)
适用状态：房间内
参数：
uid 待查询的用户号。
reserved 保留为0。
描述：查讯用户注册ID号。如果自身注册权限(注意不是房间内的权限)与待查用户的权限相同或更高，则查询结果为该用户的实际用户注册ID号；如果对方是游客或级别高于自己，则结果为0。查询结果通过OnQueryUser事件返回。

void Logout()
适用状态：登录前、房间外、房间内
描述：请求退出用户登录。在适用状态时调用此方法总是成功。完成用户退出登录后，将会触发OnLogout事件。

void ChangeRoomCate(long roomid, short cateno, short sortno)
适用状态：房间外
参数：
roomid 房间号。
cateno 分类号，有效值1/255。
sortno 序号，有效值0/255。
描述：该变一个已经存在的房间的分类和排列次序。本方法仅站长可完全调用。为了便于管理，房间按分类号进行分类，同一分类参考序号和房间号进行排序。排序的规则为：首先参考序号，在序号一致时查考分类号。本地缓存的房间列表是按区号由小到大排列的，同区的房间按序号由小到大排列，同区同序号的房间按房间号由小到大排列。房主仅可以利用此方法改变自己房间的序号。（房主的为级别大于1，用SelfInfo取得的区号和房号与对应房间区号及房号完全相等的管理员）

void ChangeNick(BSTR usernick)
适用状态：房间内
参数：
usernick 用户新昵称。
描述：请求改变昵称。在服务器接受请求后房间内所有用户会收到OnChangeNick事件。

void PubText(long userid, BSTR msgtext)
适用状态：房间内
参数：
userid 用户号。
msgtext 文字信息，长度120汉字。
描述：向指定用户号的用户在公众可见的情况下发文字信息。在服务器接受请求后房间内所有用户会收到OnPubText事件。用户号置为0表示向不确定用户（所有人）发送文字信息。

void PrivText(long userid, BSTR msgtext)
适用状态：房间内
参数：
userid 用户号。
msgtext 文字信息，长度120汉字。
描述：向指定用户号的用户在公众不可见的情况下发文字信息。在服务器接受请求后自己及指定用户会收到OnPrivText事件。

long Idx2id(long idx)
适用状态：房间内
参数：
idx 用户序号，为0到cUser-1。
描述：指定用户序号得到用户号，用于枚举房间内的用户号。用户序号始终连续。用户号在用户进入房间时分配，不保证连续。用户号是用户在房间内的唯一标识。

BSTR Nickbyid(long uid)
适用状态：房间内
参数：
uid 用户号
返回值：用户号对应的用户昵称
描述：通过用户号取得对应用户的昵称，不同用户的用户昵称可以相同，称之为重名，即俗称的同名同姓。在本系统中，房间内的用户唯一标识为用户号而非昵称。

long UserDef(long uid)
适用状态：房间内
参数：
uid 用户号
返回值：用户号对应的用户自定义数据
描述：通过用户号取得对应用户的自定义数据。

void SetUserDef(long udata)
适用状态：房间内
参数：
udata 用户自定义数据
描述：设置自身的用户的自定义数据。在服务器接受请求后房间内所有用户会收到OnChangeNick事件。触发此事件的原因为用户自定义数据与用户昵称存放在同一处。用户自定义数据常用来表示用户昵称外的其他用户特征，如用户的性别，头像等等。

short EnumCate(short cate)
适用状态：房间外、房间内
参数：
cate 分类号
返回值：下一个分类号
描述：枚举房间列表中的全部分类。在首次触发OnRoomList事件后生效。分类号参数为0则返回第一个分类的分类号；分类号参数为有效分类号时，返回相邻的下一个分类号；当返回的分类号为0时，说明作为参数的分类号无效，或已经是房间列表中的最后一个分类号。

long EnumRoom(short cate, long rid)
适用状态：房间外、房间内
参数：
cate 分类号
rid 房间号
返回值：下一个房间号
描述：枚举房间列表中的指定分类的全部房间。在首次触发OnRoomList事件后生效。分类号参数必须为有效分类号，不能为0。房间号参数为0则返回对应分类的第一个房间号；房间号参数为有效房间号时，返回同分类相邻的下一个房间号；当返回的房间号为0时，说明作为参数的房间号或分类号无效，或已经是对应分类的最后一个房间号。

BSTR RoomName(long rid)
适用状态：房间外、房间内
参数：
rid 房间号
返回值：房间号对应的房间名称
描述：返回房间号对应的房间名称，当房间号不存在时，返回空名称。

long RoomCUser(long rid)
适用状态：房间外、房间内
参数：
rid 房间号
返回值：房间号对应的房间人数
描述：返回房间号对应的房间人数，当房间号不存在时，返回-1。建议用RoomInfo(rid,9)替代。

void RoomList()
适用状态：房间外、房间内
描述：请求房间列表。在适用状态下，服务器端返回房间列表，房间列表被用户端控件缓冲，当用户端接受全部房间列表后，触发OnRoomList事件。如果频繁调用本事件，但服务器端并没有新的房间列表生成，服务器将自动丢弃本请求，不会触发OnRoomList事件。

long RoomIdx2id(long ridx)
适用状态：房间外、房间内
参数：
ridx 房间索引号
返回值：房间索引号对应的房间号(rid)
描述：返回房间索引号对应的房间号。房间索引号由0到cRoom-1。索引号为用户端房间列表排序后的绝对下标。

short RoomCate(long rid)
适用状态：房间外、房间内
参数：
rid 房间号
返回值：房间号对应的分类号
描述：返回房间号对应的分类号。建议用RoomInfo(rid,7)替代。

short RoomSort(long rid)
适用状态：房间外、房间内
参数：
rid 房间号
返回值：房间号对应的序号。
描述：返回房间号对应的序号。建议用RoomInfo(rid,8)替代。

void DelRoom(long rid)
适用状态：房间外
参数：
rid 房间号
描述：用户级别为站长时方有权调用此方法，向服务器请求删除指定房间号的房间。无论房间是否被删除，用户端总会触发OnRoomDel事件。

void SetSelfPriv(long vocr, long pubtr, long prvtr)
适用状态：房间内
参数：
vocr 语音接收，有效值-1/0/1
pubtr 公聊文字接收，有效值-1/0/1
prvtr 私聊接收，有效值-1/0/1
描述：请求设定自身有选择的接收信息。当对应参数值为-1时表示不改变参数原值，当参数值为0时表示关闭对应接收，为1表示开启对应接收。在服务器接受请求后房间内所有用户会收到OnSelfStat事件。

void VPMRequest(long uid, BSTR msg)
适用状态：房间内
参数：
uid 用户号
msg 邀请的文字信息
描述：向用户号对应的用户发出语音私聊邀请。如果对应用户允许私聊接收，会收到OnVPMRequest事件。

void VPMPermit(long uid)
适用状态：房间内
参数：
uid 用户号
描述：当收到用户号对应的用户发来的语音私聊邀请后，通过调用此方法回应对方的语音私聊邀请。双方会收到OnVPMEnter事件，进入两人语音私聊。

void VPMLeave()
适用状态：房间内
描述：在进入语音私聊之后，调用此方法离开语音私聊。任何一方调用此方法，语音私聊双方均会收到OnVPMLeave事件，退出语音私聊。

void Register(BSTR passwd, BSTR nick, BSTR xmlinfo)
适用状态：登录前
参数：
passwd 用户登录密码
nick 用户注册昵称
xmlinfo 用户其他注册信息(保留)
描述：调用此方法申请一个注册用户号。如果注册成功，OnRegister事件会被触发。否则服务器自动断开连接。

void ChangeUserLevel(long ugidLo, short ulevel, short cateid, long rid)
适用状态：房间外
参数：
ugidLo 用户注册ID号
ulevel 用户级别0..3,15
cateid 分类号
rid 房间号
描述：用户级别为站长(15)时方有权调用此方法，向服务器请求改变用户注册ID号指定用户的用户级别及管理权范围。用户级别目前为0至3级和15级，分别对应游客/用户/网管/高管/站长。管理权范围仅对网管及网管以上级别有效。分类号和房间号均为0时，管理权为全站。分类号不为0，房间号为0时，管理权为该分类号下的全部房间。房间号为非0时，管理权为房间号对应的单个房间。无论用户级别修改成功与否，均会触发OnChangeUserLevel事件。

BOOL ChangePasswd(long ugidLo, BSTR oldpassword, BSTR newpassword, BSTR nick)
适用状态：房间外
参数：
ugidLo 用户注册ID号，站长之外的用户仅可填写自己的用户注册ID号
oldpassword 用户的旧密码
newpassword 用户的新密码
nick 用户的新注册昵称
描述：向服务器请求改变对应用户注册ID号指定用户的用户密码及注册昵称。仅用户级别为站长时可以改变其他用户。无论用户密码及昵称修改成功与否，均会触发OnChangePasswd事件。

long UserLevel(long uid)
适用状态：房间内
参数：
uid 用户号
描述：得到用户号对应的用户级别。建议用UserInfo(uid, 0)代替。

long SelfInfo(long infoidx)
适用状态：房间外、房间内
参数：
infoidx 信息索引号
有效值
1: 用户级别
2: 区管标识
3: 房管标识
4: 用户经验值
5: 上站次数
6: 用户注册ID号
描述：得到与索引号对应的自身用户信息。

void OPKick(long uid, BSTR msg)
适用状态：房间内
参数：
uid 用户号
msg 踢出理由
描述：踢出指定用户。网管以上适用。踢出规则：用户或游客首次被踢出，将在踢出时间一内不得登录服务器，超过时间一再次登录成功后，在时间二内又被踢出，将在时间三内不得登录服务器，并且时间二重新计时。这个三个时间参数在服务器配置文件内进行配置。

void OPGetMic(long fromuid, long touid)
适用状态：房间内
参数：
fromuid 被夺取话筒的用户号
touid 得到话筒的用户号
描述：转移话筒。网管以上适用。在多个话筒时fromuid为0则由系统决定夺取多个正在发言用户中某用户的话筒，非0则夺取指定用户的话筒。touid为0则抢下话筒后不交给任何用户，用户可自行争夺，刚被夺去话筒的用户优先权最低，touid为有效用户，则该用户得到话筒，发言时间为不限时长。

void OPSetNick(long uid, BSTR nick)
适用状态：房间内
参数：
uid 用户号
nick 用户昵称
描述：强行更改昵称。网管以上适用。

void OPSetUserPriv(long uid, short vout, short vin, short tout, short tin, short ulevel)
适用状态：房间内
参数：
uid 用户号
vout -1/0/1 语音发送
vin -1/0/1 语音接收
tout -1/0/1 文字发送
tin -1/0/1 文字接收
ulevel -1/0..3 用户级别
描述：网管以上适用。用户号为非0时，修改用户的语音及文字接受发送(-1为不修改)，及用户级别。N级网管最多将指定用户提升为N-1级。N级网管无权对N级及以上网管操作。此处指的级别是进入房间后的级别，与用户实际级别无关。用户号为0时，用于设置进于或退出主席发言模式，语音及文字的发送接收对低于设置者级别的所有级别同时生效。进入主席发言模式应将参数中的发送或接收参数设置为不全为1且不全为0，退出主席模式可设置全1或全0，用户级别将被忽略。

void OPForceVPM(long uid)
适用状态：房间内
参数：
uid 用户号
描述：强行与指定用户语音私聊。网管以上适用。

void OPCastText(short cateid, long rid, BSTR castmsg)
适用状态：房间外
参数：
cateid 分类号
rid 房间号
castmsg 广播的文字信息
描述：此方法要求具有站长权限。向指定的房间或分类或全站发出广播文字信息。当分类号及房间号均为0时，为全站广播。当分类号非0，房间号为0时，为全分类（区）广播。当房间号为0时，为房间广播。被广播的有效范围内的所有在房间内用户均收到OnCastText消息。

void OPSetRoomParam(short locked, short invisble, short mic_time, short min_ulevel)
适用状态：房间内
参数：
locked 锁住
invisble 不可见(保留)
mic_time 话筒持有时间
mic_ulevel 最小进房间级别
描述：改变房间状态。此方法要求具有网管以上的权限。对进房间的级别限制只能低于自身级别。房间内所有用户将收到 OnRoomStat 事件。

void OPBanIP(long uid, BSTR msg)
适用状态：房间内
参数：
uid 用户号
msg 封IP的理由
描述：封指定用户IP。站长适用。当IP被封，只有在服务器的IP封锁文件中删除该IP封锁方可恢复访问权，服务器重启动后，IP封锁文件中的IP封锁依然有效。

void SetUserRela(long uid, short svoc, short rvoc, short stxt, short rtxt)
适用状态：房间内
参数：
uid 用户号
svoc 发送语音信息，有效值:-1/0/1
rvoc 接收语音信息，有效值:-1/0/1
stxt 发送文字信息，有效值:-1/0/1
rtxt 接收文字信息，有效值:-1/0/1
描述：设置用户规则。设置自己对指定用户的接收及发送规则。参数值为-1表示不改变当前规则，为0表示禁止，为1允许。此调用此方法将收到 OnUserStat 事件。可以用此方法屏蔽某些用户的骚扰。

void SetParam(long funcnum, long value)
适用状态：连接前、登录前、房间外、房间内
参数：
funcnum 功能号，有效值:1/3/4
value 值

功能号	值	描述
1	0/1	是否保存改名后的昵称到本地注册表。缺省为0
3	0/1..4	用户名单是否按持有话筒排序。缺省为0不排序；1为拿话筒的排最前面；2为拿话筒的排最前面，其余按用户级别排；3为按用户级别排，拿话筒的排本级别的最前面；4为按用户级别排
4	-99..-1/0/1..999	OnUpdateUL事件开关。为负数为设置两次事件的触发时间间隔，缺省为-5，意指至少5秒触发一次刷新事件，0为不触发本事件，正数为启用优化刷新的人数下限，当超过该正数的人数时，进行优化刷新。缺省为0
5	1..65535	显式设置语音端口号

描述：用户端参数开关。

long RoomInfo(long rid, long infoidx)
适用状态：房间外、房间内
参数：
rid 房间号
infoidx 房间信息索引号

房间信息索引号	值	描述
0	0..15	房间类型。0为游客自建，1为用户自建，2为管理员自建，3为站长自建，15为永久房间，其它保留
1	2..上限	房间人数上限
2	1/4	话筒个数
3	5..80	发言时间（秒）
4	0/1	房间锁住置1
5	0/1	房间不可见置1（保留）
6	0..15	准入用户级别，目前只用到0..3
7	1..255	房间区号
8	0..255	房间序号
9	0..上限	房间当前人数

描述：取得指定房间的房间信息。

long UserInfo(long uid, long infoidx)
适用状态：房间内
参数：
uid 用户号
infoidx 用户信息索引号

用户信息索引号	值	描述
0	0/15	用户级别。0:游客 1:用户 2:网管 4:高管 15:站长其他保留
1	1/2/3/4	无话筒/试图请求话筒/持有话筒/语音私聊
2	0..3	无文字/向对方发送/从对方接收/全收发
3	0..3	无语音/向对方发送/从对方接收/全收发
6	0..15	发送接受权。为数字组合：1=文字接收 2=文字发送 4=语音接收 8=语音发送
7	0/1	置1为允许私聊接收
8	0/1	置1为允许文字公聊接收
9	0/1	置1为允许语音接收
10	0/1	置1为新用户
11	1..上限	用户注册ID号 new
12	1..上限	用户经验值 new

描述：取得指定用户的用户信息。

void QueryUser(long uid, long funcid)
适用状态：房间内
参数：
uid 用户号
funcid 功能号(保留为0)
描述：查询指定用户的注册信息。如果自身具有查询权限，被查询用户为注册用户，则查询成功；否则查询失败。无论查询成功与否，均会触发OnQueryUser事件。

void OPLockRoom(BSTR roompass)
适用状态：房间内
参数：
roompass 房间密码(长度最大为16字节)
描述：用密码锁住房间或解锁。当房间密码不为空时，锁住房间；密码串为空则为解锁。必须具有网管以上权限方可成功锁房/解锁。成功后会触发OnRoomStat事件，广播房间当前状态。

void SetTopic(BSTR topic)
适用状态：房间内
参数：
topic 房间议题(长度最大为250字节)
描述：设置修改房间议题。每个用户进入房间时，均可通过RoomTopic得到当前房间的议题。必须具有网管以上权限方可成功设置房间议题。成功后会触发OnRoomStat事件，广播房间当前状态，应通过RoomTopic取得当前的议题。

void RoomTopic(long rid) new
适用状态：房间外、房间内
参数：
rid 房间号
描述：取得指定房间的议题。在首次OnRoomList之后生效果。通常在OnRoomList或OnRoomStat事件中取得并显示议题。

void NewPasswd(long ugid, long gpcode) new
适用状态：登录前、房间外
参数：
ugid 用户注册ID号
pgcode 密码重设码
描述：如果密码遗忘，任何注册用户可以在登录前用本方法重新生成密码。无论用户注册ID号和密码重设号(在OnRegister中获得)正确与否，均会触发OnNewPasswd事件；在房间外时，仅站长有权力调用NewPasswd方法生成ugid对应的用户的密码重设号，此时pgcode由站长指定。如果设置成功，用户密码将与pgcode相同。无论何时，pgcode与ugid均不能为0。

事件

void OnInit(long status)
发生状态：连接前
参数：
status 初始化状态码，值：0/-1/其它。对应表示：语音正常/不支持语音/语音可能不正常
描述：用户端控件初始化完成后主动触发本事件。

void OnError(long errcode)
发生状态：连接前、登录前、房间外、房间内
参数：
errcode 错误码

错误码	含义
259	无此房间
260	房间客满
263	房间已经锁住
264	非正常断线
1007	非法操作
1010	与服务器的连接已断开
1013	放音设备打开失败
1014	内存不足，操作取消
1016	录音设备被占用，请检查是否有别的程序正在使用录音设备，关掉该程序再重试请求话筒
10053	与服务器的连接已断开
10054	与服务器的连接已断开
10061	连接服务器失败

描述：发生网络或设备错误及进入房间出错时触发本事件。

void OnLogin(long serverid, long userlevel, BSTR product, BSTR regurl)
发生状态：登录前、房间外
参数：
serverid 服务器ID。为0则登录失败，userlevel为错误码
userlevel 用户级别
product 产品信息
regurl 注册网址

错误码	含义
0	用户登录失败
1	用户注册ID或密码不对
2	用户已经上站，不能重复登录

描述：当用户登录完成时触发本事件返回登录结果。

void OnConnect()
发生状态：登录前
描述：连接服务器成功触发本事件。

void OnEnterRoom(long userid, BSTR roomname)
发生状态：房间外
参数：
userid 用户号。
roomname 房间名称。
描述：自己进入房间时触发本事件，用户号为自己在当前房间的用户号。

void OnRoomAdd(long errcode, long roomid)
发生状态：房间外
参数：
errcode 错误号。0/256/257/258/768，成功/无效房间名/房间数达到上限/建立房间失败/没有权限
roomid 房间号。
描述：建立房间时触发本事件。如果建房间成功，roomid为新房间的房间号。如果在服务器配置文件中打开建房者为房间管理员开关，则具有此房间的管理权。

void OnLogout(long errcode)
发生状态：房间外、房间内
参数：
errcode 错误码

错误码	含义
0	正常退出登录
264	非正常断线
265	被管理员踢出，稍后再试
266	过多动作（刷屏或变速齿轮等），系统保护性强令离站
267	游客身份登录，由于在线参观时间已经用尽，被系统强令离开
268	在房间外逗留时间过长，已经自动离站
512	用户名非法，已经断开
768	没有权限，已经断开

描述：退出登录或被管理员/系统踢出时触发此事件。

void OnUserStat(long userid, long userstat)
发生状态：房间内
参数：
userid 用户号。
userstat 用户状态值（无说明）。
描述：设置用户规则后触发本事件，用户名单数据可能被改变，在线人线较少时可以在此事件中重绘在线名单。

void OnRoomStat(short permanent, short locked, short invisible, short max_user, short mic_count, short mic_time)
发生状态：房间内
参数：
permanent 永久房间。0/1，置1为永久房间
locked 锁住。0/1，置1为锁住
invisble 不可见(保留)
mic_count 话筒个数1/4
mic_time 话筒持有时间
描述：自己进入房间时触发本事件，管理员改变房间属性时触发本事件。

void OnChangeRoomCate(long errcode, long roomid)
发生状态：房间外
参数：
errcode 错误码。0:无错误，768:没有权限
roomid 房间号。
描述：站长改变房间分类号及序号时触发本事件返回修改结果。

void OnGetMic(long userid)
发生状态：房间内
参数：
userid 用户号。
描述：用户得到话筒时触发本事件。

void OnWantMic(long userid)
发生状态：房间内
参数：
userid 用户号。
描述：当服务器配置文件内显示请求话筒开关打开时，请求话筒未成功，房间内所有用户收到本事件。

void OnDropMic(long userid)
发生状态：房间内
参数：
userid 用户号。
描述：用户释放话筒时触发本事件。如果该用户原本持有话筒，则房间内所有用户收到本事件，否则仅userid用户本身收到本事件。

void OnNewUser(long userid, BSTR usernick)
发生状态：房间内
参数：
userid 用户号。
usernick 用户昵称。
描述：新用户进入时，房间内所有用户收到本事件。
void OnChangeNick(long userid, BSTR newnick, BSTR oldnick)
发生状态：房间内
参数：
userid 用户号。
newnick 用户新昵称。
oldnick 用户旧昵称
描述：用户改名时，房间内所有用户收到本事件。

void OnPubText(long fromuid, long touid, BSTR msgtext)
发生状态：房间内
参数：
fromuid 文字发送用户号。
touid 文字接收用户号。
nsgtext 文字信息。
描述：用户fromuid发出文字公聊时，房间内所有用户收到本事件。

void OnPrivText(long fromuid, long touid, BSTR msgtext)
发生状态：房间内
参数：
fromuid 文字发送用户号。
touid 文字接收用户号。
nsgtext 文字信息。
描述：用户fromuid向touid发出文字私聊时，fromuid和touid用户收到本事件。

void OnQueryUser(long uid, long ugid)
发生状态：房间内
参数：
uid 用户号。
ugid 用户号对应的用户注册ID号。
描述：用户查询(QueryUser)的返回结果。

void OnQuitRoom(long errcode, BSTR oldnick, BSTR quitmsg)
发生状态：房间内
参数：
errcode 错误号。
oldnick 用户旧昵称。
quitmsg 退出留言

错误码	含义
0	正常退出房间
262	关掉浏览器跑掉
264	非正常断线
265	被管理员踢出，退出留言quitmsg为管理员踢人理由
266	过多动作（刷屏或变速齿轮等），系统保护性强令离开
267	游客身份登录，由于在线参观时间已经用尽，被系统强令离开

描述：用户自行离开房间，房间内所有用户将收到本事件。被系统及管理员踢出时，除被踢用户外所有用户将收到本事件，被踢用户收到OnLogout事件。

void OnRoomList(long crooms)
发生状态：房间外，房间内
参数：
crooms 房间列表中的房间个数。
描述：调用RoomList方法向服务器请求房间列表后将收到本事件作为房间列表接收完毕的回应。

void OnRoomDel(long errcode)
发生状态：房间外
参数：
errcode 错误号。0/259/768，成功/房间不存在/没有权限
描述：站长在调用了DelRoom方法后，服务器返回操作结果。

void OnSelfStat(long vocr, long pubtr, long prvtr)
发生状态：房间内
参数：
vocr 语音接收。0/1
pubtr 文字公聊接收。0/1
prvtr 私聊接收。0/1
描述：自己调用SetSelfPriv后触发本事件返回自身的当前设置。各参数为0表示接收关闭，为1表示接受允许。

void OnVPMRequest(long uid, BSTR msg)
发生状态：房间内
参数：
uid 用户号。
msg 语音私聊邀请文字。
描述：被邀请用户接收到本事件，uid参数为邀请者的用户号。邀请者通过调用VPMRequest使选定的用户触发本事件。在被选定用户关闭私聊接收时，本事件不可以发生。

void OnVPMEnter(long uid0, long uid1)
发生状态：房间内
参数：
uid0 用户号0。
uid1 用户号1。
描述：被邀请语音私聊的用户接受邀请后，房间内所有人均收到本事件，表明邀请者与被邀请者已经进入语音私聊状态。

void OnVPMLeave(long uid)
发生状态：房间内
参数：
userid 用户号。
roomname 房间名称。
描述：语音私聊中的任何一方调用VPMLeave离开语音私聊，房间内所有人均收到本事件，表明uid指定的用户已经离开语音私聊。

void OnVPMOpEnter(long opuid, long uid)
发生状态：房间内
参数：
opuid 管理员用户号。
uid 用户号。
描述：管理员调用OPForceVPM方法，房间内所有人均收到本事件，表明opuid和uid开始由管理员主动发起的语音私聊。

void OnRegister(long ugidlo, long ugidhi, long gpcode) new
发生状态：登录前
参数：
ugidlo 用户注册ID号。
ugidhi 服务器的ID号。
gpcode 密码重设号。
描述：调用请求用户注册Register方法，如果注册成功将触发本事件。 ugidlo一定不为0。密码重设号不是密码，当因多次修改等原因遗忘密码时，可以用此号码重设密码。

void OnChangeUserLevel(long errcode, long ugid_lo)
发生状态：房间外
参数：
errcode 错误号。0/768/769，成功/没有权限/注册用户不存在
ugid_lo 用户注册ID号。
描述：站长在调用修改用户权限ChangeUserLevel方法后，无论修改成功与否，均触发本事件。

void OnChangePasswd(long errcode, long ugid_lo)
发生状态：房间外
参数：
errcode 错误号。0/512/768/769，成功/用户名非法/没有权限/注册用户不存在
ugid_lo 用户注册ID号。
描述：站长修改他人注册密码及昵称，或自己修改密码及昵称时（调用ChangePasswd方法），触发本事件。

void OnCastText(short cateid, long roomid, long ugid, BSTR castmsg)
发生状态：房间内
参数：
cateid 分类号。
roomid 房间号。
ugid 发出广播者用户注册ID。为0则是系统自动广播
castmsg 文字广播消息。
描述：站长发出文字广播(OpCastText)时，对应的分类及房间的所有用户均接收到本消息。

void OnUpdateUL(long cUser)
发生状态：房间内
参数：
cUser 用户个数。
描述：在SetParam中开启时本事件时，按SetParam设定的触发条件触发本事件，可以通过本事件处理房间内的在线用户名单绘制，在房间内有大量用户时(>50人)会有帮助。

void OnQueryUser(long uid, long ugid)
发生状态：房间内
参数：
uid 用户号
ugid 用户注册ID号
描述：用QueryUser方法查询房间内指定用户的注册ID号时，无论用户是否有查询权限，都会触发发事件。如果没有查询权限，或被查询用户没有注册ID号，ugid均为0。

void OnNewPasswd(long ugid, long gpcode, BSTR passwd)
发生状态：登录前，房间外
参数：
ugid 用户注册ID号
gpcode 密码重设号
passwd 用户密码
描述：如果密码遗忘，任何注册用户可以在登录前用NewPasswd方法重新生成密码。如果用户注册ID号和密码重设号(在OnRegister中获得)正确，则ugid为非0，gpcode为新的密码重设号，passwd是系统为用户重设的密码。在房间外，仅站长有权力调用NewPasswd方法生成新的用户的密码重设号。

服务器端

与外部Web服务程序的整合

如果只需要使用静态页面，建议采用本系统内建的Web服务程序。此程序会提供高于IIS5.0及Apache的网页服务性能。但如果需要一部份页面采用php/asp/jsp/cgi/isapi/nsapi一类的动态页面，则可以将所有网页全部放在外部Web服务程序的目录下，并在OnInit事件中设置SetParam(5,端口号)来告知用户端控件：服务器的上述端口号才是语音服务程序的端口号。

服务器端配置文件详解

语音服务器

网页服务器

北京莲塘软件技术有限公司
http://www.liantang.net