QQAPI设计说明书.doc

范文范例参考 WORD 格式整理 QQ API 设计说明书设计说明书 深圳腾讯计算机系统有限公司深圳腾讯计算机系统有限公司 范文范例参考 WORD 格式整理 目录目录 一 引言一 引言 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 KEY 5 4 4 EVENT QQAPI CALL 6 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 ERROR 10 八 参数类型码表八 参数类型码表 1111 范文范例参考 WORD 格式整理 一 引言一 引言 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 SDK RegisterWindowMessage 进行下列系统消息的注册 例如 RegisterWindowMessage WM QQAPI REGISTER 3 1 WM QQAPI REGISTER 消息名 注册消息 方向 设备 QQ 范文范例参考 WORD 格式整理 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 程序后启动的情况下 范文范例参考 WORD 格式整理 四 从设备到四 从设备到 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 字节键值 详见 键值映射表 键值映射表 键名键值 00 x80 10 x81 20 x82 30 x83 40 x84 50 x85 60 x86 70 x87 范文范例参考 WORD 格式整理 80 x88 90 x89 Down0 x8D Up0 x8E Clear0 x8F OK 呼叫键 0 x91 Cancel 挂断键 0 x92 STAR 0 x93 SHARP 0 x94 Mute 静音键 0 x95 RINGTONG 切换铃声键 0 x96 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 消息参数总长度 参数类型码长度值说明 范文范例参考 WORD 格式整理 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 的显示操作 范文范例参考 WORD 格式整理 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 结尾的字符串 范文范例参考 WORD 格式整理 其中 呼叫句柄为 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 好友 范文范例参考 WORD 格式整理 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