view release on metacpan or  search on metacpan

lib/Mojo/Webqq.pod  view on Meta::CPAN

        #你也可以使用$msg->dump() 来打印消息结构
    });

    #ready事件触发时 表示客户端一切准备就绪：已经成功登录、已经加载完个人/好友/群信息等
    #你的代码建议尽量写在 ready 事件中
    $client->on(ready=>sub{
        my $client = shift;

        #你的代码写在此处 

    });

    #客户端开始运行
    $client->run();

    #run相当于执行一个死循环，不会跳出循环之外
    #所以run应该总是放在代码最后执行，并且不要在run之后再添加任何自己的代码了

=head1 DESCRIPTION

通过该项目，你可以完成基本的登录、接收和发送消息，在此基础上你可以通过插件的形式实现更多附加功能，比如：

群管理、聊天记录统计、QQ消息报警、QQ机器人、在QQ群中执行Perl代码，查询Perldoc文档、消息转发、QQ和IRC联通等等

原先的L<Webqq::Client>模块采用的是LWP+AnyEvent实现阻塞和非阻塞请求

代码比较混乱，存在诸多bug，易用性和可扩展性较差

此项目是L<Webqq::Client>模块的重构，基于L<Mojolicious>框架，具体更多良好特性，比如：

基于L<Mojo::Base>更好的对象模型、基于L<Mojo::EventEmitter>灵活的事件管理机制、

基于L<Mojo::UserAgent>统一的阻塞和非阻塞HTTP请求、基于L<Mojo::Log>轻量级的日志记录框架 等等

推荐你在使用本模块的同时也更多的了解L<Mojolicious>

=head1 数据类型

数据类型包含 个人、好友、群组、讨论组 几大类型，每种类型都专门设计了类

这些类都继承L<Mojo::Webqq::Model::Base>具有dump的方法，这些数据类型均由系统自动创建和维护

一般情况下，你只需要对对象进行只读操作

=head2 Mojo::Webqq::User 个人

    属性:

    id              #本次登录唯一标识，发送消息时需要用到，id和qq号是两个不同的概念
    uid             #qq帐号
    name            #昵称    
    type            #固定值"user"

    phone           #电话
    birthday        #生日
    occupation      #职业
    college         #大学
    blood           #血型
    constel         #星座
    homepage        #主页
    state           #在线状态 online|away|busy|callme|silent|hidden
    country         #国家
    city            #城市
    displayname     #当前和昵称完全一样
    shengxiao       #生效
    email           #邮箱
    client_type     #固定值"web"
    province        #省份
    sex             #性别
    mobile          #手机
    signature       #个性签名

    方法：
    dump
    is_me           #判断对象是否是自己
    
实际想要获取该对象信息时，是通过客户端提供的 user 属性来获取
    
    $client->user       #返回的是一个Mojo::Webqq::User对象
    $client->user->name #获取帐号昵称
    $client->user->id   #获取帐号id
    $client->user->dump

=head2 Mojo::Webqq::Friend 好友

    属性：

    id              #好友的id，仅在本次登录期间唯一，多次登录可能会发生变化，记住 id不是qq号
    uid             #好友的qq号码
    type            #固定值"friend"
    category        #好友所属的分组
    name            #好友昵称
    markname        #好友备注名称
    displayname     #如果设置了markname 就返回markname 否则返回nick

    is_vip          #是否是vip会员
    vip_level       #vip等级
    state           #好友状况 online|away|busy|silent|offline
    client_type     #好友客户端类型 pc|mobile|iphone|unknown

    方法:
    send            #给好友对象发送消息
    is_friend       #判断对象是否是好友
    dump

    代码示例：

    my $friend = $client->search_friend(name=>xxx);
    $client->print("好友分组为: ",$friend->category,"\n"); #使用$client->print()可以自动检测终端编码，防止乱码
    $friend->dump();

    $friend->send("hello world"); #比$client->send_friend_message($friend,"hello world")更简洁

    #遍历好友
    $client->each_friend(sub{
        my($client,$friend) = @_;
        ...;
    });
    
    for my $friend ($client->friends){
        ...;
    }
    

