QQAPI设计说明书

1、第 1 页 共 20 页 qqapi 设计说明书 目录 一、引言.3 1.1 编写目的.3 1.2 更新时间.3 二、总体设计.3 三、注册的系统消息.3 3.1wm_qqapi_register .3 3.2wm_qqapi_register_resp .4 3.3wm_qqapi_available .4 四、从设备到qq 的自定义事件.5 4.1event_qqapi_set_audiodevice .5 4.2event_qqapi_get_userinfo .5 4.3event_qqapi_press_key .5 4.4event_qqapi_call .6 4.5event_q

2、qapi_mute .6 4.6event_qqapi_unregister .7 五、从qq 到设备的自定义事件.7 5.1event_qqapi_userinfo .7 5.2event_qqapi_status_change .7 5.3event_qqapi_shutdown .8 六、双向的自定义事件.8 6.1event_qqapi_call_status .8 第 2 页 共 20 页 七、错误码定义.10 7.1 从 qq 到设备 event_qqapi_error .10 八、参数类型码表.11 第 3 页 共 20 页 一、 引言 1.1 编写目的 本文档提供了qqapi

3、接口说明，以供第三方应用 程序使用，用 于 qq 和硬件设备（例如usbphone）的交互。 1.2 更新时间 最后修订日期：2005-05-24 版本号：v1.0 二、总体设计 qq 应用程序和第三方应用程序以收发消息的方式进行通讯。 双方未成功注册之前，采用 registerwindowmessage（ windowsapi）注册的系统消息进行交互， 注册成功后，双方分别获取对方的窗口句柄，接下来的交互通过收发 wm_copydata（ windows 消息）消息完成。 wm_copydata 的 wparam 参数为发送方的窗口句柄，lparam 为指向copydatastruct 结构

4、的指针，copydatastruct 定义如下： typedefstructtagcopydatastruct ulong_ptr dwdata; dwordcbdata; pvoidlpdata; copydatastruct,*pcopydatastruct; dwdata：事件码，标示传送的消息事件码 lpdata：消息参数， 采用多个相连的“类型（ 1 字节）长度 （ 4 字节）值”的格式。所有的参数类型码表见8 参数类型码 第 4 页 共 20 页 表 cbdata：消息参数总长度，单位字节 三、注册的系统消息 第三方程序使用windowssdkregisterwindowmessa

5、ge，进 行下列系统消息的注册。例如： registerwindowmessage(“wm_qqapi_register”); 3.1wm_qqapi_register 消息名：注册消息 方向：设备qq wparam：发送方的窗口句柄 lparam： qqapi 版本号，目前为100，表示1.00。 第三方应用程序启动并检测到可用的设备后，向所有 windows 窗口广播这个消息，带上自己的窗口句柄作为消息参数，如下： sendmessage(hwnd_broadcast,wm_qqapi_register,发送端窗 口句柄 ,0); 当 qq 收到这个消息时，弹出“外设控制”窗口 等待用户选

6、择， 如下： 第 5 页 共 20 页 3.2wm_qqapi_register_resp 消息名：注册回复消息 方向： qq设备 wparam：值如下： waiting（ 1）：等待用户选择 ok（ 2）：用户选择“允许使用” reject（ 3）：用户选择“禁止使用” lparam：当wparam 为 ok（ 2）时， lparam 为 qq 应用程序的窗 口句柄。 当用户选择“禁止使用”之后，如果第三方应用程序再次发送 wm_qqapi_register 消息， qq 不再弹出“qq 安全警告”框，直接 返回reject 的 wm_qqapi_register_resp 消息，直到qq

7、程序重 新启动为止。 3.3wm_qqapi_available 消息名：qqapi 可用消息 方向： qq设备 wparam：发送方的窗口句柄，即qq 程序的窗口句柄 第 6 页 共 20 页 lparam： qqapi 版本号，目前为1 当 qq 启动后，向所有windows 窗口广播这个消息： sendmessage(hwnd_broadcast,wm_qqapi_available,qq 窗口 句柄 ,0); 当第三方应用程序收到这个消息时，再发起 wm_qqapi_register 消息进行注册。这种情况出现在，当第三方应用 程序先启动，而qq 程序后启动的情况下。 四、从设备到qq

8、 的自定义事件 4.1event_qqapi_set_audiodevice 事件说明：设置qq 使用的音频设备 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：10 lpdata：如下表 cbdata：消息参数总长度 参数类 型码 长度值说明 5 设备名 长度 音频设备名，类型：以 null 结尾的字符串 6 4 字节音频设备的设备id 号，类 型： dword 第三方应用程序可通过音频设备名字字符串或者通过设备 id 号，来发送设置音频设备事件。 4.2event_qqapi_get_userinfo 第 7 页 共 20

