QQAPI设计说明书.docx

QQAPI设计说明书.docx

《QQAPI设计说明书.docx》由会员分享，可在线阅读，更多相关《QQAPI设计说明书.docx（16页珍藏版）》请在冰豆网上搜索。

QQAPI设计说明书

QQAPI设计说明书

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

一、引言

1.1编写目的

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

1.2更新时间

最后修订日期：

2005-05-24

版本号：

v1.0

二、总体设计

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

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

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

typedefstructtagCOPYDATASTRUCT{

ULONG_PTRdwData;

DWORDcbData;

PVOIDlpData;

}COPYDATASTRUCT,*PCOPYDATASTRUCT;

dwData：

事件码，标示传送的消息事件码

lpData：

消息参数，采用多个相连的“类型（1字节）＋长度（4字节）＋值”的格式。

所有的参数类型码表见8参数类型码表

cbData：

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

三、注册的系统消息

第三方程序使用WindowsSDK――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_AVAILABLE

消息名：

QQAPI可用消息

方向：

QQà设备

wParam：

发送方的窗口句柄，即QQ程序的窗口句柄

lParam：

QQAPI版本号，目前为1

当QQ启动后，向所有Windows窗口广播这个消息：

SendMessage（HWND_BROADCAST,WM_QQAPI_AVAILABLE,QQ窗口句柄,0）;

当第三方应用程序收到这个消息时，再发起WM_QQAPI_REGISTER消息进行注册。

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

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

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

事件说明：

获取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字节

键值，详见“键值映射表”

键值映射表：

键名

键值

0

0x80

1

0x81

2

0x82

3

0x83

4

0x84

5

0x85

6

0x86

7

0x87

8

0x88

9

0x89

Down

0x8D

Up

0x8E

Clear

0x8F

OK（呼叫键）

0x91

Cancel（挂断键）

0x92

STAR（*）

0x93

SHARP（#）

0x94

Mute（静音键）

0x95

RINGTONG（切换铃声键）

0x96

4.4EVENT_QQAPI_CALL

事件说明：

直接呼叫一个好友用户

参数说明：

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

dwData（事件码）：

13

lpData：

如下表

cbData：

消息参数总长度

通过QQ号呼叫：

参数类型码

长度

值说明

1

QQ号长度

QQ号，类型：

以Null结尾的字符串

通过昵称呼叫：

参数类型码

长度

值说明

2

昵称长度

昵称，类型：

以Null结尾的字符串

通过速播号呼叫：

参数类型码

长度

值说明

3

速播号长度

速播号，类型：

以Null结尾的字符串

通过PSTN号码呼叫：

参数类型码

长度

值说明

4

PSTN号码长度

PSTN号码，类型：

以Null结尾的字符串

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：

0

当第三方应用程序退出时，向QQ发送此事件消息，QQ将音频设备切换回系统原有设备。

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

5.1EVENT_QQAPI_USERINFO

事件说明：

返回本地QQ用户信息。

对应于4.2EVENT_QQAPI_GET_USERINFO

参数说明：

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

dwData（事件码）：

16

lpData：

如下表

cbData：

消息参数总长度

参数类型码

长度

值说明

1

QQ号长度

QQ号，类型：

以Null结尾的字符串

2

昵称长度

昵称，类型：

以Null结尾的字符串

5.2EVENT_QQAPI_STATUS_CHANGE

事件说明：

QQ上的各种状态变化通知

参数说明：

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

dwData（事件码）：

17

lpData：

如下表

cbData：

消息参数总长度

状态变化类型说明：

（1）DIALNUM

说明：

拨号时的号码变化。

参数子项依次为：

参数类型码

长度

值说明

11

1字节

DIALNUM，状态变换类型码：

1

1

QQ号长度

QQ号，类型：

以Null结尾的字符串

当用户拨号，QQ在收号时，如果号码发生变换，例如用户在键盘上按一个号码，或用户在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_COPYDATA中的参数COPYDATASTRUCT结构说明详见2

dwData（事件码）：

19

lpData：

如下表

cbData：

消息参数总长度

呼叫状态类型说明：

（1）CONNECTING

方向：

从QQ到设备

说明：

呼出，正在等待对方应答。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

CONNECTING，呼叫状态类型码：

1

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

10

1字节

通话人数，类型：

char

1

QQ号长度

QQ号，类型：

以Null结尾的字符串

2

昵称长度

昵称，类型：

以Null结尾的字符串

