UcSTAR第三方集成应用接口说明

擎旗信息技术有限公司 技术文档

UCSTAR第三方集成应用接口说明书

1 目的 .............................................................................................................................................. 3 2 方法 .............................................................................................................................................. 3 2.1初始化界面 ............................................................................................................................. 3 2.2登陆......................................................................................................................................... 3 2.3更改用户 ................................................................................................................................. 4 2.4更改状态 ................................................................................................................................. 5 2.5发送消息（弹出选择人员对话框） ..................................................................................... 5 2.6发送消息 ................................................................................................................................. 6 2.7发送广播消息 ......................................................................................................................... 6 2.8查看历史消息 ......................................................................................................................... 7 2.9批量查看状态 ......................................................................................................................... 7 2.10发送短信 ............................................................................................................................... 8 2.11发送邮件 ............................................................................................................................... 8 2.12显示UCSTAR ....................................................................................................................... 8 2.13退出UCSTAR ....................................................................................................................... 9 2.14初始化界面扩展接口 ........................................................................................................... 9 2.15设置服务器地址和端口 ..................................................................................................... 10 2.16登陆UCSTAR ..................................................................................................................... 10 2.17获取UCSTAR当前状态 .................................................................................................... 11 2.18获取当前登陆名称 ............................................................................................................. 11 2.19获取当前登陆账号 ............................................................................................................. 11 2.20获取当前登陆密码 ............................................................................................................. 12 3事件 ............................................................................................................................................. 12 3.1状态变化事件 ...................................................................................................................... 12 3.2消息通知事件 ...................................................................................................................... 13 3.3会话创建事件 ...................................................................................................................... 13 3.4会话解散事件 ...................................................................................................................... 14 3.5退出多人会话事件 .............................................................................................................. 14 3.6踢出多人会话事件 .............................................................................................................. 14 3.7电话呼出事件 ...................................................................................................................... 15 3.8呼出成功事件 ...................................................................................................................... 15 3.9呼出通话事件 ...................................................................................................................... 15 3.10呼出失败事件 .................................................................................................................... 16 3.11保持成功事件 .................................................................................................................... 16 3.12保持失败事件 .................................................................................................................... 16 3.13取保持成功事件 ................................................................................................................ 17 3.14取保持失败事件 ................................................................................................................ 17 3.15电话呼入事件 .................................................................................................................... 17 3.16应答成功事件 .................................................................................................................... 17 3.17应答失败事件 .................................................................................................................... 18 3.18转移事件 ............................................................................................................................ 18

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

3.19挂机事件 ............................................................................................................................ 18 3.20请求开始远程协助事件 .................................................................................................... 19 3.21请求远程协助结束事件 .................................................................................................... 19 3.22响应远程协助请求事件 .................................................................................................... 19 3.23响应远程协助请求结束事件 ............................................................................................ 20 3.24发送文件成功 .................................................................................................................... 20 3.25发送文件失败 .................................................................................................................... 20 3.26接收文件成功 .................................................................................................................... 21 3.27接收文件失败 .................................................................................................................... 21 3.28录音成功事件 .................................................................................................................... 22 3.29录音失败事件 .................................................................................................................... 22 4 常量定义..................................................................................................................................... 23 4.1消息类型 .............................................................................................................................. 23

1 2 3 版本号 更新人 更新时间 说明 V1.0 V1.0 V1.1 张华 张华 张华 2011-4-6 2011-4-15 2011-5-23 创建 添加发送短信和发送邮件接口 添加2.12~2.20接口

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

1 目的

在第三方系统中添加IM模块。实现以下功能：即时点到点消息(分男与女) ，群消，广播消息，离线消息等。维护在线用户的状态(离开，忙，上线)。文件传输。

2 方法

2.1初始化界面

●功能 初始化界面 ●预置条件

调用本方法之前必须确保ComUc.dll已经注册，并且确保UcSTAR已经安装。 ●函数声明 short InitUc() ●返回值 0：调用成功 1：调用失败

2: 初始化Com组件失败 3：初始化UcSTAR com组件失败 4：注册UcSTAR com组件连接点失败 5：没有安装UcSTAR 2.2登陆

●功能

与服务器建立连接，登陆服务器，显示组织架构数据，显示在线状态。 ●预置条件

调用InitUc进行初始化。 ●函数声明

short LoginUc(BSTR srvIp, BSTR srvPort, BSTR username, BSTR password,

short flag)

●参数说明

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

@srvIp 服务器地址 @srvPort 服务器端口 @username 用户账号 @password 用户密码 @flag 登陆方式标志 0：账号密码登陆 1：RSA加密登陆

