QQ API设计说明书.doc

《QQ API设计说明书.doc》由会员分享，可在线阅读，更多相关《QQ API设计说明书.doc（11页珍藏版）》请在沃文网上搜索。

1、腾讯文档 QQ API设计说明书QQ API设计说明书深圳腾讯计算机系统有限公司目录一、引言31.1 编写目的31.2 更新时间3二、总体设计3三、注册的系统消息33.1 WM_QQAPI_REGISTER33.2 WM_QQAPI_REGISTER_RESP43.3 WM_QQAPI_AVAILABLE4四、从设备到QQ的自定义事件54.1 EVENT_QQAPI_SET_AUDIODEVICE54.2 EVENT_QQAPI_GET_USERINFO54.3 EVENT_QQAPI_PRESS_KEY54.4 EVENT_QQAPI_CALL64.5 EVENT_QQAPI_MUTE64.

2、6 EVENT_QQAPI_UNREGISTER7五、从QQ到设备的自定义事件75.1 EVENT_QQAPI_USERINFO75.2 EVENT_QQAPI_STATUS_CHANGE75.3 EVENT_QQAPI_SHUTDOWN8六、双向的自定义事件86.1 EVENT_QQAPI_CALL_STATUS8七、错误码定义107.1 从QQ到设备EVENT_QQAPI_ERROR10八、参数类型码表11一、引言1.1 编写目的本文档提供了QQ API接口说明，以供第三方应用程序使用，用于QQ和硬件设备（例如USB Phone）的交互。1.2 更新时间最后修订日期：2005-05-24版

3、本号：v1.0二、总体设计QQ应用程序和第三方应用程序以收发消息的方式进行通讯。双方未成功注册之前，采用RegisterWindowMessage（Windows API）注册的系统消息进行交互，注册成功后，双方分别获取对方的窗口句柄，接下来的交互通过收发WM_COPYDATA（Windows消息）消息完成。WM_COPYDATA的wParam参数为发送方的窗口句柄，lParam为指向COPYDATASTRUCT结构的指针，COPYDATASTRUCT定义如下：typedef struct tagCOPYDATASTRUCT ULONG_PTRdwData; DWORD cbData; PVO

4、ID lpData; COPYDATASTRUCT, *PCOPYDATASTRUCT;dwData：事件码，标示传送的消息事件码lpData：消息参数，采用多个相连的“类型（1字节）长度（4字节）值”的格式。所有的参数类型码表见8 参数类型码表cbData：消息参数总长度，单位字节三、注册的系统消息第三方程序使用Windows SDKRegisterWindowMessage，进行下列系统消息的注册。例如：RegisterWindowMessage(“WM_QQAPI_REGISTER”);3.1 WM_QQAPI_REGISTER消息名：注册消息方向：设备QQwParam：发送方的窗口句柄

5、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：当wPara

6、m为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_AVAILA

7、BLE, QQ窗口句柄, 0);当第三方应用程序收到这个消息时，再发起WM_QQAPI_REGISTER消息进行注册。这种情况出现在，当第三方应用程序先启动，而QQ程序后启动的情况下。四、从设备到QQ的自定义事件4.1 EVENT_QQAPI_SET_AUDIODEVICE事件说明：设置QQ使用的音频设备参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：10lpData：如下表cbData：消息参数总长度参数类型码长度值说明5设备名长度音频设备名，类型：以Null结尾的字符串64字节音频设备的设备ID号，类型：DWORD第三方应用程序可通

8、过音频设备名字字符串或者通过设备ID号，来发送设置音频设备事件。4.2 EVENT_QQAPI_GET_USERINFO事件说明：获取QQ用户信息参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：11lpData：NULLcbData：0QQ返回的用户信息，见5.1 EVENT_QQAPI_USERINFO。4.3 EVENT_QQAPI_PRESS_KEY事件说明：发送按键消息，当用户在设备上按下任何键时，发送此事件给QQ参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：12lpD

