QQAPI设计项目说明指导书.doc

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 8
六、双向自定义事件 8
6.1 EVENT_QQAPI_CALL_STATUS 8
七、错误码定义 10
7.1 从QQ到设备――EVENT_QQAPI_ERROR 10
八、参数类型码表 11
一、引言
1.1 编写目标
本文档提供了QQ API接口说明，以供第三方应用程序使用，用于QQ和硬件设备（比如USB Phone）交互。
1.2 更新时间
最终修订日期：-05-24
版本号：v1.0
二、总体设计
QQ应用程序和第三方应用程序以收发消息方法进行通讯。
双方未成功注册之前，采取RegisterWindowMessage（Windows API）注册系统消息进行交互，注册成功后，双方分别获取对方窗口句柄，接下来交互经过收发WM_COPYDATA（Windows消息）消息完成。
WM_COPYDATAwParam参数为发送方窗口句柄，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安全警告”框，直接返回REJECTWM_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