QQ API设计说明书.doc

1、腾讯文档 QQ API 设计说明书第 1 页 共 11 页QQ API 设计说明书深圳腾讯计算机系统有限公司腾讯文档 QQ API 设计说明书第 2 页 共 11 页目录一、引言 .31.1 编写目的 .31.2 更新时间 .3二、总体设计 .3三、注册的系统消息 .33.1 WM_QQAPI_REGISTER.33.2 WM_QQAPI_REGISTER_RESP .43.3 WM_QQAPI_AVAILABLE .4四、从设备到 QQ 的自定义事件 .54.1 EVENT_QQAPI_SET_AUDIODEVICE .54.2 EVENT_QQAPI_GET_USERINFO.54.3 E

2、VENT_QQAPI_PRESS_KEY .54.4 EVENT_QQAPI_CALL.64.5 EVENT_QQAPI_MUTE.64.6 EVENT_QQAPI_UNREGISTER .7五、从 QQ 到设备的自定义事件 .75.1 EVENT_QQAPI_USERINFO.75.2 EVENT_QQAPI_STATUS_CHANGE .75.3 EVENT_QQAPI_SHUTDOWN .8六、双向的自定义事件 .86.1 EVENT_QQAPI_CALL_STATUS.8七、错误码定义 .107.1 从 QQ 到设备EVENT_QQAPI_ERROR .10八、参数类型码表 .11腾讯

3、文档 QQ API 设计说明书第 3 页 共 11 页一、引言1.1 编写目的本文档提供了 QQ API 接口说明，以供第三方应用程序使用，用于 QQ 和硬件设备（例如 USB Phone）的交互。1.2 更新时间最后修订日期：2005-05-24版本号：v1.0二、总体设计QQ 应用程序和第三方应用程序以收发消息的方式进行通讯。双方未成功注册之前，采用 RegisterWindowMessage（Windows API）注册的系统消息进行交互，注册成功后，双方分别获取对方的窗口句柄，接下来的交互通过收发WM_COPYDATA（Windows 消息）消息完成。WM_COPYDATA 的 wPa

4、ram 参数为发送方的窗口句柄，lParam 为指向COPYDATASTRUCT 结构的指针，COPYDATASTRUCT 定义如下：typedef struct tagCOPYDATASTRUCTULONG_PTR dwData; DWORD cbData; PVOID lpData; COPYDATASTRUCT, *PCOPYDATASTRUCT;dwData：事件码，标示传送的消息事件码lpData：消息参数，采用多个相连的“ 类型（1 字节）长度（4 字节）值”的格式。所有的参数类型码表见 8 参数类型码表cbData：消息参数总长度，单位字节三、注册的系统消息第三方程序使用 Win

5、dows SDKRegisterWindowMessage，进行下列系统消息的注册。例如：RegisterWindowMessage(“WM_QQAPI_REGISTER”);3.1 WM_QQAPI_REGISTER消息名：注册消息腾讯文档 QQ API 设计说明书第 4 页 共 11 页方向：设备QQwParam：发送方的窗口句柄lParam： QQ API 版本号，目前为 100，表示 1.00。第三方应用程序启动并检测到可用的设备后，向所有 Windows 窗口广播这个消息，带上自己的窗口句柄作为消息参数，如下：SendMessage( HWND_BROADCAST, WM_QQAPI

6、_REGISTER, 发送端窗口句柄, 0);当 QQ 收到这个消息时，弹出“外设控制” 窗口等待用户选择，如下：3.2 WM_QQAPI_REGISTER_RESP消息名：注册回复消息方向：QQ设备wParam：值如下：WAITING（1）：等待用户选择OK（2）：用户选择“ 允许使用 ”REJECT（3）：用户选择“禁止使用”lParam：当 wParam 为 OK（2）时，lParam 为 QQ 应用程序的窗口句柄。当用户选择“禁止使用” 之后，如果第三方应用程序再次发送 WM_QQAPI_REGISTER消息，QQ 不再弹出“QQ 安全警告” 框，直接返回 REJECT 的WM_QQA

7、PI_REGISTER_RESP 消息，直到 QQ 程序重新启动为止。3.3 WM_QQAPI_AVAILABLE消息名：QQ API 可用消息方向：QQ设备wParam：发送方的窗口句柄，即 QQ 程序的窗口句柄lParam： QQ API 版本号，目前为 1当 QQ 启动后，向所有 Windows 窗口广播这个消息：SendMessage( HWND_BROADCAST, WM_QQAPI_AVAILABLE, QQ 窗口句柄, 0);当第三方应用程序收到这个消息时，再发起 WM_QQAPI_REGISTER 消息进行注册。这种情况出现在，当第三方应用程序先启动，而 QQ 程序后启动的情况

