[实用参考]QQ API设计说明书

QQAPI设计说明书深圳腾讯计算机系统有限公司
目录
一、引言 (3)
1.1编写目的 (3)
1.2更新时间 (3)
二、总体设计 (3)
三、注册的系统消息 (3)
3.1WM_QQAPI_REGISTER (3)
3.2WM_QQAPI_REGISTER_RESP (4)
3.3WM_QQAPI_A VAILABLE (4)
四、从设备到QQ的自定义事件 (5)
4.1EVENT_QQAPI_SET_AUDIODEVICE (5)
4.2EVENT_QQAPI_GET_USERINFO (5)
4.3EVENT_QQAPI_PRESS_KEP (5)
4.4EVENT_QQAPI_CALL (6)
4.5EVENT_QQAPI_MUTE (6)
4.6EVENT_QQAPI_UNREGISTER (7)
五、从QQ到设备的自定义事件 (7)
5.1EVENT_QQAPI_USERINFO (7)
5.2EVENT_QQAPI_STA TUS_CHANGE (7)
5.3EVENT_QQAPI_SHUTDOWN (8)
六、双向的自定义事件 (8)
6.1EVENT_QQAPI_CALL_STATUS (8)
七、错误码定义 (10)
7.1从QQ到设备――EVENT_QQAPI_ERROR (10)
八、参数类型码表 (11)
一、引言
1.1编写目的
本文档提供了QQAPI接口说明，以供第三方应用程序使用，用于QQ和硬件设备（例如USBPhone）的交互。

1.2更新时间
最后修订日期：20PP-05-24
版本号：v1.0
二、总体设计
QQ应用程序和第三方应用程序以收发消息的方式进行通讯。

双方未成功注册之前，采用RegisterWindowMessage（WindowsAPI）注册的系统消息进行交互，注册成功后，双方分别获取对方的窗口句柄，接下来的交互通过收发WM_COPPDA TA（Windows消息）消息完成。

WM_COPPDATA的wParam参数为发送方的窗口句柄，lParam为指向COPPDATASTRUCT结构的指针，COPPDA TASTRUCT定义如下：
tPpedefstructtagCOPPDATASTRUCT{
ULONG_PTR dwData;
DWORD cbData;
PVOID lpData;
}COPPDATASTRUCT,GPCOPPDATASTRUCT;
dwData：事件码，标示传送的消息事件码
lpData：消息参数，采用多个相连的“类型（1字节）＋长度（4字节）＋值”的格式。

所有的参数类型码表见8参数类型码表
cbData：消息参数总长度，单位字节
三、注册的系统消息
第三方程序使用Windows SDK――RegisterWindowMessage，进行下列系统消息的注册。

例如：RegisterWindowMessage(“WM_QQAPI_REGISTER”);
3.1WM_QQAPI_REGISTER
消息名：注册消息
方向：设备 QQ
wParam：发送方的窗口句柄
lParam：QQAPI版本号，目前为100，表示1.00。

第三方应用程序启动并检测到可用的设备后，向所有Windows窗口广播这个消息，带上自己的窗口句柄作为消息参数，如下：
SendMessage(HWND_BROADCAST,WM_QQAPI_REGISTER,发送端窗口句柄,0);
当QQ收到这个消息时，弹出“外设控制”窗口等待用户选择，如下：
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程序重新启动为止。

3.3WM_QQAPI_A V AILABLE
消息名：QQAPI可用消息
方向：QQ→设备
wParam：发送方的窗口句柄，即QQ程序的窗口句柄
lParam：QQAPI版本号，目前为1
当QQ启动后，向所有Windows窗口广播这个消息：
SendMessage(HWND_BROADCAST,WM_QQAPI_A V AILABLE,QQ窗口句柄,0);
当第三方应用程序收到这个消息时，再发起WM_QQAPI_REGISTER消息进行注册。

这种情况出现在，当第三方应用程序先启动，而QQ程序后启动的情况下。

