LumaQQ开发文档
QQ协议体系概述
Luma, 清华大学
更新时间: 2005-04-04
QQ的协议非常庞大，这些做一些概述，要注意，不要认为下面的说法一定是对的，只能说目前看起来好像是这样 :
加密解密
QQ的加密解密用的是TEA算法(puzzlebird的说法)，不详细解释了。QQ的包一般都是加密的（包头包尾除外），但是有个别包是不加密的，以后如果不做特别说明，则默认这个包是需要加密的。 此外，用什么密钥加密也有不同，不过基本上都是用会话密钥加密，以后如果不做特殊说明，表示是用会话密钥加密 。这里要注意一下，有时候你收到的包可能不是用会话密钥加密的，比如离线的消息。你人都不在了，哪里来的会话密钥？所以服务器在你下次登录的时候，会把你还没收到过的消息用密码密钥加密再传给你。这是一种特殊的情况，要分清楚。
UDP和TCP
QQ支持UDP和TCP登录（如果使用HTTP代理，则相当于TCP登录），UDP登录没有什么好说的，TCP登录时，不管什么包的开头两字节都是包长度，这个长度包括了这两个字节。
包头包尾
QQ协议有多种包头，每种包头都分别代表了一类用途的包，但是不是所有的包都有包尾，以下是一些存在的包头包尾格式参考
包头 包尾 包头之后的固定格式 说明 0x00 无 发送方QQ版本，或者是服务器版本，2字节 随机密钥，1字节，如果这个字节是0x23，那么密钥就是0x23232323，这个密钥用来加密发送者和接受者的QQ号。加密算法: QQ号取反再与密钥异或 发送者QQ号的加密形式，4字节 接受者QQ号的加密形式，4字节 0x00系列的包，用在文件传输过程中，传递控制信息。也会出现在点对点通信中。 0x02 0x03 源标志, 2字节，表示了这个包从何处来，主要用来标识客户端版本，如果其标识的是服务器，这个字段的具体用处还不清楚 包命令, 2字节 包序号, 2字节, 原则是保证短期内这个序号不要重复就可以，一般我们处理的时候都是递增，到最大再归0 0x02系列包主要完成一些基本任务，基本上处理了这个系列的包，QQ的功能就差不多了。 0x03 无 格式同第一行 0x03系列的包，用在文件传输过程中，传递数据信息 0x04 0x03 客户端版本号，2字节 整个的包长，2字节 序号，2字节 我的QQ号，4字节 未知的8字节 0x04系列的包，用在文件传输过程中，如果使用服务器中转模式传送文件，则用到这些包 0x06 未知 未知 还没怎么研究过这种包是干什么的
请求登录令牌
Luma, 清华大学
更新时间: 2005-04-03
登录QQ，要发的第一个包就是Request Login Token Packet。这个包会向服务器请求一个24字节大小的令牌（也不一定是24，只能说目前是24字节），然后在接下来的登录中，没有这个令牌，你是登录不 了的。这个令牌是在服务器端生成的，具体的生成算法我们当然还无从得知，但是它肯定是参考了你的IP，你的端口，还有你的其他什么信息生成这个令牌的。因 为你把在A机器上得到的令牌用到B机器上，你就会登录不了，如果你把A机器上的IP给改了，你照样也登录不了。
请求包格式
头部
未知的1字节，0x00
尾部
Note: 此包不加密
回复包格式
头部 回复码，1字节，0x00表示成功 登录令牌长度，1字节 登录令牌 尾部 Note: 此包不加密
成功时
操作成功时，核心层会触发 QQ_GET_LOGIN_TOKEN_SUCCESS 事件，这个事件携带的包是 RequestLoginTokenReplyPacket ，可用的字段如下:
replyCode: byte，回复码 loginToken: byte[]，包含了得到的登录令牌失败时
操作失败时，核心层会触发 QQ_GET_LOGIN_TOKEN_FAIL 事件，这个事件携带的包是 RequestLoginTokenReplyPacket ，可用的字段如下:
replyCode: byte，回复码登录
Luma, 清华大学
更新时间: 2005-04-04
QQ登录目前有多种模式，比如普通QQ号，电子邮件登录，绑定手机号登录，还有什么普通模式，TM模式。目前我们只支持普通模式和QQ号登录。
请求包格式 头部 初始密钥，16字节 用户的密码密钥加密一个空串得到的16字节 36字节的固定内容，未知含义 登录状态，隐身登录还是什么，1字节 16字节固定内容，未知含义 登录令牌长度，1字节 登录令牌 登录模式，1字节，目前只支持普通模式 未知1字节，0x40 后面段的个数，1字节，1个段9字节(猜测) 段，每次基本都是固定内容，未知含义 长度不足则全部填0直到符合登录包长度，UDP模式登录请求包长度为416字节 尾部 Note: 此包使用初始密钥加密，注意头部之后就是初始密钥，初始密钥是不加密的。
说明
初始密钥在2004以前用的是一个固定值: 16个0x01字节。2004之后，采用随机密钥 密码密钥是通过对用户的密码进行2次MD5生成的 密码密钥加密一个空串是干什么呢？主要是服务器用来验证密码的，如果服务器能用密码密钥解开这16个字节，那么它就认为密码是正确的。在这里，我们不一定非要加密一个空串，其实任意字符串都可以，但是你要保证密文只有16个字节。 登录请求包的固定内容，含义是未知的，而且，也不能说内容是固定的，即使我们把这些字段全部替换成0，依然能够登录回复包格式
回复包可能有多种情况，包体的第一个字节是回复码，可能的取值如下：
QQ_LOGIN_REPLY_OK : 登录成功 QQ_LOGIN_REPLY_REDIRECT : 重定向 QQ_LOGIN_REPLY_PASSWORD_ERROR : 密码错误 QQ_LOGIN_REPLY_OK： 头部 回复码，1字节 会话密钥，16字节 用户的QQ号，4字节 用户的IP，4字节 用户的端口，2字节 服务器的IP，4字节 服务器的端口，2字节 本次登录时间，4字节 未知的26字节 未知服务器1的IP，服务器的作用未知，4字节 未知服务器1的端口，2字节 未知服务器2的IP，4字节 未知服务器2的端口，2字节 2个未知字节 2个未知字节 Client Key, 32字节 12个未知字节 上次登录时的IP，4字节 上次登录时的时间，4字节 8个未知字节 尾部 QQ_LOGIN_REPLY_REDIRECT： 头部 回复码，1字节 用户QQ号，4字节 重定向的服务器IP，4字节 重定向的服务器端口，2字节 尾部 QQ_LOGIN_REPLY_PASSWORD_ERROR: 头部 回复码，1字节 错误消息字符串 尾部 Note: 登录回复包使用密码密钥加密，或者使用初始密钥加密，在处理时，应该先尝试使用密码密钥解密，如果失败，则再用初始密钥解密。为什么要这样呢，因为你可能密码输入错误，这样的话服务器用密码密钥加密的包你就解密不了了，所以会用初始密钥加密。说明
时间都是4个字节，其表示从1970-1-1开始的毫秒数再除以1000 Client Key是用在访问一些网络服务时，比如QQ秀，通过Client Key，TX可以直接定位到你的QQ秀页面，还有什么QQ家园啦，有可能聊天室也要用到这个。 那些未知的服务器，可能是用来发广告用的，猜想～成功时
登录成功或者重定向时，核心层会触发 QQ_LOGIN_SUCCESS 事件，这个事件携带的包是 LoginReplyPacket ，用户应该检查replyCode的值，然后进行相应的操作：
当replyCode为 QQ_LOGIN_REPLY_OK 时，有以下字段可用：
重定向到零地址时
在登录高峰期，登录重定向时有可能得到一个0地址，这时核心层会触发 QQ_LOGIN_REDIRECT_NULL 事件，这个事件携带的包是 LoginReplyPacket ，不过这个包没有什么可用信息。
密码错误时
如果密码错误，核心层会触发 QQ_LOGIN_PASSWORD_ERROR 事件，这个事件携带的包是 LoginReplyPacket ，可用的字段如下：
replyMessage: String, 错误信息字符串未知错误时
如果回复码不是以上三种，则核心层会触发 QQ_LOGIN_UNKNOWN_ERROR 事件，这个事件携带的包是 LoginReplyPacket ，但是没有可用字段。
改变状态
Luma, 清华大学
更新时间: 2005-04-05
登录之后的第一件事就是切换自己的状态，不然你发不出消息，这个一定要注意了，不是登录成功之后就能发消息，而是改变状态之后才能发消息。LumaQQ核心层自动处理登录后的状态改变，所以基本上你可以不管状态改变的事件，就看你的需要了。
请求包格式
头部
想要切换到的状态，1字节，定义如下
QQ_FRIEND_STATUS_ONLINE : 在线
QQ_FRIEND_STATUS_OFFLINE : 离线
QQ_FRIEND_STATUS_AWAY : 离开
QQ_FRIEND_STATUS_HIDDEN : 隐身
是否显示虚拟摄像头，4字节，最低位置1表示显示虚拟摄像头，其他位似乎无用
尾部
回复包格式
头部 回复码，1字节，0x30表示成功，相关常量 QQ_CHANGE_STATUS_REPLY_OK 尾部
成功时
操作成功时，核心层会触发 QQ_CHANGE_STATUS_SUCCESS 事件，这个事件携带的包是 ChangeStatusReplyPacket ，可用的字段如下:
replyCode: byte，回复码失败时
操作失败时，核心层会触发 QQ_CHANGE_STATUS_FAIL 事件，这个事件携带的包是 ChangeStatusReplyPacket ，可用的字段如下:
replyCode: byte，回复码得到好友列表
Luma, 清华大学
更新时间: 2005-04-07
登录之后还需要得到好友列表。现在得到好友列表这个包重要性已经不太高了，因为这个包无法得到分组信息，只能得到列表，你看到现在QQ 2004以上版本都是自动就把你的分组都同步下来，这个光用得到好友列表的功能做不到，我想这个包现在只是做为兼容性的考虑还存在。
请求包格式
头部
起始好友列表返回位置，2字节。假设你有10个好友，这个字段你设置成3，那么就从第3个
好友开始返回，预期你应该得到7个好友。那么第三个是怎么界定的？服务器是按照你的好友的QQ从小到大排序决定的。另外，为什么需要这个字段，主要是怕你
好友太多，一个包得不完，QQ服务器端的设定是一次只返回50个好友。 返回的好友列表是否排序, 1字节。相关常量如下：
QQ_FRIEND_LIST_SORTED: 排序
QQ_FRIEND_LIST_UNSORTED: 不排序
尾部
回复包格式
头部 下一次好友列表开始位置，2字节。你的好友很多，还需要再请求，那么你下次要把请求包中的起始位置字段置成这个值。如果这个字段是0xFFFF，那就是服务器告诉你，你的好友都得到了。和起始位置相关的常量有： QQ_FRIEND_LIST_POSITION_START: 开始请求好友列表。你发第一个包的时候应该把起始位置置为这个值 QQ_FRIEND_LIST_POSITION_END: 好友已经全部得到 好友QQ号，4字节 头像，2字节 年龄，1字节 性别，1字节 昵称长度，1字节 昵称 2个未知字节 1字节扩展标志，bit1表示是否有QQ Show，其他未知 1字节通用标志 bit1 => 会员 bit4 => TCP方式登陆 bit5 => 开发移动QQ bit6 => 绑定到手机 bit7 => 是否有摄像头 如果有更多好友，重复3 - 11部分 尾部
成功时
操作成功时，核心层会触发 QQ_GET_LOGIN_TOKEN_SUCCESS 事件，这个事件携带的包是 GetFriendListReplyPacket ，可用的字段如下:
position: char, 下一个请求包的起始位置 friends: List, 包含了好友的信息，每个好友的信息由一个QQFriend类封装，请查看edu.tsinghua.lumaqq.qq.beans.QQFriend.java文件了解这个类的字段信息失败时
尚未有操作失败事件的定义，因为我不知道如何才是失败，这么久了，这个操作就从没失败过，所以我不知道失败的包是什么样子的。
得到在线好友
Luma, 清华大学
更新时间: 2005-04-08
一般在得到好友列表之后就是得到在线好友了，当然你也可以先得到在线好友再得到好友列表，这个没什么限制。不过你可能会想：好友上线下线的时候会收 到通知，那还要得到在线好友干什么呢？因为这种通知是不可靠的，可能由于种种原因，你经常会收不到这个通知，所以得到在线好友是必须的，QQ的作法是在 Keep Alive的时候刷新一次来保持最新的在线列表，而Keep Alive是1分钟做一次的。需要说明的是，这个请求包并非只能得到好友，注意看下面的包格式分析。
请求包格式
头部
好友类型，1字节。目前发现这个字节置为0x02或者0x03时服务器会有反应，其他都会
返回0xFF。置为0x02时，得到的就是好友，置为0x03时，得到的是另外一些东西，b好像是系统服务，号码比如72000001到
72000013，就是那些移动QQ，会员服务之类的 在线好友列表起始位置，1字节，含义同得到好友列表中的起始位置字段，只不过它只根据在线的来排。
1个未知字节，一般设为0x00
2个未知字节，一般设为0x0000
尾部
回复包格式
头部 下一个请求包的起始位置，含义同得到好友列表的回复包。相关常量如下： QQ_FRIEND_ONLINE_LIST_POSITION_START: 开始请求在线好友列表。你发第一个包的时候应该把起始位置置为这个值 QQ_FRIEND_ONLINE_LIST_POSITION_END: 在线好友已经全部得到 好友的QQ号，4字节 未知的1字节 好 友的IP，4字节。这里提一下，这个字段只有在点对点模式时才有值，如果对方设置的是服务器模式，则这里都是0。但是在以前呢，都是有的，所以这是腾讯服 务器的一个bug，在腾讯发布2005 Beta1的这段时间左右，它修正了这个bug，服务器模式不再返回ip了。所以珊瑚虫得到ip的效果已经打了折扣了。不过对于这种这种情况，如来神掌依 然可以得到IP。 好友的端口，2字节 未知的1字节 好友的状态，1字节，相关常量如下，需要注意的是，隐身状态是得不到的，所以只会返回3种状态 QQ_FRIEND_STATUS_ONLINE: 在线 QQ_FRIEND_STATUS_OFFLINE: 离线 QQ_FRIEND_STATUS_AWAY: 离开 QQ_FRIEND_STATUS_HIDDEN: 隐身 未知的2字节 16字节的密钥，用处未知，不过猜想是用在点对点通信中 2个未知字节 1字节扩展标志，bit1表示是否有QQ Show，其他未知 1字节通用标志 bit1 => 会员 bit4 => TCP方式登陆 bit5 => 开发移动QQ bit6 => 绑定到手机 bit7 => 是否有摄像头 2个未知字节 分隔符，1字节，0x00 如果有更多在线好友，重复3 - 15部分 尾部
说明:
回复包的3 - 15部分封装在edu.tsinghua.lumaqq.qq.beans.FriendOnlineEntry.java中，而3 - 10部分又是封装在edu.tsinghua.lumaqq.qq.beans.FriendStatus.java中的，所以 FriendOnlineEntry里面包含了一个FriendStatus的对象。
成功时
操作成功时，核心层会触发 QQ_GET_FRIEND_ONLINE_SUCCESS 事件，这个事件携带的包是 GetFriendOnlineReplyPacket ，可用的字段如下:
position: byte, 下一个请求包的起始位置 onlineFriends: List，FriendOnlineEntry类的列表失败时
尚未有操作失败事件的定义，因为我不知道如何才是失败，这么久了，这个操作就从没失败过，所以我不知道失败的包是什么样子的。
Keep Alive
Luma, 清华大学
更新时间: 2005-04-17
Keep Alive这个包，用来使QQ服务器知道自己还在线，至于到底你多久不发Keep Alive就认为你不在线，这个还不清楚，感觉好像挺长的一段时间不发都没事，所以服务器端到底有没有真的在意这个包，我说不准，QQ自己是1分钟发一次 的，建议实现你自己的程序的时候参考这个间隔，你要2分钟发一次，当然也可以。这个包本身的作用很小，只能用来得到QQ总在线人数，它最主要的作用还是起 到一个定时器的用处，你可以顺便在Keep Alive之后做一些事情，比如得到在线好友数，得到群在线成员数，都可以在这个包之后做，so，把他当成一个固定操作的触发手段吧。
请求包格式
头部
用户QQ号的字符串形式
尾部
回复包格式
头部 6个域，分别是"0", "0", 所有在线用户数，我的IP，我的端口，未知含义字段，用ascii码31分隔 尾部
成功时
操作成功时，核心层会触发 QQ_KEEP_ALIVE_SUCCESS 事件，这个事件携带的包是 KeepAliveReplyPacket ，可用的字段如下:
onlines: int, 总在线人数 ip: String, 我的外部IP的字符串形式 port: int, 我的外部端口失败时
目前无失败事件定义，因为它从来就没失败过，所以也不知道失败的时候是什么样的
得到用户资料
Luma, 清华大学
更新时间: 2005-04-27
查看用户资料是个很基本的功能了，用户资料有很多，这个就看QQ版本了，那么2004目前是包含了37个字段，如果是2004 II，恐怕又会多些个性签名之类，你要是用2004 II的协议，自然是要与时俱进的。
请求包格式
头部
你想查看资料的用户QQ号的字符串形式
尾部
回复包格式
头部 用户资料，37个域，不管域的类型是整数还是什么，都采用字符串形式表示。每个域之间用字符'0'分隔。这30个域的顺序你不用关心，他们都被包装在了 edu.tsinghua.lumaqq.qq.beans.ContactInfo 类中 尾部
成功时的事件
操作成功时，核心层会触发 QQ_GET_USER_INFO_SUCCESS 事件，这个事件携带的包是 GetUserInfoReplyPacket ，可用的字段如下:
contactInfo: ContactInfo对象失败时的事件
操作失败时，核心层会触发 QQ_GET_USER_INFO_FAIL 事件，这个事件携带的包是 GetUserInfoReplyPacket ，无可用字段
登出
Luma, 清华大学
更新时间: 2005-04-27
退出QQ，要发送Logout命令，这个命令是不需要等待回复的，也就是说你发了之后就可以退出程序了，那么为了保证服务器能够收到你的登出命令， 你需要多发几次，比如像QQ的做法是发送4次，你想发多少次就随便你了，我觉得这个也不是强制要做的，比如你只想发一次，也行，服务器收不到就收不到吧， 影响也不大，说不定还能继续长你在线时间呃。
请求包格式 头部，包序号需要指定为0xFFFF，但是这个只是QQ的做法，指定为其他的是否可以，没有试验过，你感兴趣可以试试 用session key加密的password key 尾部
这个包没有回复包，所以也没有相关联的事件了。
查找用户
Luma, 清华大学
更新时间: 2005-04-27
QQ有很多种查找方式，这里是最简单的一种查找方式，2004版本开始有了高级查找，我们后面再介绍。以前我们只能查找全部在线用户，或者根据用户的一些特定信息查找（叫做自定义查找)。所以这个命令又包含两种搜索方式。
请求包格式 搜索方式的相关常量如下: QQ_SEARCH_ALL: 查找全部在线用户 QQ_SEARCH_CUSTOM: 自定义查找
搜索方式为 QQ_SEARCH_ALL 时:
头部 搜索方式，1字节 1字节分隔符: 0x1F 页号的 十进制字符串形式，从0开始。你应该知道在线用户是很多的，所以要分成多页来显示。实际上这个页号是否真的有用也不好说，你如果不停的请求得到第0页的用 户，你会发现返回结果都不一样，所以，这个页号有没有用很难说，不知道服务器是怎么做的。按照常理呢，你还是在程序中递增这个页号吧。 尾部搜索方式为 QQ_SEARCH_CUSTOM 时:
头部 搜索方式，1字节 1字节分隔符: 0x1F 要搜索的用户的QQ号的字符串形式 1字节分隔符: 0x1F 要搜索的用户的昵称 1字节分隔符: 0x1F 要搜索的用户的email 1字节分隔符: 0x1F 页号的字符串形式 1个字节，0x00，应该是结束符吧，因为前面是页号，考虑c语言的字符串表示方式，这个应该是页号的结束符 尾部 对于那些不存在的条件，把这个字段置为空就是了回复包格式 搜索的结果，有两种情况，一种是搜到了一些用户，一种是没搜到，这好像是废话哈？嗯，那么重要的是这种结果之后的含义，没搜到简单啊，那你就应该停止发送搜索请求了。要是搜到了呢？还继续搜不？这个当然就看你自己了，你想继续就继续，但是要记得把页号加1。
没搜到时：
头部 字符串"-1"，变成16进制就是0x2D31 尾部搜到时:
头部 用户的资料，每个用户有4个字段，字段的顺序是"QQ号，昵称，地区，头像号码"，注意这些字 段都是字符串形式。所以为了分隔这些字段，同时为了分隔这些用户，这里面有两种分隔符：0x1F用来分隔用户，0x1E用来分隔用户的4个字段。要注意的 是边界的情况，因为头像号码是最后一个字段，所以头像号码后面不是0x1E而是0x1F。那么自然QQ号前面也是0x1F。另外，第一个用户前面没有 0x1F。搜索的结果被封装在 edu.tsinghua.lumaqq.qq.beans.UserInfo 中，一个用户对应一个UserInfo。 尾部成功时
操作成功时，核心层会触发 QQ_SEARCH_USER_SUCCESS 事件，这个事件携带的包是 SearchUserReplyPacket ，可用的字段如下:
finished: boolean, true表示后面还可能有更多的匹配，你应该页号加1继续搜 users: java.util.List，里面存放的是UserInfo对象搜索结束时
操作成功时，核心层会触发 QQ_SEARCH_USER_END 事件，这个事件携带的包是 SearchUserReplyPacket ，可用的字段如下:
finished: boolean, 既然是搜索结束，这个字段当然是true失败时
因为目前未知还没失败过，所以不知道失败时候的模样，自然也没有失败的事件了