8、下。腾讯文档 QQ API 设计说明书第 5 页 共 11 页四、从设备到 QQ 的自定义事件4.1 EVENT_QQAPI_SET_AUDIODEVICE事件说明：设置 QQ 使用的音频设备参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：10lpData：如下表cbData：消息参数总长度参数类型码 长度 值说明5 设备名长度 音频设备名，类型：以 Null 结尾的字符串6 4 字节 音频设备的设备 ID 号，类型： DWORD第三方应用程序可通过音频设备名字字符串或者通过设备 ID 号，来发送设置音频设备事件。4.2 EVE

9、NT_QQAPI_GET_USERINFO事件说明：获取 QQ 用户信息参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：11lpData：NULLcbData： 0QQ 返回的用户信息，见 5.1 EVENT_QQAPI_USERINFO。4.3 EVENT_QQAPI_PRESS_KEY事件说明：发送按键消息，当用户在设备上按下任何键时，发送此事件给 QQ参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：12lpData：如下表cbData：消息参数总长度参数类型

10、码 长度 值说明7 1 字节 键值，详见“键值映射表”键值映射表：键名 键值0 0x801 0x812 0x823 0x834 0x84腾讯文档 QQ API 设计说明书第 6 页 共 11 页5 0x856 0x867 0x878 0x889 0x89Down 0x8DUp 0x8EClear 0x8FOK (呼叫键) 0x91Cancel (挂断键 ) 0x92STAR (*) 0x93SHARP (#) 0x94Mute (静音键) 0x95RINGTONG (切换铃声键) 0x964.4 EVENT_QQAPI_CALL事件说明：直接呼叫一个好友用户参数说明：WM_COPYDATA 中

11、的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：13lpData：如下表cbData：消息参数总长度通过 QQ 号呼叫：参数类型码 长度 值说明1 QQ 号长度 QQ 号，类型：以 Null 结尾的字符串通过昵称呼叫：参数类型码 长度 值说明2 昵称长度 昵称，类型：以 Null 结尾的字符串通过速播号呼叫：参数类型码 长度 值说明3 速播号长度 速播号，类型：以 Null 结尾的字符串通过 PSTN 号码呼叫：参数类型码 长度 值说明4 PSTN 号码长度PSTN 号码，类型：以 Null 结尾的字符串4.5 EVENT_QQAPI_MUTE事件说明：静音设置，

12、根据参数决定是打开静音或者关闭静音参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2腾讯文档 QQ API 设计说明书第 7 页 共 11 页dwData（事件码）：14lpData：如下表cbData：消息参数总长度参数类型码 长度 值说明12 1 字节 静音状态标志。1：静音打开；0：静音关闭4.6 EVENT_QQAPI_UNREGISTER事件说明：反注册参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：15lpData：NULLcbData： 0当第三方应用程序退出时，向 QQ 发

13、送此事件消息，QQ 将音频设备切换回系统原有设备。五、从 QQ 到设备的自定义事件5.1 EVENT_QQAPI_USERINFO事件说明：返回本地 QQ 用户信息。对应于 4.2 EVENT_QQAPI_GET_USERINFO参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：16lpData：如下表cbData：消息参数总长度参数类型码 长度 值说明1 QQ 号长度 QQ 号，类型：以 Null 结尾的字符串2 昵称长度 昵称，类型：以 Null 结尾的字符串5.2 EVENT_QQAPI_STATUS_CHANGE事件说明：

14、QQ 上的各种状态变化通知参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：17lpData：如下表cbData：消息参数总长度状态变化类型说明：（1） DIALNUM说明：拨号时的号码变化。参数子项依次为：参数类型码 长度 值说明11 1 字节 DIALNUM，状态变换类型码：1腾讯文档 QQ API 设计说明书第 8 页 共 11 页1 QQ 号长度 QQ 号，类型：以 Null 结尾的字符串当用户拨号，QQ 在收号时，如果号码发生变换，例如用户在键盘上按一个号码，或用户在 PC 上按一个号码，或用户按清除键 Clear，那么

15、，QQ 向第三方程序发送此事件通知。第三方程序可通过此事件通知来进行拨号过程中 LCD 的显示操作。5.3 EVENT_QQAPI_SHUTDOWN事件说明：关闭 QQ 应用程序参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：18lpData：NULLcbData： 0当 QQ 应用程序退出时，向第三方程序发送此事件消息。六、双向的自定义事件6.1 EVENT_QQAPI_CALL_STATUS事件说明：呼叫状态通知参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：

16、19lpData：如下表cbData：消息参数总长度呼叫状态类型说明：（1）CONNECTING方向：从 QQ 到设备说明：呼出，正在等待对方应答。参数子项依次为：参数类型码 长度 值说明8 1 字节 CONNECTING，呼叫状态类型码：19 4 字节 呼叫句柄（CallHandle） ，类型：DWORD10 1 字节 通话人数，类型：char1 QQ 号长度 QQ 号，类型：以 Null 结尾的字符串2 昵称长度 昵称，类型：以 Null 结尾的字符串其中，呼叫句柄为 QQ 分配的唯一呼叫标识符；通话人数为同时呼出的 QQ 个数；接下来紧跟的 2 个参数子项为被呼叫的 QQ 好友信息，如果

17、被呼叫的 QQ 好友有多个，则有多个 QQ 好友信息。回铃音由 QQ 控制播放。（2）RING 方向：从 QQ 到设备腾讯文档 QQ API 设计说明书第 9 页 共 11 页说明：呼入，振铃。参数子项依次为：参数类型码 长度 值说明8 1 字节 RING，呼叫状态类型码：29 4 字节 呼叫句柄（CallHandle） ，类型：DWORD1 QQ 号长度 QQ 号，类型：以 Null 结尾的字符串2 昵称长度 昵称，类型：以 Null 结尾的字符串4（可选） PSTN 号码长度PSTN 号码，类型：以 Null 结尾的字符串其中，呼叫句柄为 QQ 分配的唯一呼叫标识符；接下来的 2 个参数子

18、项为呼入QQ 好友信息；最后一个参数项为可选项，呼出的 PSTN 号码，该号码直接由呼叫方指定，本地 QQ 完成呼叫转移，转到 PSTN 号码上。如果 RINGING 带了“ 呼出的PSTN 号码 ”，则本地不振铃，直接转移呼出；如果 RINGING 没带“呼出的 PSTN 号码”，则本地振铃。（3）BUSY （针对转接盒设备）方向：双向说明：占线。参数子项依次为：参数类型码 长度 值说明8 1 字节 BUSY，呼叫状态类型码：39 4 字节 呼叫句柄（CallHandle） ，类型：DWORD从 QQ 到设备：呼出，等待对方应答，且当对方的设备被 PSTN 占用时，则 QQ向本地设备发送占线

19、状态。从设备到 QQ：呼入，本地振铃，且当本地设备被 PSTN 占用时，则本地设备向QQ 发送占线状态。（4）ACCEPT方向：从 QQ 到设备说明：呼入或呼出，某方接受，双方进入通话状态。参数子项依次为：参数类型码 长度 值说明8 1 字节 ACCEPT，呼叫状态类型码：49 4 字节 呼叫句柄（CallHandle） ，类型：DWORD（5）REJECT方向：从 QQ 到设备说明：呼入或呼出，某方拒绝。参数子项依次为：参数类型码 长度 值说明8 1 字节 REJECT，呼叫状态类型码：59 4 字节 呼叫句柄（CallHandle） ，类型：DWORD（6）FINISH方向：从 QQ 到设

20、备说明：呼入或呼出，通话结束，无论哪方发起。参数子项依次为：参数类型码 长度 值说明8 1 字节 FINISH，呼叫状态类型码：6腾讯文档 QQ API 设计说明书第 10 页 共 11 页9 4 字节 呼叫句柄（CallHandle） ，类型：DWORD（7）FAIL方向：从 QQ 到设备说明：呼出失败。参数子项依次为：参数类型码 长度 值说明8 1 字节 FAIL，呼叫状态类型码：79 4 字节 呼叫句柄（CallHandle） ，类型：DWORD失败原因可能是，呼叫的用户不是 QQ 好友。（8）HOLD （针对转接盒设备）方向：从设备到 QQ说明：暂停通话，通话被切换到 PSTN。参数子

21、项依次为：参数类型码 长度 值说明8 1 字节 HOLD，呼叫状态类型码：89 4 字节 呼叫句柄（CallHandle） ，类型：DWORD（9）RESUME（针对转接盒设备）方向：从设备到 QQ说明：恢复通话，通话被切换到回 QQ。参数子项依次为：参数类型码 长度 值说明8 1 字节 RESUME，呼叫状态类型码：99 4 字节 呼叫句柄（CallHandle） ，类型：DWORD（10）MUTE方向：从 QQ 到设备说明：静音状态通知。参数子项依次为：参数类型码 长度 值说明8 1 字节 MUTE，呼叫状态类型码：109 4 字节 呼叫句柄（CallHandle） ，类型：DWORD12 1 字节 静音状态标志。1：静音打开；0：静音关闭七、错误码定义7.1 从 QQ 到设备EVENT_QQAPI_ERROR事件说明：从 QQ 到设备的错误通知参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2dwData（事件码）：20lpData：如下表cbData：消息参数总长度