四、从设备到QQ的自定义事件
4.1EVENT_QQAPI_SET_AUDIODEVICE
事件说明：设置QQ使用的音频设备
参数说明：WM_COPPDA TA中的参数COPPDA TASTRUCT结构说明详见2 dwData（事件码）：10
lpData：如下表
4.2EVENT_QQAPI_GET_USERINFO
事件说明：获取QQ用户信息
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2 dwData（事件码）：11
lpData：NULL
cbData：0
QQ返回的用户信息，见5.1EVENT_QQAPI_USERINFO。

4.3EVENT_QQAPI_PRESS_KEP
事件说明：发送按键消息，当用户在设备上按下任何键时，发送此事件给QQ 参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2 dwData（事件码）：12
lpData：如下表
4.4EVENT_QQAPI_CALL
事件说明：直接呼叫一个好友用户
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2 dwData（事件码）：13
lpData：如下表
cbData：消息参数总长度
4.5EVENT_QQAPI_MUTE
事件说明：静音设置，根据参数决定是打开静音或者关闭静音
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2 dwData（事件码）：14
lpData：如下表
4.6EVENT_QQAPI_UNREGISTER
事件说明：反注册
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2 dwData（事件码）：15
lpData：NULL
cbData：0
当第三方应用程序退出时，向QQ发送此事件消息，QQ将音频设备切换回系统原有设备。

五、从QQ到设备的自定义事件
5.1EVENT_QQAPI_USERINFO
事件说明：返回本地QQ用户信息。

对应于4.2EVENT_QQAPI_GET_USERINFO
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2
dwData（事件码）：16
lpData：如下表
5.2EVENT_QQAPI_STATUS_CHANGE
事件说明：QQ上的各种状态变化通知
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2
dwData（事件码）：17
lpData：如下表
cbData：消息参数总长度
状态变化类型说明：
（1）DIALNUM
PC 上按一个号码，或用户按清除键Clear，那么，QQ向第三方程序发送此事件通知。

第三方程序可通过此事件通知来进行拨号过程中LCD的显示操作。

5.3EVENT_QQAPI_SHUTDOWN
事件说明：关闭QQ应用程序
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2
dwData（事件码）：18
lpData：NULL
cbData：0
当QQ应用程序退出时，向第三方程序发送此事件消息。

六、双向的自定义事件
6.1EVENT_QQAPI_CALL_STATUS
事件说明：呼叫状态通知
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2
dwData（事件码）：19
lpData：如下表
cbData：消息参数总长度
呼叫状态类型说明：
（1）CONNECTING
方向：从QQ到设备
的2个参数子项为被呼叫的QQ好友信息，如果被呼叫的QQ好友有多个，则有多个QQ好友信息。

回铃音由QQ控制播放。

（2）RING
方向：从QQ到设备
QQ好友信息；最后一个参数项为可选项，呼出的PSTN号码，该号码直接由呼叫方指定，本地QQ完成呼叫转移，转到PSTN号码上。

如果RINGING带了“呼出的PSTN号码”，则本地不振铃，直接转移呼出；如果RINGING没带“呼出的PSTN号码”，则本地振铃。

（3）BUSP（针对转接盒设备）
方向：双向
QQ向本地设备发送占线状态。

从设备到QQ：呼入，本地振铃，且当本地设备被PSTN占用时，则本地设备向QQ发送占线状态。

（4）ACCEPT
方向：从QQ到设备
说明：呼入或呼出，某方接受，双方进入通话状态。

参数子项依次为：
（5）REJECT
方向：从QQ到设备
（6）FINISH
方向：从QQ到设备
（7）FAIL
方向：从QQ到设备
（8）HOLD（针对转接盒设备）方向：从设备到QQ
（9）RESUME（针对转接盒设备）方向：从设备到QQ
（10）MUTE
方向：从QQ到设备
七、错误码定义
7.1从QQ到设备――EVEN T_QQAPI_ERROR
事件说明：从QQ到设备的错误通知
参数说明：WM_COPPDA TA中的参数COPPDATASTRUCT结构说明详见2 dwData（事件码）：20
lpData：如下表
八、参数类型码表。