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