其中，呼叫句柄为QQ分配的唯一呼叫标识符；通话人数为同时呼出的QQ个数；接下来紧跟的2个参数子项为被呼叫的QQ好友信息，如果被呼叫的QQ好友有多个，则有多个QQ好友信息。

回铃音由QQ控制播放。

（2）RING

方向：

从QQ到设备

说明：

呼入，振铃。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

RING，呼叫状态类型码：

2

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

1

QQ号长度

QQ号，类型：

以Null结尾的字符串

2

昵称长度

昵称，类型：

以Null结尾的字符串

4（可选）

PSTN号码长度

PSTN号码，类型：

以Null结尾的字符串

其中，呼叫句柄为QQ分配的唯一呼叫标识符；接下来的2个参数子项为呼入QQ好友信息；最后一个参数项为可选项，呼出的PSTN号码，该号码直接由呼叫方指定，本地QQ完成呼叫转移，转到PSTN号码上。

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

（3）BUSY（针对转接盒设备）

方向：

双向

说明：

占线。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

BUSY，呼叫状态类型码：

3

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

从QQ到设备：

呼出，等待对方应答，且当对方的设备被PSTN占用时，则QQ向本地设备发送占线状态。

从设备到QQ：

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

（4）ACCEPT

方向：

从QQ到设备

说明：

呼入或呼出，某方接受，双方进入通话状态。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

ACCEPT，呼叫状态类型码：

4

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

（5）REJECT

方向：

从QQ到设备

说明：

呼入或呼出，某方拒绝。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

REJECT，呼叫状态类型码：

5

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

（6）FINISH

方向：

从QQ到设备

说明：

呼入或呼出，通话结束，无论哪方发起。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

FINISH，呼叫状态类型码：

6

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

（7）FAIL

方向：

从QQ到设备

说明：

呼出失败。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

FAIL，呼叫状态类型码：

7

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

失败原因可能是，呼叫的用户不是QQ好友。

（8）HOLD（针对转接盒设备）

方向：

从设备到QQ

说明：

暂停通话，通话被切换到PSTN。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

HOLD，呼叫状态类型码：

8

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

（9）RESUME（针对转接盒设备）

方向：

从设备到QQ

说明：

恢复通话，通话被切换到回QQ。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

RESUME，呼叫状态类型码：

9

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

（10）MUTE

方向：

从QQ到设备

说明：

静音状态通知。

参数子项依次为：

参数类型码

长度

值说明

8

1字节

MUTE，呼叫状态类型码：

10

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

12

1字节

静音状态标志。

1：

静音打开；0：

静音关闭

七、错误码定义

7.1从QQ到设备――EVENT_QQAPI_ERROR

事件说明：

从QQ到设备的错误通知

参数说明：

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

dwData（事件码）：

20

lpData：

如下表

cbData：

消息参数总长度

参数类型码

长度

值说明

12

1字节

错误类型，类型：

char

错误码定义：

八、参数类型码表

参数类型码

长度

值说明

1

QQ号长度

QQ号，类型：

以Null结尾的字符串

2

昵称长度

昵称，类型：

以Null结尾的字符串

3

速播号长度

速播号，类型：

以Null结尾的字符串

4

PSTN号码长度

PSTN号码，类型：

以Null结尾的字符串

5

设备名长度

音频设备名，类型：

以Null结尾的字符串

6

4字节

音频设备的设备ID号，类型：

DWORD

7

1字节

键值，详见4.3的“键值映射表”

8

1字节

呼叫状态的类型，类型：

char，主要有：

（1）CONNECTING，呼叫状态类型码：

1

（2）RING，呼叫状态类型码：

2

（3）BUSY，呼叫状态类型码：

3

（4）ACCEPT，呼叫状态类型码：

4

（5）REJECT，呼叫状态类型码：

5

（6）FINISH，呼叫状态类型码：

6

（7）FAIL，呼叫状态类型码：

7

（8）HOLD，呼叫状态类型码：

8

（9）RESUME，呼叫状态类型码：

9

（10）MUTE，呼叫状态类型码：

10

9

4字节

呼叫句柄（CallHandle），类型：

DWORD

10

1字节

通话人数，类型：

char

注：

通话人数会影响后续的参数子项，例如当通话人数为2，后面会跟两份的QQ用户信息。

11

1字节

状态变换的类型，类型：

char，主要有：

（1）DIALNUM，状态变换类型码：

1

12

1字节

静音状态标志。

1：

静音打开；0：

静音关闭

13

1字节

错误类型，类型：

char