2：仅仅使用账号登陆，不验证密码 4：使用账号和sessionKey登陆 ●返回值 0：登陆成功 1：已经登陆 2：密码错误 3：登陆超时 4：正在登陆

2.3更改用户

●功能

与服务器重新建立连接，登陆服务器，显示新用户的组织架构数据，显示在线状态。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short ChangeUser(BSTR srvIp, BSTR srvPort, BSTR username, BSTR password) ●参数说明

@srvIp 服务器地址 @srvPort 服务器端口 @username 用户账号 @password 用户密码

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●返回值 0：调用成功 1：调用失败 2.4更改状态

●功能

改变当前登录用户的状态，上线，离线和离开，界面上会有不同体现。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short ChangeStatus(short iStatus) ●参数说明

@ iStatus 状态值 0：在线，1：离开，2：离线 ●返回值 0：调用成功 1：调用失败

2.5发送消息（弹出选择人员对话框）

●功能

发送消息给所选择的人员。调用该函数，首先会弹出一个选择人员的对话框，选择人员（可以选择多个人）确认后弹出消息发送框，点击发送按钮就可以发送消息。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short SendMessageSimple(BSTR strContent, short editable) ●参数说明

@ strContent 消息内容

@ editable 是否可以再编辑，1：可以编辑，0：不可以编辑 ●返回值 0：调用成功

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

1：调用失败 2.6发送消息

●功能

发送消息给所指定的人员。调用该函数后弹出消息发送框，点击发送按钮就可以发送消息。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short SendMessageTo(BSTR strContent, short editable, BSTR strUsers) ●参数说明

@ strContent 消息内容

@ editable 是否可以再编辑，1：可以编辑，0：不可以编辑

@ strUsers 用户账号，多个以逗号隔开，如果账号是群组，则在后面加[group],如果账号是部门，则在后面加[depart] ●返回值 0：调用成功 1：调用失败 2.7发送广播消息

●功能

发送广播消息给所指定的人员。调用该函数后就可以发送消息。不会弹出任何界面。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short SendBroadcastTo(BSTR strContent, BSTR strUsers) ●参数说明

@ strContent 消息内容

@ strUsers 用户账号，多个以逗号隔开，如果账号是群组，则在后面加[group],如果账号是部门，则在后面加[depart]

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●返回值 0：调用成功 1：调用失败 2.8查看历史消息

●功能

弹出查询界面，显示查询结果。可以在界面上进行其他条件的查询。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short ShowMessageHistory(BSTR strSender, BSTR strReceiver, BSTR strType) ●参数说明

@ strSender 发送者账号，不允许为空 @ strReceiver 接收者用户账号，可以为空

@ strType 会话类型，chat 表示单人会话，groupchat 表示多人会话 ●返回值 0：调用成功 1：调用失败 2.9批量查看状态

●功能

查询指定用户状态。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

BSTR GetBatchState(BSTR strUsers) ●参数说明

@ strUsers 用户账号，多个以逗号隔开 ●返回值

状态数字串集，逗号分开，按账号顺序返回；0:离线 1:在线 2:离开 3免打

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

扰 -1：用户不存在。 2.10发送短信

●功能

向指定人员发送短信，弹出短信编辑窗口。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short SendSms(BSTR strUsers) ●参数说明

@ strUsers 用户账号，多个以逗号隔开。 ●返回值 0：调用成功 1：调用失败 2.11发送邮件

●功能

向指定人员发送邮件，弹出邮件编辑窗口。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

short SendEmail(BSTR strUsers) ●参数说明

@ strUsers 用户账号，多个以逗号隔开 ●返回值 0：调用成功 1：调用失败 2.12显示UcSTAR

●功能

根据参数显示和最小化UcSTAR。 ●预置条件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

调用InitUc进行初始化。 ●函数声明

short ShowUc (short flag) ●参数说明

@ flag 1：顶层显示，0：最小化UcSTAR ●返回值 0：调用成功 1：调用失败 2.13退出UcSTAR

●功能 退出UcSTAR。 ●预置条件

调用InitUc进行初始化。 ●函数声明

short CloseUc(short force) ●参数说明

@ force 1：不提示直接关闭，0：提示是否关闭 ●返回值 0：调用成功 1：调用失败 2.14初始化界面扩展接口

●功能

初始化UcSTAR界面。如果是弹出界面方式，则是初始化UcSTAR com接口,启动UcSTAR；如果是嵌入界面方式，则是初始化加载界面。 ●预置条件

调用本方法之前必须确保ComUc.dll已经注册，并且确保UcSTAR已经安装。 ●函数声明

short InitUcEx(short flag) ●参数说明

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

@ flag 0：独立界面显示方式，1：嵌入界面显示方式 ●返回值 0：调用成功 1：调用失败

2.15设置服务器地址和端口