9、页 事件说明：获取qq 用户信息 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：11 lpdata： null cbdata： 0 qq 返回的用户信息，见5.1event_qqapi_userinfo。 4.3event_qqapi_press_key 事件说明：发送按键消息，当用户在设备上按下任何键时，发送此事 件给qq 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：12 lpdata：如下表 cbdata：消息参数总长度 参数类 型码 长度值说明 7 1

10、 字节键值，详见“键值映射表” 键值映射表： 键名键值 00 x80 10 x81 第 8 页 共 20 页 20 x82 30 x83 40 x84 50 x85 60 x86 70 x87 80 x88 90 x89 down0 x8d up0 x8e clear0 x8f ok(呼叫键 ) 0 x91 cancel(挂断键 ) 0 x92 star(*)0 x93 sharp(#)0 x94 mute(静音键 ) 0 x95 ringtong(切换 铃声键 ) 0 x96 4.4event_qqapi_call 事件说明：直接呼叫一个好友用户 参数说明：wm_copydata 中的参数c

11、opydatastruct 结构说明 详见2 dwdata（事件码）：13 第 9 页 共 20 页 lpdata：如下表 cbdata：消息参数总长度 通过qq 号呼叫： 参数类 型码 长度值说明 1 qq 号长 度 qq 号，类型：以null 结 尾的字符串 通过昵称呼叫： 参数类 型码 长度值说明 2 昵称长 度 昵称，类型：以null 结尾 的字符串 通过速播号呼叫： 参数类 型码 长度值说明 3 速播号 长度 速播号，类型：以null 结 尾的字符串 通过pstn 号码呼叫： 参数类 型码 长度值说明 4 pstn 号pstn 号码，类型：以 第 10 页 共 20 页 码长度nul

12、l 结尾的字符串 4.5event_qqapi_mute 事件说明：静音设置，根据参数决定是打开静音或者关闭静音 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：14 lpdata：如下表 cbdata：消息参数总长度 参数类 型码 长度值说明 12 1 字节静音状态标志。1：静音打开； 0：静音关闭 4.6event_qqapi_unregister 事件说明：反注册 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：15 lpdata： null cbdata：

13、 0 当第三方应用程序退出时，向qq 发送此事件消息，qq 将音 频设备切换回系统原有设备。 五、从qq 到设备的自定义事件 5.1event_qqapi_userinfo 事件说明：返回本地qq 用户信息。对应于 第 11 页 共 20 页 4.2event_qqapi_get_userinfo 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：16 lpdata：如下表 cbdata：消息参数总长度 参数类 型码 长度值说明 1 qq 号长 度 qq 号，类型：以null 结尾 的字符串 2 昵称长 度 昵称，类型：以null

14、 结尾 的字符串 5.2event_qqapi_status_change 事件说明：qq 上的各种状态变化通知 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：17 lpdata：如下表 cbdata：消息参数总长度 状态变化类型说明： （ 1） dialnum 说明：拨号时的号码变化。参数子项依次为： 参数类 型码 长度值说明 第 12 页 共 20 页 11 1 字节dialnum，状态变换类型码：1 1 qq 号长 度 qq 号，类型：以null 结尾 的字符串 当用户拨号，qq 在收号时，如果号码发生变换，例如用户在键

15、盘 上按一个号码，或用户在pc 上按一个号码，或用户按清除键 clear，那么，qq 向第三方程序发送此事件通知。第三方程序可通过此 事件通知来进行拨号过程中lcd 的显示操作。 5.3event_qqapi_shutdown 事件说明：关闭qq 应用程序 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：18 lpdata： null cbdata： 0 当 qq 应用程序退出时，向第三方程序发送此事件消息。 六、双向的自定义事件 6.1event_qqapi_call_status 事件说明：呼叫状态通知 参数说明：wm_co

16、pydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：19 lpdata：如下表 cbdata：消息参数总长度 呼叫状态类型说明： 第 13 页 共 20 页 （ 1） connecting 方向：从qq 到设备 说明：呼出，正在等待对方应答。参数子项依次为： 参数类 型码 长度值说明 8 1 字节connecting，呼叫状态类型码： 1 9 4 字节呼叫句柄（callhandle）， 类型： dword 10 1 字节通话人数，类型：char 1 qq 号长 度 qq 号，类型：以null 结尾 的字符串 2 昵称长 度 昵称，类型：以null 结尾

17、 的字符串 其中，呼叫句柄为qq 分配的唯一呼叫标识符；通话人数为同时呼 出的qq 个数；接下来紧跟的2 个参数子项为被呼叫的qq 好友信 息，如果被呼叫的qq 好友有多个，则有多个qq 好友信息。 回铃音由qq 控制播放。 （ 2） ring 方向：从qq 到设备 说明：呼入，振铃。参数子项依次为： 参数类 型码 长度值说明 8 1 字节ring，呼叫状态类型码：2 第 14 页 共 20 页 9 4 字节呼叫句柄（callhandle）， 类型： dword 1 qq 号长 度 qq 号，类型：以null 结尾 的字符串 2 昵称长 度 昵称，类型：以null 结尾 的字符串 4（可 选）

18、 pstn 号 码长度 pstn 号码，类型：以null 结尾的字符串 其中，呼叫句柄为qq 分配的唯一呼叫标识符；接下来的2 个参数子项为呼入qq 好友信息；最后一个参数项为可选项，呼出的 pstn 号码，该号码直接由呼叫方指定，本地qq 完成呼叫转移，转 到 pstn 号码上。如果ringing 带了 “呼出的pstn 号码 ”，则本 地不振铃，直接转移呼出；如果ringing 没带 “呼出的pstn 号 码 ”，则本地振铃。 （ 3） busy（针对转接盒设备） 方向：双向 说明：占线。参数子项依次为： 参数类 型码 长度值说明 8 1 字节busy，呼叫状态类型码：3 9 4 字节呼叫

19、句柄（callhandle）， 类型： dword 从 qq 到设备：呼出，等待对方应答，且当对方的设备被 pstn 占用时，则qq 向本地设备发送占线状态。 第 15 页 共 20 页 从设备到qq：呼入，本地振铃，且当本地设备被pstn 占用 时，则本地设备向qq 发送占线状态。 （ 4） accept 方向：从qq 到设备 说明：呼入或呼出，某方接受，双方进入通话状态。参数子项依次为： 参数类 型码 长度值说明 8 1 字节accept，呼叫状态类型码： 4 9 4 字节呼叫句柄（callhandle）， 类型： dword （ 5） reject 方向：从qq 到设备 说明：呼入或呼出

20、，某方拒绝。参数子项依次为： 参数类 型码 长度值说明 8 1 字节reject，呼叫状态类型码： 5 9 4 字节呼叫句柄（callhandle）， 类型： dword （ 6） finish 第 16 页 共 20 页 方向：从qq 到设备 说明：呼入或呼出，通话结束，无论哪方发起。参数子项依次为： 参数类 型码 长度值说明 8 1 字节finish，呼叫状态类型码： 6 9 4 字节呼叫句柄（callhandle）， 类型： dword （ 7） fail 方向：从qq 到设备 说明：呼出失败。参数子项依次为： 参数类 型码 长度值说明 8 1 字节fail，呼叫状态类型码：7 9 4

21、字节呼叫句柄（callhandle）， 类型： dword 失败原因可能是，呼叫的用户不是qq 好友。 （ 8） hold（针对转接盒设备） 方向：从设备到qq 说明：暂停通话，通话被切换到pstn。参数子项依次为： 参数类 型码 长度值说明 8 1 字节hold，呼叫状态类型码：8 第 17 页 共 20 页 9 4 字节呼叫句柄（callhandle）， 类型： dword （ 9） resume（针对转接盒设备） 方向：从设备到qq 说明：恢复通话，通话被切换到回qq。参数子项依次为： 参数类 型码 长度值说明 8 1 字节resume，呼叫状态类型码： 9 9 4 字节呼叫句柄（cal

22、lhandle）， 类型： dword （ 10） mute 方向：从qq 到设备 说明：静音状态通知。参数子项依次为： 参数类 型码 长度值说明 8 1 字节mute，呼叫状态类型码：10 9 4 字节呼叫句柄（callhandle）， 类型： dword 12 1 字节静音状态标志。1：静音打开； 0：静音关闭 七、错误码定义 第 18 页 共 20 页 7.1 从 qq 到设备 event_qqapi_error 事件说明：从qq 到设备的错误通知 参数说明：wm_copydata 中的参数copydatastruct 结构说明 详见2 dwdata（事件码）：20 lpdata：如下表 cbdata：消息参数总长度 参数类 型码 长度值说明 12