服不服?

不服就证明给自己看

  C++博客 :: 首页 :: 新随笔 :: 联系 :: 聚合  :: 管理 ::
  6 随笔 :: 8 文章 :: 6 评论 :: 0 Trackbacks

QQ API设计说明书
深圳腾讯计算机系统有限公司

目录
一、引言
1.1 编写目的
1.2 更新时间
二、总体设计
三、注册的系统消息
3.1 WM_QQAPI_REGISTER
3.2 WM_QQAPI_REGISTER_RESP
3.3 WM_QQAPI_AVAILABLE
四、从设备到QQ的自定义事件
4.1 EVENT_QQAPI_SET_AUDIODEVICE
4.2 EVENT_QQAPI_GET_USERINFO
4.3 EVENT_QQAPI_PRESS_KEY
4.4 EVENT_QQAPI_CALL
4.5 EVENT_QQAPI_MUTE
4.6 EVENT_QQAPI_UNREGISTER
五、从QQ到设备的自定义事件
5.1 EVENT_QQAPI_USERINFO
5.2 EVENT_QQAPI_STATUS_CHANGE
5.3 EVENT_QQAPI_SHUTDOWN
六、双向的自定义事件
6.1 EVENT_QQAPI_CALL_STATUS
七、错误码定义
7.1 从QQ到设备――EVENT_QQAPI_ERROR
八、参数类型码表


一、引言

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收到这个消息时,弹出“外设控制”窗口等待用户选择,如下:
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

设备名长度

音频设备名,类型:以Null结尾的字符串

6

4字节

音频设备的设备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

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.4 EVENT_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.5 EVENT_QQAPI_MUTE

事件说明:静音设置,根据参数决定是打开静音或者关闭静音
参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2
dwData(事件码):14
lpData:如下表
cbData:消息参数总长度


参数类型码

长度

值说明

12

1字节

静音状态标志。1:静音打开;0:静音关闭

4.6 EVENT_QQAPI_UNREGISTER

事件说明:反注册
参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2
dwData(事件码):15
lpData:NULL
cbData:0
当第三方应用程序退出时,向QQ发送此事件消息,QQ将音频设备切换回系统原有设备。

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

5.1 EVENT_QQAPI_USERINFO

事件说明:返回本地QQ用户信息。对应于4.2 EVENT_QQAPI_GET_USERINFO
参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2
dwData(事件码):16
lpData:如下表
cbData:消息参数总长度


参数类型码

长度

值说明

1

QQ号长度

QQ号,类型:以Null结尾的字符串

2

昵称长度

昵称,类型:以Null结尾的字符串

5.2 EVENT_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.3 EVENT_QQAPI_SHUTDOWN

事件说明:关闭QQ应用程序
参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2
dwData(事件码):18
lpData:NULL
cbData:0
当QQ应用程序退出时,向第三方程序发送此事件消息。

六、双向的自定义事件

6.1 EVENT_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

posted on 2006-04-24 12:59 我的梦想我的游戏 阅读(547) 评论(1)  编辑 收藏 引用

评论

# re: QQ的API,他们简单的使用copydata,没有使用rpc之类 2007-05-31 16:06 Vicky
好东西,谢谢分享!
但I看不懂,去研究研究才行!  回复  更多评论
  


只有注册用户登录后才能发表评论。
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理