=head2 Mojo::Webqq::Group 群组

    属性：

    id              #群的id，仅在本次登录期间唯一，多次登录可能会发生变化
    type            #固定值"group"
    uid             #群号码
    name            #群名称
    memo            #群说明
    role            #create|attend|manage 分别表示创建的群|加入的群|管理的群
    owner_id        #群拥有者的id
    owner_uid       #群拥有者的qq
    markname        #群备注名称
    displayname     #如果设置了gmarkname 就返回gmarkname 否则返回gname
    createtime      #群创建时间
    level           #群等级
    member          #群成员，此属性是一个数组引用，数组中每个元素是一个Mojo::Webqq::Group::Member的对象
    max_member      #最大群成员数量
    max_admin       #最大管理员数量

    方法：
    search_group_member     #根据群成员属性搜索，标量上下文返回第一个群成员对象，列表上下文返回全部，搜索失败返回undef
    each_group_member       #在群中遍历所有的群成员
    invite_friend           #邀请好友入群
    kick_group_member       #踢出群成员
    set_group_admin         #设置群成员为管理员
    remove_group_admin      #取消群成员的管理员身份
    set_group_member_card   #设置群名片
    shutup_group_member     #对群成员进行禁言
    speakup_group_member    #取消群成员禁言
    members                 #返回群成员对象列表  
    member_count            #返回当前群成员数量
    send                    #给群对象发送消息
    me                      #返回自己在群成员中的对象 (Mojo::Webqq::Group::Member)

lib/Mojo/Webqq.pod  view on Meta::CPAN

    msg             #发送消息状态中文描述：发送成功|发送失败
    info            #发送消息更多错误描述信息

    方法：
    dump            #打印消息结构，主要用于调试
    to_json_hash    #将消息转换为json兼容的hash，方便和外部系统交互
                    #常见的接收和发送消息都支持该方法，下文不再赘述
    is_at           #消息是否艾特某人，常见的接收和发送消息都支持该方法，下文不再赘述
    faces           #返回消息中的表情内容
    images          #获取到消息中图片内容后执行指定回调，适合对具体某个消息进行图片处理
                    #参考 receive_pic 事件，可以设置全局接收图片的处理回调
    reply           #对消息进行回复
                    #如果class为recv，相当于发送内容给消息发送者，如果class为send，相当于发送内容给消息的接收者

    is_success      #判断发送消息是否成功

    示例代码:
    $msg->sender->displayname; #从消息中 获取发送者的名称

    my $json_hash = $msg->to_json_hash();    #获取到hash引用
    my $json_text = $client->to_json($json_hash); #将hash转换为json字符串

    $msg->dump();
    $msg->reply("hello world"); #比$client->reply_message($msg,"hello world")更简洁

    $msg->is_at();          #判断发送或接收的消息中是否有艾特自己
    $msg->is_at($member);   #判断发送或接收的消息中是否有艾特某个成员
    $msg->is_at($friend);   #判断发送或接收的消息中是否有艾特某个好友

    my @faces = $msg->faces(); #("[微笑]","[流泪]","[害羞]")
    
    $msg->images(sub{
        my($client,$image_path,$sender) = @_;
    });

    #全局图片处理事件
    $client->on(receive_pic=>sub{
        my($client,$image_path,$sender) = @_;
    });
    
    text            #纯文本消息内容，不包含表情图片等
    raw_content     #消息原始内容 一个数组引用

=head1 客户端属性

    $client->security   #是否开启安全加密
    $client->mode       #登录状态
    $client->type       #类型 固定值 smartqq，Mojo::Webqq只支持smartqq
    $client->htto_debug #http请求是否打印debug信息
    $client->log_level  #日志记录等级 默认info
    $client->log_path   #日志记录路径，默认undef，打印到STDOUT
    $client->version    #客户端版本
    $client->account    #登录帐号，不必是真实的qq号码，可以自由定义，根据扫码确定实际登陆qq

=head1 客户端方法