9、ata：如下表cbData：消息参数总长度参数类型码长度值说明71字节键值，详见“键值映射表”键值映射表：键名键值00x8010x8120x8230x8340x8450x8560x8670x8780x8890x89Down0x8DUp0x8EClear0x8FOK (呼叫键)0x91Cancel (挂断键)0x92STAR (*)0x93SHARP (#)0x94Mute (静音键)0x95RINGTONG (切换铃声键)0x964.4 EVENT_QQAPI_CALL事件说明：直接呼叫一个好友用户参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（

10、事件码）：13lpData：如下表cbData：消息参数总长度通过QQ号呼叫：参数类型码长度值说明1QQ号长度QQ号，类型：以Null结尾的字符串通过昵称呼叫：参数类型码长度值说明2昵称长度昵称，类型：以Null结尾的字符串通过速播号呼叫：参数类型码长度值说明3速播号长度速播号，类型：以Null结尾的字符串通过PSTN号码呼叫：参数类型码长度值说明4PSTN号码长度PSTN号码，类型：以Null结尾的字符串4.5 EVENT_QQAPI_MUTE事件说明：静音设置，根据参数决定是打开静音或者关闭静音参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（

11、事件码）：14lpData：如下表cbData：消息参数总长度参数类型码长度值说明121字节静音状态标志。1：静音打开；0：静音关闭4.6 EVENT_QQAPI_UNREGISTER事件说明：反注册参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：15lpData：NULLcbData：0当第三方应用程序退出时，向QQ发送此事件消息，QQ将音频设备切换回系统原有设备。五、从QQ到设备的自定义事件5.1 EVENT_QQAPI_USERINFO事件说明：返回本地QQ用户信息。对应于4.2 EVENT_QQAPI_GET_USERINFO参

12、数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：16lpData：如下表cbData：消息参数总长度参数类型码长度值说明1QQ号长度QQ号，类型：以Null结尾的字符串2昵称长度昵称，类型：以Null结尾的字符串5.2 EVENT_QQAPI_STATUS_CHANGE事件说明：QQ上的各种状态变化通知参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：17lpData：如下表cbData：消息参数总长度状态变化类型说明：（1） DIALNUM说明：拨号时的号码变化。参数子项依次为：参

13、数类型码长度值说明111字节DIALNUM，状态变换类型码：11QQ号长度QQ号，类型：以Null结尾的字符串当用户拨号，QQ在收号时，如果号码发生变换，例如用户在键盘上按一个号码，或用户在PC上按一个号码，或用户按清除键Clear，那么，QQ向第三方程序发送此事件通知。第三方程序可通过此事件通知来进行拨号过程中LCD的显示操作。5.3 EVENT_QQAPI_SHUTDOWN事件说明：关闭QQ应用程序参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：18lpData：NULLcbData：0当QQ应用程序退出时，向第三方程序发送此事件消

14、息。六、双向的自定义事件6.1 EVENT_QQAPI_CALL_STATUS事件说明：呼叫状态通知参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：19lpData：如下表cbData：消息参数总长度呼叫状态类型说明：（1）CONNECTING方向：从QQ到设备说明：呼出，正在等待对方应答。参数子项依次为：参数类型码长度值说明81字节CONNECTING，呼叫状态类型码：194字节呼叫句柄（CallHandle），类型：DWORD101字节通话人数，类型：char1QQ号长度QQ号，类型：以Null结尾的字符串2昵称长度昵称，类型：以N

15、ull结尾的字符串其中，呼叫句柄为QQ分配的唯一呼叫标识符；通话人数为同时呼出的QQ个数；接下来紧跟的2个参数子项为被呼叫的QQ好友信息，如果被呼叫的QQ好友有多个，则有多个QQ好友信息。回铃音由QQ控制播放。（2）RING 方向：从QQ到设备说明：呼入，振铃。参数子项依次为：参数类型码长度值说明81字节RING，呼叫状态类型码：294字节呼叫句柄（CallHandle），类型：DWORD1QQ号长度QQ号，类型：以Null结尾的字符串2昵称长度昵称，类型：以Null结尾的字符串4（可选）PSTN号码长度PSTN号码，类型：以Null结尾的字符串其中，呼叫句柄为QQ分配的唯一呼叫标识符；接下来

16、的2个参数子项为呼入QQ好友信息；最后一个参数项为可选项，呼出的PSTN号码，该号码直接由呼叫方指定，本地QQ完成呼叫转移，转到PSTN号码上。如果RINGING带了“呼出的PSTN号码”，则本地不振铃，直接转移呼出；如果RINGING没带“呼出的PSTN号码”，则本地振铃。（3）BUSY（针对转接盒设备）方向：双向说明：占线。参数子项依次为：参数类型码长度值说明81字节BUSY，呼叫状态类型码：394字节呼叫句柄（CallHandle），类型：DWORD从QQ到设备：呼出，等待对方应答，且当对方的设备被PSTN占用时，则QQ向本地设备发送占线状态。从设备到QQ：呼入，本地振铃，且当本地设备被

17、PSTN占用时，则本地设备向QQ发送占线状态。（4）ACCEPT方向：从QQ到设备说明：呼入或呼出，某方接受，双方进入通话状态。参数子项依次为：参数类型码长度值说明81字节ACCEPT，呼叫状态类型码：494字节呼叫句柄（CallHandle），类型：DWORD（5）REJECT方向：从QQ到设备说明：呼入或呼出，某方拒绝。参数子项依次为：参数类型码长度值说明81字节REJECT，呼叫状态类型码：594字节呼叫句柄（CallHandle），类型：DWORD（6）FINISH方向：从QQ到设备说明：呼入或呼出，通话结束，无论哪方发起。参数子项依次为：参数类型码长度值说明81字节FINISH，呼叫

18、状态类型码：694字节呼叫句柄（CallHandle），类型：DWORD（7）FAIL方向：从QQ到设备说明：呼出失败。参数子项依次为：参数类型码长度值说明81字节FAIL，呼叫状态类型码：794字节呼叫句柄（CallHandle），类型：DWORD失败原因可能是，呼叫的用户不是QQ好友。（8）HOLD（针对转接盒设备）方向：从设备到QQ说明：暂停通话，通话被切换到PSTN。参数子项依次为：参数类型码长度值说明81字节HOLD，呼叫状态类型码：894字节呼叫句柄（CallHandle），类型：DWORD（9）RESUME（针对转接盒设备）方向：从设备到QQ说明：恢复通话，通话被切换到回QQ。参

19、数子项依次为：参数类型码长度值说明81字节RESUME，呼叫状态类型码：994字节呼叫句柄（CallHandle），类型：DWORD（10）MUTE方向：从QQ到设备说明：静音状态通知。参数子项依次为：参数类型码长度值说明81字节MUTE，呼叫状态类型码：1094字节呼叫句柄（CallHandle），类型：DWORD121字节静音状态标志。1：静音打开；0：静音关闭七、错误码定义7.1 从QQ到设备EVENT_QQAPI_ERROR事件说明：从QQ到设备的错误通知参数说明：WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData（事件码）：20lpData：如下表c

20、bData：消息参数总长度参数类型码长度值说明121字节错误类型，类型：char错误码定义：八、参数类型码表参数类型码长度值说明1QQ号长度QQ号，类型：以Null结尾的字符串2昵称长度昵称，类型：以Null结尾的字符串3速播号长度速播号，类型：以Null结尾的字符串4PSTN号码长度PSTN号码，类型：以Null结尾的字符串5设备名长度音频设备名，类型：以Null结尾的字符串64字节音频设备的设备ID号，类型：DWORD71字节键值，详见4.3的“键值映射表”81字节呼叫状态的类型，类型：char，主要有：（1）CONNECTING，呼叫状态类型码：1（2）RING，呼叫状态类型码：2（3）

21、BUSY，呼叫状态类型码：3（4）ACCEPT，呼叫状态类型码：4（5）REJECT，呼叫状态类型码：5（6）FINISH，呼叫状态类型码：6（7）FAIL，呼叫状态类型码：7（8）HOLD，呼叫状态类型码：8（9）RESUME，呼叫状态类型码：9（10）MUTE，呼叫状态类型码：1094字节呼叫句柄（CallHandle），类型：DWORD101字节通话人数，类型：char注：通话人数会影响后续的参数子项，例如当通话人数为2，后面会跟两份的QQ用户信息。111字节状态变换的类型，类型：char，主要有：（1）DIALNUM，状态变换类型码：1121字节静音状态标志。1：静音打开；0：静音关闭131字节错误类型，类型：char第 11 页 共 11 页