QQ API

QQ API设计说明书目录一、引言    31.1 编写目的    31.2 更新时间    3二、总体设计    3三、注册的系统消息    33.1 WM_QQAPI_REGISTER    33.2 WM_QQAPI_REGISTER_RESP    43.3 WM_QQAPI_AVAILABLE    4四、从设备到QQ的自定义事件    54.1 EVENT_QQAPI_SET_AUDIODEVICE    54.2 EVENT_QQAPI_GET_USERINFO    54.3 EVENT_QQAPI_PRESS_KEY    54.4 EVENT_QQAPI_CALL    64.5 EVENT_QQAPI_MUTE    64.6 EVENT_QQAPI_UNREGISTER    7五、从QQ到设备的自定义事件    75.1 EVENT_QQAPI_USERINFO    75.2 EVENT_QQAPI_STATUS_CHANGE    75.3 EVENT_QQAPI_SHUTDOWN    8六、双向的自定义事件    86.1 EVENT_QQAPI_CALL_STATUS    8七、错误码定义    107.1 从QQ到设备――EVENT_QQAPI_ERROR    10八、参数类型码表    11 一、引言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消息名:注册消息方向:设备?QQwParam:发送方的窗口句柄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结构说明详见2dwData(事件码):10lpData:如下表cbData:消息参数总长度参数类型码    长度    值说明5    设备名长度    音频设备名,类型:以Null结尾的字符串6    4字节    音频设备的设备ID号,类型:DWORD第三方应用程序可通过音频设备名字字符串或者通过设备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(事件码):12lpData:如下表cbData:消息参数总长度参数类型码    长度    值说明7    1字节    键值,详见“键值映射表” 键值映射表:键名    键值0    0x801    0x812    0x823    0x834    0x845    0x856    0x867    0x878    0x889    0x89Down    0x8DUp    0x8EClear    0x8FOK (呼叫键)    0x91Cancel (挂断键)    0x92STAR (*)    0x93SHARP (#)    0x94Mute (静音键)    0x95RINGTONG (切换铃声键)    0x964.4 EVENT_QQAPI_CALL事件说明:直接呼叫一个好友用户参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):13lpData:如下表cbData:消息参数总长度通过QQ号呼叫:参数类型码    长度    值说明1    QQ号长度    QQ号,类型:以Null结尾的字符串通过昵称呼叫:参数类型码    长度    值说明2    昵称长度    昵称,类型:以Null结尾的字符串通过速播号呼叫:参数类型码    长度    值说明3    速播号长度    速播号,类型:以Null结尾的字符串通过PSTN号码呼叫:参数类型码    长度    值说明4    PSTN号码长度    PSTN号码,类型:以Null结尾的字符串4.5 EVENT_QQAPI_MUTE事件说明:静音设置,根据参数决定是打开静音或者关闭静音参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):14lpData:如下表cbData:消息参数总长度参数类型码    长度    值说明12    1字节    静音状态标志。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参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):16lpData:如下表cbData:消息参数总长度参数类型码    长度    值说明1    QQ号长度    QQ号,类型:以Null结尾的字符串2    昵称长度    昵称,类型:以Null结尾的字符串5.2 EVENT_QQAPI_STATUS_CHANGE事件说明:QQ上的各种状态变化通知参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):17lpData:如下表cbData:消息参数总长度状态变化类型说明:(1)    DIALNUM说明:拨号时的号码变化。参数子项依次为:参数类型码    长度    值说明11    1字节    DIALNUM,状态变换类型码:11    QQ号长度    QQ号,类型:以Null结尾的字符串当用户拨号,QQ在收号时,如果号码发生变换,例如用户在键盘上按一个号码,或用户在PC上按一个号码,或用户按清除键Clear,那么,QQ向第三方程序发送此事件通知。第三方程序可通过此事件通知来进行拨号过程中LCD的显示操作。5.3 EVENT_QQAPI_SHUTDOWN事件说明:关闭QQ应用程序参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):18lpData:NULLcbData:0当QQ应用程序退出时,向第三方程序发送此事件消息。六、双向的自定义事件6.1 EVENT_QQAPI_CALL_STATUS事件说明:呼叫状态通知参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):19lpData:如下表cbData:消息参数总长度呼叫状态类型说明:(1)CONNECTING方向:从QQ到设备说明:呼出,正在等待对方应答。参数子项依次为:参数类型码    长度    值说明8    1字节    CONNECTING,呼叫状态类型码:19    4字节    呼叫句柄(CallHandle),类型:DWORD10    1字节    通话人数,类型:char1    QQ号长度    QQ号,类型:以Null结尾的字符串2    昵称长度    昵称,类型:以Null结尾的字符串其中,呼叫句柄为QQ分配的唯一呼叫标识符;通话人数为同时呼出的QQ个数;接下来紧跟的2个参数子项为被呼叫的QQ好友信息,如果被呼叫的QQ好友有多个,则有多个QQ好友信息。回铃音由QQ控制播放。(2)RING方向:从QQ到设备说明:呼入,振铃。参数子项依次为:参数类型码    长度    值说明8    1字节    RING,呼叫状态类型码:29    4字节    呼叫句柄(CallHandle),类型:DWORD1    QQ号长度    QQ号,类型:以Null结尾的字符串2    昵称长度    昵称,类型:以Null结尾的字符串4(可选)    PSTN号码长度    PSTN号码,类型:以Null结尾的字符串其中,呼叫句柄为QQ分配的唯一呼叫标识符;接下来的2个参数子项为呼入QQ好友信息;最后一个参数项为可选项,呼出的PSTN号码,该号码直接由呼叫方指定,本地QQ完成呼叫转移,转到PSTN号码上。如果RINGING带了“呼出的PSTN号码”,则本地不振铃,直接转移呼出;如果RINGING没带“呼出的PSTN号码”,则本地振铃。(3)BUSY(针对转接盒设备)方向:双向说明:占线。参数子项依次为:参数类型码    长度    值说明8    1字节    BUSY,呼叫状态类型码:39    4字节    呼叫句柄(CallHandle),类型:DWORD从QQ到设备:呼出,等待对方应答,且当对方的设备被PSTN占用时,则QQ向本地设备发送占线状态。从设备到QQ:呼入,本地振铃,且当本地设备被PSTN占用时,则本地设备向QQ发送占线状态。(4)ACCEPT方向:从QQ到设备说明:呼入或呼出,某方接受,双方进入通话状态。参数子项依次为:参数类型码    长度    值说明8    1字节    ACCEPT,呼叫状态类型码:49    4字节    呼叫句柄(CallHandle),类型:DWORD (5)REJECT方向:从QQ到设备说明:呼入或呼出,某方拒绝。参数子项依次为:参数类型码    长度    值说明8    1字节    REJECT,呼叫状态类型码:59    4字节    呼叫句柄(CallHandle),类型:DWORD (6)FINISH方向:从QQ到设备说明:呼入或呼出,通话结束,无论哪方发起。参数子项依次为:参数类型码    长度    值说明8    1字节    FINISH,呼叫状态类型码:69    4字节    呼叫句柄(CallHandle),类型:DWORD (7)FAIL方向:从QQ到设备说明:呼出失败。参数子项依次为:参数类型码    长度    值说明8    1字节    FAIL,呼叫状态类型码:79    4字节    呼叫句柄(CallHandle),类型:DWORD失败原因可能是,呼叫的用户不是QQ好友。(8)HOLD(针对转接盒设备)方向:从设备到QQ说明:暂停通话,通话被切换到PSTN。参数子项依次为:参数类型码    长度    值说明8    1字节    HOLD,呼叫状态类型码:89    4字节    呼叫句柄(CallHandle),类型:DWORD (9)RESUME(针对转接盒设备)方向:从设备到QQ说明:恢复通话,通话被切换到回QQ。参数子项依次为:参数类型码    长度    值说明8    1字节    RESUME,呼叫状态类型码:99    4字节    呼叫句柄(CallHandle),类型:DWORD (10)MUTE方向:从QQ到设备说明:静音状态通知。参数子项依次为:参数类型码    长度    值说明8    1字节    MUTE,呼叫状态类型码:109    4字节    呼叫句柄(CallHandle),类型:DWORD12    1字节    静音状态标志。1:静音打开;0:静音关闭七、错误码定义7.1 从QQ到设备――EVENT_QQAPI_ERROR事件说明:从QQ到设备的错误通知参数说明:WM_COPYDATA中的参数COPYDATASTRUCT结构说明详见2dwData(事件码):20lpData:如下表cbData:消息参数总长度参数类型码    长度    值说明12    1字节    错误类型,类型:char错误码定义:八、参数类型码表参数类型码    长度    值说明1    QQ号长度    QQ号,类型:以Null结尾的字符串2    昵称长度    昵称,类型:以Null结尾的字符串3    速播号长度    速播号,类型:以Null结尾的字符串4    PSTN号码长度    PSTN号码,类型:以Null结尾的字符串5    设备名长度    音频设备名,类型:以Null结尾的字符串6    4字节    音频设备的设备ID号,类型:DWORD7    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,呼叫状态类型码:109    4字节    呼叫句柄(CallHandle),类型:DWORD10    1字节    通话人数,类型:char注:通话人数会影响后续的参数子项,例如当通话人数为2,后面会跟两份的QQ用户信息。11    1字节    状态变换的类型,类型:char,主要有:(1)DIALNUM,状态变换类型码:112    1字节    静音状态标志。1:静音打开;0:静音关闭13    1字节    错误类型,类型:char文章引用自:

你可能感兴趣的:(windows,qq,struct,api,null,文档)