=head2 new()

    account           #登录帐号，默认default,不必是真实qq号码，可自由定义，根据扫码确定实际登陆qq
    security          #设置该参数，将使得发送和接收消息使用https加密
    mode              #设置登录状态，默认是online，支持online|away|busy|silent|hidden|offline|callme
    http_debug        #设置该参数，打印调试信息
    keep_cookie       #默认为1，0表示不保存登录cookie，1表示保存登录cookie方便下次直接恢复登录
    disable_color     #默认为0，是否禁用终端彩色打印
    send_interval     #默认为3s，全局发送消息时间间隔，间隔太小会导致消息发送频繁，可能有被封号的风险
    ignore_send_retcode #对发送消息返回这些状态码不认为发送失败不重试,参数是一个数组引用
                        #设置示例 Mojo::Webqq->new(ignore_send_retcode=>[1202,100100]);
                        #默认值 [1202,100100] 不清楚作用请不要随意设置

    ignore_poll_retcode #对接收消息返回这些状态码不认为接收失败，不重新登录，避免频繁掉线
                        #设置示例 Mojo::Webqq->new(ignore_poll_retcode=>[102,109,110,1202,100012]);
                        #默认值 [102,109,110,1202,100012] 不清楚作用请不要随意设置

    ignore_unknown_id #其他设备上自己发送的消息，在webqq上会以接受消息的形式再次接收到
                      #消息发送者是一个未知的id，非常影响很多功能的正常工作，该选项决定是否忽略掉这种消息
                      #默认值为 1
    allow_message_sync #是否允许同步来自其他设备登录账号发送的消息 默认为0
                       #由于webqq自身发送消息后也会收到服务端重复的消息
                       #且没办法和来自其他设备的消息区分，会导致出现一些不期望的结果，比如某些插件会陷入死循环等
                       #因此默认不开启消息同步，如果你只是用来irc聊天，则可以考虑开启此选项
                       #可以同步来自其他设备的消息，体验会更好一些

    log_console     #打印到文件的同时也打印到屏幕，方便调试，默认 1
    log_level       #默认级别为info，可以设置debug|info|warn|error|fatal
    log_path        #默认客户端输出内容打印到STDOUT 设置该参数可以将客户端输出重定向到文件
    log_encoding    #输出日志的编码，默认自动检测，如果出现乱码可以尝试手动设置一下输出编码
                    #编码必须是 Encode 模块支持的格式，比如utf8 gbk等

    tmpdir          #程序使用的临时目录，主要用于保存一些验证码、二维码等数据，默认为系统临时目录
    pic_dir         #图片接收默认地址，默认为 tmpdir 参数所设置的目录

    verifycode_path #图片验证码保存路径，默认是 tmpdir 目录下固定文件名
    qrcode_path     #二维码保存路径，默认是 tmpdir 目录下固定文件名
    cookie_path     #登录cookie接收保存地址，默认为 tmpdir 参数所设置的目录下固定文件名

    #程序会根据实际需要自动按需加载好友、群、讨论组信息，首次登录加载这些信息是不必须的
    #如果你的群组数量非常惊人，首次加载会严重影响运行速度，这种情况下建议选择性的取消某些默认加载行为

    is_init_friend      #是否在首次登录时初始化好友信息，默认值 1，据测试设置为0可能影响登录
    is_init_group       #是否在首次登录时初始化群组信息，默认值 1
    is_init_discuss     #是否在首次登录时初始化讨论组信息，默认值 1

    #程序会定期更新个人、好友、群、讨论组信息，目的是为了可以感知新增的成员、失去的好友等
    #如果你完全不关注这些特性，可以关闭定期更新
    is_update_user      #是否定期更新个人信息，默认值 0
    is_update_group     #是否定期更新群组信息，默认值 1
    is_update_group_member #是否定期更新群成员信息，默认值 1
    is_update_group_member_ext  #是否定期更新群成员扩展信息，扩展信息包含QQ号，默认值0，即新增成员才会更新
    is_update_friend    #是否定期更新好友信息，默认值 1
    is_update_discuss   #是否定期更新讨论组信息，默认值 1
    update_interval     #定时更新群组、好友、讨论组等信息的时间间隔，默认600秒

    group_member_use_friend_markname #群成员使用好友备注名(如果是好友关系并且备注存在)

    is_fetch_notice     #是否获取公告信息，默认值 1

    msg_ttl             #发送失败的消息，重试次数，默认是5

    qrcode_count_max    #每个二维码都有一个过期时间，过期后会重新下载一个二维码继续等待扫描
                        #如果等待扫码次数超过 qrcode_count_max 客户端会停止运行，默认10次