Webqq-Client/lib/Webqq/Client.pod
=pod
=encoding utf8
=head1 NAME
Webqq::Client - A webqq client in Perl Language
=head1 SYNOPSIS
use Webqq::Client;
use Digest::MD5 qw(md5_hex);
my $qq = 12345678;
#使用md5_hex将你的qq密码进行md5加密后再传递给Webqq::Client
#我可不想被怀疑有盗号行为
my $pwd = md5_hex('your password');
#通过new来初始化一个客户端对象
#debug=>1来打印debug信息方便调试
my $client = Webqq::Client->new(debug=>0);
#通过login进行登录
$client->login( qq=> $qq, pwd => $pwd);
#登录成功后设置客户端的接收消息回调函数
$client->on_receive_message = sub{
#当收到消息后，传递给回调函数的唯一参数是原始消息的一个hash引用
my $msg = shift;
...;
#你可以对收到的消息进行任意的处理
#你也可以使用Data::Dumper这样的模块来查看消息的结构，比如
#use Data::Dumper;
#print Dumper $msg;
};
#客户端进入事件循环,正式开始运行
$client->run();
=head1 IMPORTANT NOTICE
该模块会逐步停止维护，取而代之的是该模块的重构模块 L<Mojo::Webqq> 具有如下优势：
基于L<Mojolicious>框架，实现统一的阻塞和非阻塞HTTP请求，统一的日志系统，更好的对象支持，更灵活的事件管理机制
弊端：要求perl版本5.10+
=head1 CLIENT ASYNCHRONOUS FRAMEWORK
client
|
->login()
|
| +-------------------------<------------------------------+
| | |
|->_recv_message()-[put]-> Webqq::Message::Queue -[get]-> on_receive_message()
|
|->send_message() -[put]--+ +-[get]-> _send_message() ---+
| \ / |
|->send_sess_message()-[put]-Webqq::Message::Queue-[get]->_send_sess_message()-|
| / \ |
|->send_group_message()-[put]-+ +-[get]->_send_group_message()--|
| |
| on_send_message() ---<---- msg->{cb} -------<-------+
+->run()
请注意：
由于采用了单线程异步框架
你不应该在任何回调函数中产生长时间的阻塞
这会导致整个进程被阻塞，无法正常响应处理其他回调
=head1 CLIENT DATA STRUCTURE
客户端登录成功后，会马上更新个人信息、好友信息、群信息
这些相关的信息通过多重hash引用的形式存储在如下形式中：
$client->{qq_database}{
user => {}, #个人信息存储在 %{ $client->{qq_database}{user} }中
friends => [], #好友信息存储在 @{ $client->{qq_database}{friends} }中
group_list => [], #群列表信息（不含群成员）存储在@{$client->{qq_database}{group_list}}中
group => [], #群信息（包含群成员）存储在 @{ $client->{qq_database}{group} } 中
discuss => [], #讨论组信息
recent => [], #最近联系人/群/讨论组列表
discuss_list=> [], #讨论组列表信息
}
=over
=item %{ $client->{qq_database}{user} } 个人信息
一般情况下，你不应该直接操作该数据结构，而应该通过类提供的方法进行查询
hash包含的key及相关说明,注意有些key的值并不是直接的结果，通常是一些索引编号等需要做额外的转换
比如生肖的值是数字0，1，2，3，很容易猜测和12生肖依次对应，这部分可以自行研究
face => #作用未知
birthday => #生日
phone => #电话
occupation => #职业
allow => #权限
college => #大学
qq => #qq号码
uin => #本次登录唯一标识，发送消息时需要用到
blood => #血型
constel => #星座
homepage => #主页
state => #状态 online|away|busy|callme|silent|hidden
country => #国家
city => #城市
personal => #个性签名
nick => #昵称
shengxiao => #生肖
email => #邮箱
token => #作用未知
client_type => #客户端类型 由于采用的是webqq协议，自身登录类型恒为"web"
province => #省份
gender => #性别
mobile => #手机
例如想获取昵称，可以通过
$client->{qq_database}{user}{nick}
来获取
=item @{ $client->{qq_database}{friends} } 好友信息
一般情况下，你不应该直接操作该数据结构，而应该通过类提供的方法进行查询，参见：
$client->search_friend()
$client->update_friends_info()
好友信息存储在数组中，数组中的每个元素又是一个hash的引用
[
{#数组中第1个元素-好友1
flag => #作用未知
qq => #好友的qq号码，需要安装Webqq::Qun模块
uin => #发送接收消息唯一uin
categories => #好友所属分组
nick => #好有昵称
face => #作用未知
markname => #好友备注
is_vip => #是否是vip
vip_level => #vip等级
state => #好友状态 online|offline|away|busy|callme|silent
client_type => #好友的客户端类型 pc|mobile|iphone|web|unknown
},
{#数组中第2个元素-好友2
flag =>
uin =>
categories =>
nick =>
face =>
markname =>
is_vip =>
vip_level =>
state =>
client_type =>
},
...#依此类推
]
比如我要在好友数据库中查找昵称是"小灰"的好友所属的分组，需要这样遍历查找：
for my $each_friend (@{ $client->{qq_database}{friends} }) {
if( $each_friend->{nick} eq "小灰" ){
print "小灰所属的分组是：",$each_friend->{categories},"\n"
}
}
=item @{ $client->{qq_database}{group_list} } 群列表（不包含群成员）信息
一般情况下，你不应该直接操作该数据结构，而应该通过类提供的方法进行查询，参见：
$client->update_group_list_info();
由于群包含的成员数量很多，很多时候我们只需要知道有加入了哪些群，并不关心群里具体的
每一位成员，这种情况下只需要获取群列表信息即可，和好友信息类似，群列表信息也是存储在
一个数组中，数组中的每个元素又是一个hash引用
[
{#数组中第1个元素，群1
flag => #作用未知
name => #群名称
gid => #群的uin，发送接收消息时使用
code => #群的gcode，查找群信息时需要用到
markname => #群备注名称
type => #create|attend|manage 分别表示创建的群|加入的群|管理的群, 需要安装Webqq::Qun模块
number => #群号码 需要安装Webqq::Qun模块
},
{#数组中第2个元素，群2
flag =>
name =>
gid =>
code =>
markname =>
type =>
number =>
},
...#依此类推
]
比如我要查找gcode是123456的群对应的群名称
for my $each_group (@{ $client->{qq_database}{group_list} }){
if($each_group->{code} == 123456){
print $each_group->{name};
}
}
我要向群名称是"PERL学习交流"的群发送"hello world"消息
发送消息需要先获取到群的uin（也就是gid）
my $gid ;
for my $each_group (@{ $client->{qq_database}{group_list} }){
if($each_group->{name} eq "PERL学习交流" ){
$gid = $each_group->{gid}
}
}
if($gid){
$client->send_group_message(
$client->create_group_msg(to_uin=>$gid, content=>"hello world")
);
}
=item @{ $client->{qq_database}{group} } 群信息（包含群成员）
一般情况下，你不应该直接操作该数据结构，而应该通过类提供的方法进行查询，参见：
$client->search_group();
$client->update_group_info();
$client->search_member_in_group();
此结构更为复杂一些，每个群信息仍然存在放一个数组中，
[
{#第1个群
ginfo => {
face => #作用未知
memo => #群介绍
class => #群类别
fingermemo => #
code => #群的gcode，和$client->{qq_database}{group_list}一致
createtime => #群创建时间
flag => #
level => #群等级
name => #群名称
gid => #群gid ，和$client->{qq_database}{group_list}一致
owner => #群主的uin
number => #群号码, 需要安装Webqq::Qun模块
type => #create|attend|manage 分别表示创建的群|加入的群|管理的群, 需要安装Webqq::Qun模块
},
minfo => [
{#群里第1个成员
nick => #该成员昵称
province => #该成员省份
gender => #该成员性别
uin => #该成员uin
country => #该成员国家
city => #该成员城市
card => #群名片
state => #online|offline|away|busy|callme|silent
client_type => #pc|mobile|iphone|web|known
qq => #qq号, 需要安装Webqq::Qun模块
qage => #q龄, 需要安装Webqq::Qun模块
join_time => #入群时间, 需要安装Webqq::Qun模块
last_speak_time => #最后发言时间, 需要安装Webqq::Qun模块
level => #等级 灌水|传说|潜水 等, 需要安装Webqq::Qun模块
role => #角色 admin|owner|member, 需要安装Webqq::Qun模块
bad_record => #是否有不良记录 0|1， 需要安装Webqq::Qun模块
},
{#群里第2个成员
},
...,
]
},
{#第2个群
ginfo => {},
minfo => {},
},
...
]
比如我要统计第1个群里女性群成员数量
my $female_member = 0;
for my $each_member @{ $client->{qq_database}{group}[0]{minfo} }{
if($each_member->{gender} eq 'female'){
$female_member++;
}
}
=item @{ $client->{qq_database}{disucss_list} } 讨论组列表（不包含成员）信息
一般情况下，你不应该直接操作该数据结构，而应该通过类提供的方法进行查询，参见：
$client->update_discuss_list_info();
数组中的每个元素又是一个hash引用，存储每个讨论组的基本信息
[
{#数组中第1个元素，讨论组1
name => #讨论组名称
did => #讨论组的uin，发送接收消息时使用
},
{#数组中第2个元素，讨论组2
name =>
did =>
},
...#依此类推
]
=item @{ $client->{qq_database}{discuss} } 讨论组信息（包含成员）
一般情况下，你不应该直接操作该数据结构，而应该通过类提供的方法进行查询，参见：
$client->search_discuss();
$client->update_discuss_info();
$client->search_member_in_discuss();
此结构更为复杂一些，每个讨论组信息仍然存在放一个数组中，
[
{#第1个讨论组
dinfo => {
name => #讨论组名称
did => #讨论组did ，和$client->{qq_database}{discuss_list}一致
owner =>
},
minfo => [
{#讨论组里第1个成员
nick => #该成员昵称
uin => #该成员uin
state => #online|offline|away|busy|callme|silent
client_type => #pc|mobile|iphone|web|known
},
{#讨论组里第2个成员
},
...,
]
},
{#第2个讨论组
dinfo => {},
minfo => {},
},
...
]
讨论组 和 群 的概念和操作均极为相似，这里不做过多展开
=item @{$client->{qq_database}{recent} } 最近联系列表
[
{
uin => #联系对象uin, type是group，uin指gid，type是discuss，此uin指讨论组的did
type => #联系对象的类型 friend|group|discuss
},
{
uin =>
type =>
}
...,
]
=back
每个接收和发送的消息均存储在一个单独的hash引用中,根据消息类型的不同，内容上稍有出入
与此同时，采用了Automated Accessor Generation的手段，
每个hash的key产生一个对应的函数来方便读取，每个消息hash引用还绑定了一些方法
关于Automated Accessor Generation可以参见cpan Class::Accessor
注意：发送和接收消息对应的方法名称和数量可能不同
=over
=item 发送消息结构
create_sess_msg()/create_group_msg()create_discuss_msg()/create_msg()/reply_message()等会生成此消息结构
send_message()/send_sess_message()/send_group_message()/send_discuss_message()等需要用到此消息结构
$msg = {
type => #类型，"message"|"group_message"|"sess_message|discuss_message"
msg_id => #消息id，系统自动维护
from_uin => #发送者uin，就是自己的uin,系统自动维护
to_uin => #接收者或者接收群的uin
content => #发送内容
msg_class = "send" #消息类别,用于区分是发送还是接收的消息
msg_time => #消息发送时间，系统自动维护
cb => #该消息发送完成后的回调函数
group_code => #群消息需要设置,发送群临时消息时需要设置，其他情况系统自动维护
send_uin => #群消息需要设置,系统自动维护
ttl => #发送消息带有一个ttl值，默认是5，当ttl减为0时会被发送消息队列丢弃
allow_plugin => #是否允许插件处理该消息标记，插件之间互相配合需要用到
}
由于采用了Automated Accessor Generation的手段，因此当你要获取$msg中的某个key对应value时，
你可以才有两种方式：
方式1：
$msg->{type};
方式2：
$msg->type;
接收到的消息结构也有类似的特性，不再说明
$msg除上述hash的key以外绑定的方法：
如果发送消息是群消息
$msg->group_name();#发送消息对应的群名称
$msg->to_gname(); #消息对应的群名称
$msg->from_qq(); #发送者的qq号
$msg->from_nick(); #发送者的昵称
如果发送消息是好友消息
$msg->from_nick #发送者昵称
$msg->from_qq #发送者qq号
$msg->to_nick #接收者昵称
$msg->to_qq #接收者qq号
$msg->to_markname #接收者备注
$msg->to_categories #接收者所属分组
如果发送消息是临时消息
$msg->from_qq() #获取发送者qq号
$msg->from_nick() #获取发送者昵称
$msg->to_qq() #获取接收者qq号
$msg->to_nick() #获取接收者昵称
$msg->via_name() #获取接收者所在的群或者讨论组名称
$msg->via_type() #判断临时消息是来自群还是讨论组，值为二者之一："group"|"discuss"
=item 接收到的好友消息结构
$msg = {
type => "message"
msg_id #系统自动维护
from_uin #消息发送者的uin，可以使用此uin进行消息回复
to_uin #消息接收者的uin，也就是自己的uin
msg_time #消息发送时刻
content #消息内容，UTF-8编码，表情会转换成为文字，例如"[系统表情]","[图片]"
raw_content => [], #一个数组引用，原始消息按图片、表情、文本等形式分别存储在数组中
msg_class = "recv"
allow_plugin #是否允许插件处理该消息标记，插件之间互相配合需要用到
ttl #默认是5，当ttl减为0时会被发送消息队列丢弃
}
$msg->{raw_content}中的每一个元素又是一个hash的引用
好友消息、群消息、临时消息均包含该结构，不再重复说明
文本类消息的hash引用为
{
type => 'txt',
content => 'xxxxxxx', #utf8编码的文本消息
}
非好友自定义图片消息的hash引用为
{
type => 'cface',
content => '[图片]',
name => 'xxxx.jpg',#文件名
server => 'xxx.xxx.xxx.xxx:80', #图片存储服务器
file_id => '图片文件id',
}
好友自定义图片消息的hash引用为
{
type => 'offpic',
content => '[图片]',
file_path => '/xxxxxx-xxxx-xxxx-xxx' #图片路径，下载图片时需要用到
}
表情类消息的hash引用为
{
type => 'face',
content => '[微笑]',
id => 14, #表情的唯一数字id
}
$msg除上述hash的key以外绑定的方法：
$msg->from_qq() #获取发送者qq号
$msg->from_nick() #获取发送者昵称
$msg->to_qq() #获取接收者qq号
$msg->to_nick() #获取接收者昵称
$msg->from_markname() #获取发送该消息的好友备注名称
$msg->from_categories() #获取发送该消息的好友分组名称
$msg->from_city() #获取发送者所在城市信息
=item 接收到的群消息结构
$msg = {
type = "group_message"
msg_id #系统自动维护
from_uin #消息来源群的uin，也就是群gid，可以使用此uin进行群消息回复
to_uin #消息接收者的uin，也就是自己的uin
msg_time #消息发送时刻
content #消息内容，UTF-8编码，表情会转换成为文字，例如"[系统表情]","[图片]"
send_uin #消息发送者的uin，和from_uin进行区别，此uin是指具体的群成员
group_code #消息来源群的gcode
msg_class = "recv"
raw_content => [], #一个数组引用，原始消息按图片、表情、文本等形式分别存储在数组中
allow_plugin #是否允许插件处理该消息标记，插件之间互相配合需要用到
ttl #默认是5，当ttl减为0时会被发送消息队列丢弃
}
$msg除上述hash的key以外绑定的方法：
$msg->from_qq() #获取发送者qq号
$msg->from_nick() #获取发送者昵称
$msg->to_qq() #获取接收者qq号
$msg->to_nick() #获取接收者昵称
$msg->from_gname() #获取消息群名称
$msg->group_name() #获取消息群名称
$msg->from_card() #获取发送者群名片
$msg->from_city() #获取消息发送者的所在城市信息
=item 接收到的讨论组消息结构
$msg = {
type = "discuss_message"
msg_id #系统自动维护
from_uin #消息来源讨论组的uin，也就是讨论组的did，可以使用此uin进行群消息回复
to_uin #消息接收者的uin，也就是自己的uin
msg_time #消息发送时刻
content #消息内容，UTF-8编码，表情会转换成为文字，例如"[系统表情]","[图片]"
send_uin #消息发送者的uin，和from_uin进行区别，此uin是指具体的讨论组成员
did #消息来源讨论组的did，实际上就是from_uin
msg_class = "recv"
raw_content => [], #一个数组引用，原始消息按图片、表情、文本等形式分别存储在数组中
allow_plugin #是否允许插件处理该消息标记，插件之间互相配合需要用到
ttl #默认是5，当ttl减为0时会被发送消息队列丢弃
}
$msg除上述hash的key以外绑定的方法：
$msg->from_qq() #获取发送者qq号
$msg->from_nick() #获取发送者昵称
$msg->to_qq() #获取接收者qq号
$msg->to_nick() #获取接收者昵称
$msg->discuss_name()#获取消息所属讨论组名称
$msg->from_dname() #获取消息所属讨论组名称
$msg->to_dname() #获取消息所属讨论组名称
=item 接收到的临时消息结构
$msg = {
type = "sess_message"
msg_id #系统自动维护
from_uin #消息来源群的uin，可以使用此uin进行群消息回复
to_uin #消息接收者的uin，也就是自己的uin
msg_time #消息发送时刻
content #消息内容，UTF-8编码，表情会转换成为文字，例如"[系统表情]","[图片]"
gid #临时消息所属的群的gid
did #临时消息所属的讨论组的gid
groud_code #临时消息所属的群的group_code
service_type #临时消息service_type, 0表示群临时消息，1表示讨论组临时消息
msg_class = "recv"
via = "group"|"discuss" 表示临时消息来自群还是讨论组
raw_content => [], #一个数组引用，原始消息按图片、表情、文本等形式分别存储在数组中
allow_plugin #是否允许插件处理该消息标记，插件之间互相配合需要用到
ttl #默认是5，当ttl减为0时会被发送消息队列丢弃
}
$msg除上述hash的key以外绑定的方法：
$msg->from_qq() #获取发送者qq号
$msg->from_nick() #获取发送者昵称
$msg->to_qq() #获取接收者qq号
$msg->to_nick() #获取接收者昵称
$msg->via_name() #获取接收者所在的群或者讨论组名称
$msg->via_type() #判断临时消息是来自群还是讨论组，值为二者之一："group"|"discuss"
=back
=head1 PUBLIC CLASS METHOD
=over
=item new()
返回一个客户端对象
支持的参数
debug=>0|1 ,设置debug=>1来打印调试信息
type=>"webqq"|"smartqq",设置type来切换使用webqq或者smartqq，默认使用smartqq
state=>"online"|"away"|"busy"|"silent"|"hidden"|"offline",设置登录状态，默认"online"
security=>1, 设置是否使用https进行消息发送和接收，默认值为 0, 使用https会导致处理速度稍慢
encrypt_method=>"perl"|"js"，默认采用纯perl加密算法，速度快，当登录错误时会自动使用js计算方式再次重试一遍
webqq是腾讯的老版本，smartqq是最新版本
my $client = Webqq::Client->new(debug=>1);
=item on_send_message() :lvalue
设置客户端发送消息完成后的回调函数，常用于在回调函数中记录发送消息内容或者判断发送消息状态
这是一个具有lvalue属性的subroutine，你必须赋值一个函数引用
$client->on_send_message() = sub{
my ($msg,$is_success,$status) = @_;
...
};
或者使用hash的形式
$client->{on_send_message} = sub{
my ($msg,$is_success,$status) = @_;
...
};
你的回调会在发送消息完成后被立即调用
这个回调通常是用来判断消息的发送状态
传递给回调的参数有三个：
$msg: the original msg
$is_success: the send status, true means success,false means fail
$status: the send status, the value is "发送成功" or "发送失败";
注意，如果发送消息失败，客户端默认会根据$msg->{ttl}重试多次，
因此你不需要再根据$is_success自己再进行重试
=item on_receive_offpic() :lvalue
成功下载到好友发送的图片文件时的回调函数
$client->on_receive_offpic = sub{
my($fh,$filename) = @_;
#$fh为下载到的好友图片文件的文件句柄(只读模式),该句柄会在回调结束后自动被close
#$filename为下载到的好友图片文件的本地临时存储路径，比如/tmp/webqq_offpic_XXXX.png
#$filename所对应的本地临时文件会在回调执行后自动删除
...;
}
注意，目前观察到，腾讯的好友图片下载速度不稳定，有时候会较慢
=item on_receive_message() :lvalue
设置客户端接收消息回调函数，客户端接收到消息后会调用设置的回调函数，讲接收到的消息
通过hash引用的形式传递给回调函数，你可以在此函数中对接收到的消息进行处理
比如打印接收到的消息，对接收到的消息进行应答等
$client->on_receive_message() = sub{
my $msg = shift;
};
传递给回调函数的唯一参数是一个接收到的消息的hash引用，你可以对这个msg进行随意处理
=item on_login() :lvalue
设置客户端登录成功后的回调函数，客户端在登录成功后会调用该回调函数
$client->on_login() = sub{...;};
=item on_run() :lvalue
设置客户端执行run之前的回调
$client->on_run() = sub{...;};
=item on_ready() :lvalue
设置客户端执行ready之前的回调
$client->on_ready() = sub{...;};
=item on_input_img_verifycode() :lvalue
正常情况下，如果你是直接在终端运行webqq，需要输入验证码时
客户端会将验证码图片下载到本地，使用<STDIN>要求你在终端输入，并提示你验证码图片保存路径
如果你的客户端是在后台运行，脱离终端，此时无法再通过<STDIN>输入验证码
如果设置了该回调函数，且客户端未连接到终端
则客户端会尝试调用on_input_img_verifycode来获取验证码
你可以在该回调函数中将验证码图片通过邮件发送到手机端
手机端通过特殊的链接将验证码最终提交回webqq
$client->on_input_img_verifycode() = sub{
#$img_verifycode_file是本地验证码图片路径
my $img_verifycode_file = shift;
#通过你自己的方式获取到图片的验证码是xxxx;
#比如把验证码通过邮件附件发送到手机，然后生成一个提交验证码的页面
#手机端查看邮件附件中的验证码，再通过页面把验证码最终提交给服务器
...;
return "xxxx"
};
#实际上已经有写好的一个插件Webqq::Client::Plugin::PostImgVerifycode
$client->load("PostImgVerifycode");
$client->on_input_img_verifycode() = sub{
my ($img_verifycode_file) = @_;
my $smtp = {
smtp =>'smtp.163.com',
user =>'sjdyd521@163.com',
pass =>'xxxx',
from =>'sjdyd521@163.com',
to =>'sjdy521@163.com',
from_title => 'QQ机器人',
subject => '验证码',
};
return &{$client->plugin("PostImgVerifycode")}($client,$img_verifycode_file,$smtp);
};
=item on_new_friend() :lvalue
设置新增好友时的回调
$client->on_new_friend = sub{
my $friend = shift;
#$friend结构和$client->{qq_database}{user}一致
};
注意，smartqq做了很多限制，新增好友时客户端不一定能够获取到新增好友的信息
往往只能知道该好友的uin，这种情况下客户端返回的$friend可能是这样的一种结构：
{
uin => xxxx,
categories => "陌生人",
nick => undef,
};
=item on_new_group() :lvalue
设置新增群时的回调
$client->on_new_group = sub{
my $group = shift;
#$group结构和@{$client->{qq_database}{group}}中的元素一致
};
注意，smartqq有限制，新增群的时候客户端不一定能够获取到新群的信息
=item on_new_group_member() :lvalue
设置已有群中有新成员加入时的回调
注意，腾讯的webqq功能受限，已存在的群新增加群成员时，不一定能够获取到新成员的信息
webqq还能够显示发送的消息，只是昵称变为发送者的uin
smartqq则完全不会显示新成员发送的消息
不明白为什么会这样子，这算腾讯很二的地方么。。
客户端会努力尝试获取，但实在获取不到只能返回一个默认的结构：
$default_member = {
nick => undef,
province=> undef,
gender => undef,
uin => $member_uin,
country => undef,
city => undef,
card => undef,
};
只能知道发送者的uin，其他的全部都是undef，因此，在进行回调处理时，你需要考虑到这种情况
当客户端重新再次登陆时，会再次获取整个群成员信息，这时候便可以全部成员信息都获取到
新增好友也有上述类似的情况
$client->on_new_group_member = sub{
my($group,$member) =@_;
#$group和@{$client->{qq_database}{group}}中元素一致
#member和@{$client->{qq_database}{group}}中元素的->{minfo}元素一致
my $member_nick = defined $member->{nick}?$member->{nick}:"昵称未知";
};
=item on_loss_group_member() :lvalue
客户端会定期更新群成员信息，当发现有群成员推出时，会执行该回调
传递给该回调的参数分别是 群数据结构 和 离开的群成员 数据结构
$client->on_loss_group_member() = sub{
my($group,$loss_member) = @_;
};
=item on_new_discuss() :lvalue
和on_new_group类似，这里不做展开
=item on_new_discuss_member() :lvalue
和on_new_group_member类似，这里不做展开
=item on_loss_discuss_member() :lvalue
和on_loss_group_member类似，这里不做展开
=item on_friend_change_state() :lvalue
好友状态变更时会执行该回调函数，传入状态变更的好友信息
use Webqq::Client::Util qw(console);
$client->on_friend_change_state = sub{
my $who = shift;
my %s = qw(
online 上线
offline 离线(或隐身)
away 离开
slient 请勿打扰
busy 忙碌
callme Q我吧
);
console "好友 \@$who->{nick} 状态变更为：[$s{$who->{state}}]\n";
};
=item login(qq=>$qq,pwd=>$pwd,[state=>$state,security=>1])
客户端登录，登录成功后才能够正常收发消息，登录失败该函数会die，登录成功返回true
$client->login(qq=>xxxx, pwd=> xxxx, state=>"online"); #pwd是经过md5加密后的，默认使用online状态登录
请注意，登录过程涉及的密码加密算法比较复杂，smartqq采用的是md5+rsa+tea+base64组合的方式
客户端默认会尝试采用L<JE>模块按照原始的javascript代码进行计算，速度非常慢
你可以尝试安装L<Crypt::RSA> (或者L<Crypt::OpenSSL::RSA> 和 L<Crypt::OpenSSL::Bignum>)
能够极大的提升RSA加密的计算速度
=item relogin()
客户端长期运行一段时间，会收到kick的消息要求强制下线
默认情况下客户端会自动调用relogin()
尝试重新登录，你也可以根据需要主动进行relogin
注意relogin过程中可能会需要重新输入验证码
$client->relogin()
=item get_qq_from_uin($uin)
webqq中每个qq用户在每一次客户端登录后使用的是一个唯一的uin（一串数字）进行身份标识
同一个用户在多次登录中uin可能不一样，但qq号码是永远不变的
通常情况下发送、接收消息使用uin即可
当你需要获取原始的qq号时，可以使用该函数
my $qq = $client->get_qq_from_uin($uin);
$uin通常是包含在接收到的消息或者客户端自己的数据库中，可以参考客户端数据结构介绍部分
=item change_state($state)
客户端设置登录状态，支持的状态包括 online|away|busy|silent|hidden|offline
$client->change_state("online");
=item send_message($msg)
=item send_message(to_uin=>$uin, content=>$content)
发送好友信息，如果传递给send_message的参数只有一个$msg
它必须是一个由$client->create_msg()生成的消息结构
my $msg=$client->create_msg(to_uin=>$uin, content=>$content);
$client->send_message($msg);
或者你可以按如下方式直接调用send_message()
$client->send_message(to_uin=>$uin, content=>$content);
如果发送失败默认会尝试重新发送，最多尝试5次
参见$client->create_msg()
=item send_sess_message($msg)
=item send_sess_message(to_uin=>$uin,group_code=>$gcode,content=>$content)
发送临时消息，send_sess_message的参数只有一个$msg
它必须是由$client->create_sess_msg()生成的消息结构
my $msg=$client->create_sess_msg(to_uin=>$uin, group_code=>$gcode,content=>$content);
$client->send_sess_message($msg);
或者你可以按如下方式直接调用send_sess_message()
$client->send_sess_message(to_uin=>$uin, group_code=>$gcode,content=>$content);
如果发送失败默认会尝试重新发送，最多尝试5次
参见$client->create_sess_msg()
=item send_group_message($msg)
=item send_group_message(to_uin=>$uin,content=>$content)
发送群消息，send_group_message的参数如果只有一个$msg
它必须是由$client->create_group_msg()生成的消息结构
my $msg=$client->create_group_msg(to_uin=>$uin, content=>$content);
$client->send_group_message($msg);
或者你可以按如下方式直接调用send_group_message()
$client->send_group_message(to_uin=>$uin, content=>$content);
如果发送失败默认会尝试重新发送，最多尝试5次
参见$client->create_group_msg()
=item send_discuss_message($msg)
=item send_discuss_message(to_uin=>$uin,content=>$content)
和send_group_message极为相似，这里不做展开，但需要注意，目前由于腾讯的现在，讨论组消息无法发送成功
=item reply_message($msg,$content)
当你使用send_message() send_sess_message() send_group_message()时不可避免你需要自己构造
一个消息结构，需要设置消息结构中的目标uin和其他一些关键信息，这种形式适合主动发送消息
但大部分时候，我们都是倾向于收到消息后针对此收到的消息进行回复，这种情况下可以考虑使用
reply_message(),该方法接收两个参数，第一个参数是接收到的消息，第二个参数是回复的内容,比如：
$client->on_receive_message = sub{
my $msg = shift;
$client->reply_message($msg,"hello world");
};
$client->run();
这种方式更为便捷，不需要关心消息的类型，reply_message()支持回复好友消息，临时消息和群消息
如果回复失败默认会尝试重新发送，最多尝试5次
=item create_sess_msg(to_uin=>$uin, group_code => $gcode, content=> $content, cb=>sub{...;})
创建一个群临时消息，需要至少设置
to_uin #接收者的uin
group_code #接收者所在的群的gcode
content #发送内容，UTF8编码
返回一个消息结构的hash引用:
my $sess_msg = $client->create_sess_msg(to_uin=>$uin, content=> $content,);
=item create_group_msg(to_uin=>$uin, content=> $content,cb=>sub{...;})
创建一个群消息，需要设置的参数
to_uin #目标群的uin，和数据结构中提到的gid、接收消息中的from_uin呼应
content #发送的内容,UTF8编码
my $group_msg = $client->create_group_msg(to_uin=>$uin, content=> $content,);
=item create_msg()
创建一个好友消息，需要设置的参数
to_uin #目标群的uin，和接收消息中的from_uin呼应
content #发送的内容,UTF8编码
my $msg = $client->create_msg(to_uin=>$uin, content=> $content,);
=item create_discuss_msg()
创建一个讨论组消息，需要设置的参数
to_uin #目标讨论组的uin，和接收消息中的from_uin呼应
content #发送的内容,UTF8编码
=item welcome()
登录成功后，获取个人信息，打印一些欢迎信息
$client->welcome()
=item logout()
注销登陆，webqq一般不需要注销，要退出直接关闭终止客户端即可
$client->logout()
=item stop()
如果只运行了一个帐号，调用stop()等效于调用exit()，会导致整个进程退出
如果同时运行多个帐号，调用stop()只会终止当前帐号的运行，不会影响其他帐号
=item exit()
适合单帐号运行的情况下使用，调用改方法会导致进程退出
=item run()
=item Webqq::Client::RUN()
客户端运行的流程是
1、登录
2、设置相关的回调函数
3、进入事件循环
因此run()往往是放在代码最后执行，且不可缺少
$client = Webqq::Client->new;
$client->login();
$client->on_xxx = sub{...};
$client->run()
$client->run() 和 Webqq::Client::RUN() 的区别在于:
run()是自身启动了一个事件循环，适合只运行单一帐号的情况
当需要在一个进程中同时运行多个帐号时，可以采用
$client1 = Webqq::Client->new;
$client2 = Webqq::Client->new;
$client1->login(...);
$client2->login(...);
$client1->on_xxx = sub {...};
$client2->on_xxx = sub {...};
$client1->ready();
$client2->ready();
Webqq::Client::RUN();
=item search_cookie($cookie_name)
查找指定cookie对应的值，客户端会自动维护所有的cookie信息，该方法基本用不到
my $cookie_val = $client->search_cookie($cookie_name);
=item search_friend($uin)
根据提供的uin在@{ $client->{qq_database}{friends} }中查找匹配的结果，
返回@{ $client->{qq_database}{friends} }中某一个匹配的元素，失败返回undef
my $friend_hash_ref = $client->search_friend($uin);
$friend_hash_ref =
{
flag => #作用未知
uin => #发送接收消息唯一uin
categories => #好友所属分组
nick => #好有昵称
face => #作用未知
markname => #好友备注
is_vip => #是否是vip
vip_level => #vip等级
}
=item search_member_in_group($gcode,$member_uin)
根据提供的gcode和uin在指定的群里搜索指定的成员，返回匹配的群成员引用，查询失败返回undef
my $member_hash_ref = $client->search_member_in_group($gcode,$member_uin);
$member_hash_ref =
{
nick => #该成员昵称
province => #该成员省份
gender => #该成员性别
uin => #该成员uin
country => #该成员国家
city => #该成员城市
},
注意当你接收到一个群消息时，search_member_in_group里的 $member_uin
不是指$msg->{from_uin} 而是指 $msg->{send_uin}
所以你应该这样搜索群成员
$client->search_member_in_group($msg->{group_code},$msg->{send_uin});
=item search_stranger($uin)
收到临时消息时，可以消息包含的uin查找对应的陌生人信息，查询失败返回undef
my $stranger_hash_ref = $client->search_stranger($uin);
$stranger_hash_ref =
{
uin => #uin
nick => #昵称
}
=item search_group($gcode)
根据设置的gcode在@{ $client->{qq_database}{group} }中查找对应的群信息，查询失败返回undef
my $group_hash_ref = $client->search_group($gcode);
$group_hash_ref =
{
face => #作用未知
memo => #群介绍
class => #群类别
fingermemo => #
code => #群的gcode，和$client->{qq_database}{group_list}一致
createtime => #群创建时间
flag => #
level => #群等级
name => #群名称
gid => #群gid ，和$client->{qq_database}{group_list}一致
owner =>
}
=item search_discuss()
和search_group()极为相似这里不做展开
=item search_member_in_discuss()
和search_member_in_group()极为相似这里不做展开
=item update_user_info()
更新$client->{qq_database}{user}，如果为空则初始化
客户端登陆后会调用一次该方法，原则上你不需要在使用过程中再次调用该方法
=item update_friends_info([$friend])
更新$client->{qq_database}{friends} ，如果参数为空，则初始化
如果参数不为空，则必须是一个有效的好友hash结构的引用，客户端登录完成后会调用一次该方法
原则上你不需要直接调用该方法，如果需要搜索好友信息，请通过$clent->search_friend()进行操作
$clent->search_friend()会根据查询的情况自动调用update_friends_info()来更新客户端数据库
=item update_group_info([$group])
更新$client->{qq_database}{group} 如果参数为空则初始化
如果参数不为空，则必须是一个有效的群hash结构的引用，客户端登录完成后会调用一次该方法
原则上你不需要直接调用该方法，如果需要搜索好友信息，请通过$clent->search_group()进行操作
$clent->search_group()/$clent->search_member_in_group()会自动调用update_group_info()来更新客户端数据库
=item update_group_list_info([$group])
更新$client->{qq_database}{group_list} 如果参数为空则初始化
原则上你不需要直接调用该方法，客户端会自己管理
=item update_discuss_list([$discuss])
=item update_discuss_info([$discuss])
=item add_job($type,$time,$callback)
客户端添加定时任务，参数：
$type #任意字符串
$time #时间HH:MM::SS
$callback #达到指定时刻后执行的动作
$client->add_job("定时任务","11:12",sub{...;});
该方法继承自Webqq::Client::Cron更多说明参见下方的Webqq::Client::Cron
=item get_group_code_from_gid($gid)
通过gid查找gcode
my $gcode = $client->get_group_code_from_gid($gid);
=item get_dwz($url)
使用百度短地址api生成url对应的短地址，由于是在线生成，如果超时返回undef
my $url = "http://www.baidu.com";
my $dwz = $client->get_dwz($url);
$dwz = $url unless defined $dwz;
=item get_single_long_nick($uin)
通过uin查找个性签名
my $single_long_nick = $client->get_single_long_nick($uin);
返回utf-8编码的个性签名
=item load($module1,$module2...)
该方法继承自Webqq::Client::Plugin
客户端提供了一个简单的插件管理框架
该方法用于查找并加载一个插件，
$client->load("ShowMsg");
会自动查找Webqq::Client::Plugin::ShowMsg模块，并提取模块中的call函数
更多说明参加下方的Webqq::Client::Plugin
=item call($module,$param1,$param2...)
=item call([$module1,$module2,...],$param1,$param2...)
该方法继承自Webqq::Client::Plugin，运行一个或多个插件
=item plugin($module)
该方法继承自Webqq::Client::Plugin，返回一个已经加载的模块的call函数引用
$client->load("ShowMsg");
my $code_ref = $client->plugin("ShowMsg");
#执行对应的函数，获取函数的返回值
my $return = &{$code_ref}(...);
一般情况下，你可以使用$client->call()来执行插件，但call不会关心插件的返回值
当你需要获取插件的返回值，则需要通过$client->plugin()获取到插件函数引用，然后自己执行
=back
=head1 PRIVATE CLASS METHOD
=over
=item _prepare_for_login()
=item _check_verify_code()
=item _get_img_verify_code()
=item _check_sig()
=item _login1()
=item _login2()
=item _relink()
=item _get_user_info()
=item _get_group_info()
=item _get_group_list_info()
=item _get_friend_info()
=item _get_user_friends()
=item _get_discuss_list_info()
=item _send_message()
=item _send_group_message()
=item _get_msg_tip()
=item _get_vfwebqq()
=item _report()
=item _get_offpic()
=item _cookie_proxy()
=back
=head1 OTHER MODULE
=over
=item Webqq::UserAgent
一个http异步请求客户端，原本使用AnyEvent::UserAgent
但由于AnyEvent::UserAgent依赖的模块比较多
故将AnyEvent::UserAgent的代码移植到Webqq，减少依赖模块，便于安装
=item Webqq::Client::Cache
一个简单的缓存模块，可以缓存任何内容，支持设置过期时间
$cache = Webqq::Client::Cache->new;
$cache->store('key',{a=>1,b=2,c=>[1,2,3]},30);
$cache->retrieve('key');#得到{a=>1,b=2,c=>[1,2,3]}
sleep 30;
$cache->retrieve('key');#缓存已过期，得到undef
=item Webqq::Client::Util
此模块导出4个函数
console("UTF-8的内容") #打印内容到STDOUT，会自动检测终端编码,以防止乱码
console_stderr("UTF-8的内容") #打印内容到STDERR，会自动检测终端编码，以防止乱码
hash() #webqq密码生成函数，无视
truncate($msg_content,max_bytes=>200,max_lines=>3) #截断消息，防止消息太长
=item Webqq::Client::Cron
客户端定时执行任务模块，已被Webqq::Client继承，提供参见$client->add_job()
=item Webqq::Client::Plugin
一个简单的客户端插件管理模块，被Webqq::Client继承，含几个方法：
1、$client->new()
2、$client->load()
#加载插件，例如$client->load("Test");则会查找Webqq::Client::Plugin::Test模块
#并加载模块中的call()函数，因此你开发插件模块应该遵循这样的包命名规则，并且
#模块中定义了call方法，例如：
package Webqq::Client::Plugin::Test;
sub call{
#$client将是在执行时传入的第一个参数
my $client = shift;
}
#如果你的模块不是遵循Webqq::Client::Plugin::前缀，你可以在load的模块名前面添加一个+号
#例如：
$client->load("+MyPakcag::Test");
#则会在@INC里搜索MyPakcag::Test模块
3、$client->call()
#执行指定插件的call函数，例如：
$client->load("Test");
$client->call("Test","a","b","c");
#相当于执行Webqq::Client::Plugin::Test::call($client,"a","b","c");
#如果有多个插件要执行，可以使用数组引用的形式
$client->call(["Test1","Test2","Test3"],"a","b","c");
#会顺序执行每一个插件的call函数
4、$client->call_all()
#按load的顺序依次执行每个插件
$client->load("Test1","Test2","Test3");
$client->call_all("a","b","c");
#相当于依次执行如下插件
Webqq::Client::Plugin::Test1::call($client,"a","b","c");
Webqq::Client::Plugin::Test2::call($client,"a","b","c");
Webqq::Client::Plugin::Test3::call($client,"a","b","c");
5、$client->plugin()
#返回插件对应的call函数引用
package Webqq::Client::Plugin::Test;
sub call{
#$client将是在执行时传入的第一个参数
my $client = shift;
}
1;
$client->load("Test");
my $plugin_code_ref = $client->plugin("Test");
$plugin_code_ref是Webqq::Client::Plugin::Test::call()的引用
6、$client->clear()
卸载客户端所有插件
=item Webqq::Client::Plugin::ShowMsg
打印接收或者发送消息的插件，插件调用时需要传入接收或者发送的$msg
$client->load("ShowMsg");
$client->on_receive_message = sub{
my $msg = shift;
$client->call("ShowMsg",$msg);
};
$client->on_send_message =sub {
my $msg = shift;
my $is_success = shift;
my $status = shift;
$client->call("ShowMsg",$msg,"[$status]");
};
$client->run();
=item Webqq::Client::Plugin::Openqq
如果并不熟悉Perl语言，你可能更希望提供api接口的方式给外部调用
该插件运行时会产生一个监听本地指定端口的HTTP服务器，用于接收api请求
返回数据完全为JSON格式，接口包括：
获取个人信息 /openqq/get_user_info
获取好友信息 /openqq/get_friend_info
获取群信息 /openqq/get_group_info
获取讨论组信息 /openqq/get_discuss_info
获取最近联系人列表 /openqq/get_recent_info
发送好友消息 /openqq/send_message?uin=xxx&content=xxx
发送群消息 /openqq/send_group_message?gid=xxx&content=xxx
发送讨论组消息 /openqq/send_discuss_message?did=xxx&content=xxx(由于腾讯限制，该功能暂时无法发送成功)
发送群临时消息 /openqq/send_sess_message?gid=xxx&uin=xxx&content=xxx
发送讨论组临时消息 /openqq/send_sess_message?did=xxx&uin=xxx&content=xxx
若系统安装了Webqq::Qun模块，则支持使用QQ号码和群号码来指定发送消息的对象，number表示群号码，qq表示群成员或好友qq号
发送好友消息 /openqq/send_message?qq=xxx&content=xxx
发送群消息 /openqq/send_group_message?number=xxx&content=xxx
发送群临时消息 /openqq/send_sess_message?number=xxx&qq=xxx&content=xxx
插件使用代码示例
$client->load("Openqq");
$client->on_run = sub{
$client->call("Openqq",host=>"127.0.0.0",port=>5000);
};
$client->run();
api调用示例
http://127.0.0.1:5000/openqq/get_user_info
=item Webqq::Client::Plugin::SendMsgControl
=item Webqq::Client::Plugin::PicLimit
=item Webqq::Client::Plugin::SmartReply
=item Webqq::Client::Plugin::Perlcode
=item Webqq::Client::Plugin::Perldoc
=item Webqq::Client::Plugin::ShowMsg
=item Webqq::Client::Plugin::Msgstat
=item Webqq::Client::Plugin::SendMsgFromMsg
=item Webqq::Client::Plugin::SendMsgFromSocket
=back
=head1 SEE ALSO
L<https://github.com/sjdy521/Webqq-Client>
L<https://git.oschina.net/sjdy521/Webqq-Client>
L<Webqq::Qun>
L<Mojo::Webqq>
=head1 AUTHOR
sjdy521, E<lt>sjdy521@163.comE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2014 by Perfi
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.
=cut