●功能

设置服务器地址和端口。兼容老的接口，如果使用LoginUc函数登陆，则不必调用该函数。 ●预置条件

调用InitUc进行初始化成功。 ●函数声明

short SetUcSTARHost(BSTR serverip, BSTR serverport) ●参数说明

@ serverip 服务器地址 @ serverport 服务器端口 ●返回值 0：调用成功 1：调用失败 2.16登陆UcSTAR

●功能

使用SessionKey方式登陆UcSTAR。兼容老的接口，如果使用LoginUc函数登陆，则不必调用该函数。注意，该函数仅仅支持SessionKey方式登陆。 ●预置条件

调用InitUc进行初始化，调用SetUcSTARHost设置服务器地址和端口。 ●函数声明

short StartUcSTAR(BSTR username, BSTR sessionkey) ●参数说明

@ username 用户账号

@ sessionkey sessionkey,一般都是调用者从UcSTAR服务器端获取。

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●返回值 0：调用成功 1：调用失败

2.17获取UcSTAR当前状态

●功能

获取UcSTAR客户端的当前状态。 ●预置条件 无。 ●函数声明

short GetUcPresence() ●返回值

0：表示没有安装UcSTAR，或者没有初始化UcSTAR 1：表示UcSTAR处于在线状态 2：表示UcSTAR处于离线状态 2.18获取当前登陆名称

●功能

获取当前登陆名称。是用户通过LoginUc函数或者StartUcSTAR函数传入的名称。

注意：该名称可能不是账号。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明

BSTR GetLoginName() ●返回值 当前登陆名称 2.19获取当前登陆账号

●功能

获取当前登陆账号。是用户的注册账号。

注意：必须登陆成功该函数返回值才有效，否则返回的是登陆名称。

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明 BSTR GetUserName() ●返回值

当前登陆账号

2.20获取当前登陆密码

●功能

获取当前登陆密码。

注意：必须是密码登陆方式登陆的才有效，返回的密码是经过MD5加密过的。 ●预置条件

调用InitUc进行初始化,调用LoginUc成功。 ●函数声明 BSTR GetPassword() ●返回值

经过MD5加密过的密码。

3事件

3.1状态变化事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnStatusChange(short iStatus, BSTR strShow) ●参数说明

@iStatus 状态值。0：在线，1：忙（离开），2：离线 @strShow 状态说明 ●触发条件

1、登陆成功触发该事件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

2、触发该事件

3.2消息通知事件 ●事件类型 ActiveX连接点事件 ●函数声明

点击下拉箭头后，选择上线，离开，离线均

void OnMessageCome(short iType, BSTR strBody, BSTR strOwner) ●参数说明 @iType 消息类型。

Message_chat = 1 //单人消息

Message_groupchat = 2 //多人消息 Message_sms = 4 //短信消息 Message_broadcast = 5 //广播消息 Message_system = 6 //系统消息 Message_lecture = 7 //专家讲堂消息 Message_error = 9 //消息错误

@ strBody 消息体。 @ strOwner 发送者。 ●触发条件

当有消息接收的时候触发。

3.3会话创建事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnSessionCreate(short iType, BSTR strKey) ●参数说明

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

@ iType 会话类型，等同于消息类型。 @ strKey 会话ID ●触发条件

多人会话创建成功的时候触发。

3.4会话解散事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnSessionDismiss(BSTR strKey) ●参数说明 @ strKey 会话ID ●触发条件

多人会话解散的时候触发。

3.5退出多人会话事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnMucQuit(BSTR strKey, BSTR strUser) ●参数说明 @ strKey 会话ID @ strUser 用户ID ●触发条件

有人退出多人会话的时候触发。

3.6踢出多人会话事件 ●事件类型 ActiveX连接点事件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●函数声明

void OnMucKick(BSTR strKey, BSTR strUser) ●参数说明 @ strKey 会话ID @ strUser 用户ID ●触发条件

有人被踢出多人会话的时候触发。

3.7电话呼出事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnOutCalling(BSTR strUser, BSTR strNumber) ●参数说明

@ strUser 扩展使用，暂时没用到 @ strNumber 呼出号码 ●触发条件

本人向其他人发起语音会话的时候触发。

3.8呼出成功事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioCallOutSuccess() ●触发条件

呼出电话接通的时候触发。

3.9呼出通话事件 ●事件类型

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

ActiveX连接点事件 ●函数声明

void OnAudioCallOutSuccTalk() ●触发条件

呼出电话对方接听后触发。该函数暂时没用到

3.10呼出失败事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioCallOutFailure() ●触发条件

呼出失败的时候触发。

3.11保持成功事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioHoldSuccess() ●触发条件

