内容发布更新时间 : 2024/12/23 12:14:12星期一 下面是文章的全部内容请认真阅读。

QQ API设计说明书

深圳腾讯计算机系统有限公司

目录

一、引言 .......................................................... 3

1.1 编写目的 ....................................................................................................................................... 3 1.2 更新时间 ....................................................................................................................................... 3

二、总体设计 ...................................................... 3 三、注册的系统消息 ................................................. 3

3.1 WM_QQAPI_REGISTER .............................................................................................................. 3 3.2 WM_QQAPI_REGISTER_RESP .................................................................................................. 4 3.3 WM_QQAPI_AVAILABLE ........................................................................................................... 4

四、从设备到QQ的自定义事件 ........................................ 5

4.1 EVENT_QQAPI_SET_AUDIODEVICE ....................................................................................... 5 4.2 EVENT_QQAPI_GET_USERINFO .............................................................................................. 5 4.3 EVENT_QQAPI_PRESS_KEY ..................................................................................................... 5 4.4 EVENT_QQAPI_CALL ................................................................................................................. 6 4.5 EVENT_QQAPI_MUTE ................................................................................................................ 6 4.6 EVENT_QQAPI_UNREGISTER .................................................................................................. 7

五、从QQ到设备的自定义事件 ........................................ 7

5.1 EVENT_QQAPI_USERINFO ........................................................................................................ 7 5.2 EVENT_QQAPI_STATUS_CHANGE .......................................................................................... 7 5.3 EVENT_QQAPI_SHUTDOWN .................................................................................................... 7

六、双向的自定义事件 ............................................... 8

6.1 EVENT_QQAPI_CALL_STATUS ................................................................................................ 8

七、错误码定义 ................................................... 10

7.1 从QQ到设备――EVENT_QQAPI_ERROR ........................................................................... 10

八、参数类型码表.................................................. 10

一、引言

1.1 编写目的

本文档提供了QQ API接口说明，以供第三方应用程序使用，用于QQ和硬件设备（例如USB Phone）的交互。

1.2 更新时间

最后修订日期：2005-05-24 版本号：v1.0

二、总体设计

QQ应用程序和第三方应用程序以收发消息的方式进行通讯。

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

WM_COPYDATA的wParam参数为发送方的窗口句柄，lParam为指向COPYDATASTRUCT结构的指针，COPYDATASTRUCT定义如下：

typedef struct tagCOPYDATASTRUCT{ ULONG_PTR dwData; DWORD cbData; PVOID lpData;

}COPYDATASTRUCT, *PCOPYDATASTRUCT; dwData：事件码，标示传送的消息事件码

lpData：消息参数，采用多个相连的“类型（1字节）＋长度（4字节）＋值”的格式。所有的参数类型码表见8 参数类型码表

cbData：消息参数总长度，单位字节

三、注册的系统消息

第三方程序使用Windows SDK――RegisterWindowMessage，进行下列系统消息的注册。例如：RegisterWindowMessage(“WM_QQAPI_REGISTER”);

3.1 WM_QQAPI_REGISTER

消息名：注册消息 方向：设备?QQ

wParam：发送方的窗口句柄

lParam：QQ API版本号，目前为100，表示1.00。

第三方应用程序启动并检测到可用的设备后，向所有Windows窗口广播这个消息，带上自己的窗口句柄作为消息参数，如下：

SendMessage( HWND_BROADCAST, WM_QQAPI_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_QQAPI_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程序后启动的情况下。

四、从设备到QQ的自定义事件

4.1 EVENT_QQAPI_SET_AUDIODEVICE

事件说明：设置QQ使用的音频设备

参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2

dwData（事件码）：10 lpData：如下表

cbData：消息参数总长度 参数类型码 5 6 长度 设备名长度 4字节 值说明 音频设备名，类型：以Null结尾的字符串 音频设备的设备ID号，类型：DWORD 第三方应用程序可通过音频设备名字字符串或者通过设备ID号，来发送设置音频设备事件。

4.2 EVENT_QQAPI_GET_USERINFO

事件说明：获取QQ用户信息

参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2

dwData（事件码）：11 lpData：NULL cbData：0

QQ返回的用户信息，见5.1 EVENT_QQAPI_USERINFO。

4.3 EVENT_QQAPI_PRESS_KEY

事件说明：发送按键消息，当用户在设备上按下任何键时，发送此事件给QQ 参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2

dwData（事件码）：12 lpData：如下表

cbData：消息参数总长度 参数类型码 7 键值映射表：

键名 0 1 2 3 4 5 6 7

长度 1字节 值说明 键值，详见“键值映射表” 键值 0x80 0x81 0x82 0x83 0x84 0x85 0x86 0x87