QQ API设计说明书.doc

QQ API 设计说明书设计说明书 深圳腾讯计算机系统有限公司深圳腾讯计算机系统有限公司 目录目录 一、引言一、引言3 3 1.1 编写目的.3 1.2 更新时间.3 二、总体设计二、总体设计3 3 三、注册的系统消息三、注册的系统消息3 3 3.1 WM_QQAPI_REGISTER.3 3.2 WM_QQAPI_REGISTER_RESP.4 3.3 WM_QQAPI_AVAILABLE.4 四、从设备到四、从设备到 QQQQ 的自定义事件的自定义事件5 5 4.1 EVENT_QQAPI_SET_AUDIODEVICE .5 4.2 EVENT_QQAPI_GET_USERINFO.5 4.3 EVENT_QQAPI_PRESS_KEY5 4.4 EVENT_QQAPI_CALL6 4.5 EVENT_QQAPI_MUTE.6 4.6 EVENT_QQAPI_UNREGISTER.7 五、从五、从 QQQQ 到设备的自定义事件到设备的自定义事件7 7 5.1 EVENT_QQAPI_USERINFO.7 5.2 EVENT_QQAPI_STATUS_CHANGE 7 5.3 EVENT_QQAPI_SHUTDOWN.8 六、双向的自定义事件六、双向的自定义事件8 8 6.1 EVENT_QQAPI_CALL_STATUS.8 七、错误码定义七、错误码定义1010 7.1 从 QQ 到设备EVENT_QQAPI_ERROR10 八、参数类型码表八、参数类型码表1111 一、引言一、引言 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_PTRdwData; DWORD cbData; PVOID lpData; COPYDATASTRUCT, *PCOPYDATASTRUCT; dwData：事件码，标示传送的消息事件码 lpData：消息参数，采用多个相连的“类型（1 字节）长度（4 字节）值”的格式。所有的参数类 型码表见 8 参数类型码表 cbData：消息参数总长度，单位字节 三、注册的系统消息三、注册的系统消息 第三方程序使用 Windows SDKRegisterWindowMessage，进行下列系统消息的注册。例如： 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 安全警告”框，直接返回 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 结尾的字符串 64 字节音频设备的设备 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：消息参数总长度 参数类型码长度值说明 71 字节键值，详见“键值映射表” 键值映射表： 键名键值 00x80 10x81 20x82 30x83 40x84 50x85 60x86 70x87 80x88 90x89 Down0x8D Up0x8E Clear0x8F 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 号呼叫： 参数类型码长度值说明 1QQ 号长度QQ 号，类型：以 Null 结尾的字符串 通过昵称呼叫： 参数类型码长度值说明 2昵称长度昵称，类型：以 Null 结尾的字符串 通过速播号呼叫： 参数类型码长度值说明 3速播号长度速播号，类型：以 Null 结尾的字符串 通过 PSTN 号码呼叫： 参数类型码长度值说明 4PSTN 号码长 度 PSTN 号码，类型：以 Null 结尾的字符串 4.5 EVENT_QQAPI_MUTE 事件说明：静音设置，根据参数决定是打开静音或者关闭静音 参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2 dwData（事件码）：14 lpData：如下表 cbData：消息参数总长度 参数类型码长度值说明 121 字节静音状态标志。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：消息参数总长度 参数类型码长度值说明 1QQ 号长度QQ 号，类型：以 Null 结尾的字符串 2昵称长度昵称，类型：以 Null 结尾的字符串 5.2 EVENT_QQAPI_STATUS_CHANGE 事件说明：QQ 上的各种状态变化通知 参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2 dwData（事件码）：17 lpData：如下表 cbData：消息参数总长度 状态变化类型说明： （1）DIALNUM 说明：拨号时的号码变化。参数子项依次为： 参数类型码长度值说明 111 字节DIALNUM，状态变换类型码：1 1QQ 号长度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 到设备 说明：呼出，正在等待对方应答。参数子项依次为： 参数类型码长度值说明 81 字节CONNECTING，呼叫状态类型码：1 94 字节呼叫句柄（CallHandle） ，类型：DWORD 101 字节通话人数，类型：char 1QQ 号长度QQ 号，类型：以 Null 结尾的字符串 2昵称长度昵称，类型：以 Null 结尾的字符串 其中，呼叫句柄为 QQ 分配的唯一呼叫标识符；通话人数为同时呼出的 QQ 个数；接下来紧跟 的 2 个参数子项为被呼叫的 QQ 好友信息，如果被呼叫的 QQ 好友有多个，则有多个 QQ 好友信息。 回铃音由 QQ 控制播放。 （2）RING 方向：从 QQ 到设备 说明：呼入，振铃。参数子项依次为： 参数类型码长度值说明 81 字节RING，呼叫状态类型码：2 94 字节呼叫句柄（CallHandle） ，类型：DWORD 1QQ 号长度QQ 号，类型：以 Null 结尾的字符串 2昵称长度昵称，类型：以 Null 结尾的字符串 4（可选）PSTN 号码长 度 PSTN 号码，类型：以 Null 结尾的字符串 其中，呼叫句柄为 QQ 分配的唯一呼叫标识符；接下来的 2 个参数子项为呼入 QQ 好友信息；最 后一个参数项为可选项，呼出的 PSTN 号码，该号码直接由呼叫方指定，本地 QQ 完成呼叫转移，转 到 PSTN 号码上。如果 RINGING 带了“呼出的 PSTN 号码”，则本地不振铃，直接转移呼出；如果 RINGING 没带“呼出的 PSTN 号码”，则本地振铃。 （3）BUSY（针对转接盒设备） 方向：双向 说明：占线。参数子项依次为： 参数类型码长度值说明 81 字节BUSY，呼叫状态类型码：3 94 字节呼叫句柄（CallHandle） ，类型：DWORD 从 QQ 到设备：呼出，等待对方应答，且当对方的设备被 PSTN 占用时，则 QQ 向本地设备发送 占线状态。 从设备到 QQ：呼入，本地振铃，且当本地设备被 PSTN 占用时，则本地设备向 QQ 发送占线状 态。 （4）ACCEPT 方向：从 QQ 到设备 说明：呼入或呼出，某方接受，双方进入通话状态。参数子项依次为： 参数类型码长度值说明 81 字节ACCEPT，呼叫状态类型码：4 94 字节呼叫句柄（CallHandle） ，类型：DWORD （5）REJECT 方向：从 QQ 到设备 说明：呼入或呼出，某方拒绝。参数子项依次为： 参数类型码长度值说明 81 字节REJECT，呼叫状态类型码：5 94 字节呼叫句柄（CallHandle） ，类型：DWORD （6）FINISH 方向：从 QQ 到设备 说明：呼入或呼出，通话结束，无论哪方发起。参数子项依次为： 参数类型码长度值说明 81 字节FINISH，呼叫状态类型码：6 94 字节呼叫句柄（CallHandle） ，类型：DWORD （7）FAIL 方向：从 QQ 到设备 说明：呼出失败。参数子项依次为： 参数类型码长度值说明 81 字节FAIL，呼叫状态类型码：7 94 字节呼叫句柄（CallHandle） ，类型：DWORD 失败原因可能是，呼叫的用户不是 QQ 好友。 （8）HOLD（针对转接盒设备） 方向：从设备到 QQ 说明：暂停通话，通话被切换到 PSTN。参数子项依次为： 参数类型码长度值说明 81 字节HOLD，呼叫状态类型码：8 94 字节呼叫句柄（CallHandle） ，类型：DWORD （9）RESUME（针对转接盒设备） 方向：从设备到 QQ 说明：恢复通话，通话被切换到回 QQ。参数子项依次为： 参数类型码长度值说明 81 字节RESUME，呼叫状态类型码：9 94 字节呼叫句柄（CallHandle） ，类型：DWORD （10）MUTE 方向：从 QQ 到设备 说明：静音状态通知。参数子项依次为： 参数类型码长度值说明 81 字节MUTE，呼叫状态类型码：10 94 字节呼叫句柄（CallHandle） ，类型：DWORD 121 字节静音状态标志。1：静音打开；0：静音关闭 七、错误码定义七、错误码定义 7.1 从从 QQ 到设备到设备EVENT_QQAPI_ERROR 事件说明：从 QQ 到设备的错误通知 参数说明：WM_COPYDATA 中的参数 COPYDATASTRUCT 结构说明详见 2 d