点击“保持”按钮的时候触发。

3.12保持失败事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioHoldFailure() ●触发条件

保持通话失败的时候触发。

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

3.13取保持成功事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioGetHoldSuccess() ●触发条件

点击“取回”按钮的时候触发。

3.14取保持失败事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioGetHoldFailure() ●触发条件

取保持失败的时候触发。

3.15电话呼入事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnInComing(BSTR strNumber, BSTR strUser) ●参数说明

@ strNumber 呼入号码 @ strUser 用户ID，暂时没有用 ●触发条件

有电话呼入的时候触发。

3.16应答成功事件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioAnswerSuccess() ●触发条件

自己点击“接听”按钮并且通话成功或对方点击“接听”并且通话成功的时候触发。

3.17应答失败事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioAnswerFailure() ●触发条件

点击“接听”按钮并且通话失败的时候触发。

3.18转移事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioTransfer(BSTR strNumber) ●参数说明

@ strNumber 呼入号码 ●触发条件

转移电话的时候触发。

3.19挂机事件 ●事件类型 ActiveX连接点事件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●函数声明

void OnAudioHangUp(BSTR strNumber，BSTR strUser) ●参数说明

@ strUser 扩展使用，暂时没用到 @ strNumber 呼入号码 ●触发条件

自己或对方挂机的时候触发。

3.20请求开始远程协助事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnReqAssistenceStart(BSTR strUser) ●参数说明 @ strUser 用户ID ●触发条件

本人向其他人发起远程协助请求的时候触发。

3.21请求远程协助结束事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnReqAssistenceEnd() ●触发条件

请求远程协助结束的时候触发。

3.22响应远程协助请求事件 ●事件类型 ActiveX连接点事件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

●函数声明

void OnResAssistenceStart(BSTR strUser) ●参数说明 @ strUser 用户ID ●触发条件

其他人向本人发起远程协助请求的时候触发。

3.23响应远程协助请求结束事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnResAssistenceEnd() ●触发条件

响应远程协助结束的时候触发。

3.24发送文件成功 ●事件类型 ActiveX连接点事件 ●函数声明

void OnFileSendSuccess(BSTR strFileName, BSTR strSender, BSTR strRecver) ●参数说明

@ strFileName 文件名 @ strSender 发送者用户ID @ strRecver 接收者用户ID ●触发条件

发送文件成功的时候触发。

3.25发送文件失败 ●事件类型

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

ActiveX连接点事件 ●函数声明

void OnFileSendFailure(BSTR strFileName, BSTR strSender, BSTR strRecver) ●参数说明

@ strFileName 文件名 @ strSender 发送者用户ID @ strRecver 接收者用户ID ●触发条件

发送文件失败或取消发送文件的时候触发。

3.26接收文件成功 ●事件类型 ActiveX连接点事件 ●函数声明

void OnFileRecvSuccess(BSTR strFileName, BSTR strSender, BSTR strRecver) ●参数说明

@ strFileName 文件名 @ strSender 发送者用户ID @ strRecver 接收者用户ID ●触发条件

接收文件成功的时候触发。

3.27接收文件失败 ●事件类型 ActiveX连接点事件 ●函数声明

void OnFileRecvFailure(BSTR strFileName, BSTR strSender, BSTR strRecver) ●参数说明

@ strFileName 文件名

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

@ strSender 发送者用户ID @ strRecver 接收者用户ID ●触发条件

接收文件失败或取消接收文件的时候触发。

3.28录音成功事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioRecordingSuccess(BSTR strCallingParty, BSTR strCalledParty, BSTR strFileName) ●参数说明

@ strCallingParty 主叫用户账号 @ strCalledParty 被叫用户账号 @ strFileName 录音文件名 ●触发条件

录音完毕的时候触发。

3.29录音失败事件 ●事件类型 ActiveX连接点事件 ●函数声明

void OnAudioRecordingFailure(BSTR strCallingParty, BSTR strCalledParty, BSTR strFileName) ●参数说明

@ strCallingParty 主叫用户账号 @ strCalledParty 被叫用户账号 @ strFileName 录音文件名 ●触发条件

Version 1.0.0.4

擎旗信息技术有限公司 技术文档

根据号码找不到相关用户信息的时候触发。

4 常量定义

4.1消息类型 enum MessageType{

Message_normal = 0, //保留

Message_chat, // Message_groupchat, // Message_headline, // Message_sms, // Message_broadcast, // Message_system, // Message_lecture, // Message_other, //

Message_error //};

单人消息 多人消息 保留 短信消息 广播消息 系统消息 专家讲堂消息 其他消息 消息错误

Version 1.0.0.4

本文来源：https://www.bwwdw.com/article/q9m7.html