jabber-querybot

JABBER-QUERYBOT(1p)   User Contributed Perl Documentation  JABBER-QUERYBOT(1p)



NAME
       jabber-querybot - a modular perl jabber bot

DESCRIPTION
       jabber-querybot connects a jabber account and wait for messages. If a
       message comes in, it forward it to your self programmend modul. The
       return string of your module, jabber-querybot send it back to the
       jabber sender.

       It is designed to be re-usable and to make it easy to write small
       Jabber bots that do one thing and do it well. A simple concept with a
       lot of examples and experiences are implemented.

       1. Create a jabber account on a jabber-server around

       2. Create a bot application:

        cd examples
        cp Querymodule.pm /etc/jabber-querybot/Mybot.pm
        cd /etc/jabber-querybot
        ln -s Mybot.pm Querymodule.pm

       Modify login parameters to your jabber-bot-account

       vim Mybot.pm

         our $hostname        = "swissjabber.ch";
         our $user            = "";
         our $password        = "";
         our $ident           = "Testbot";
         our $bot_admin       = "\@swissjabber.ch";
         our $port            = "5222";
         our $timeout         = "5";
         our $service_name    = "$user\@$hostname";
         our $bot_description = "Bot help title
         Bot description";

       For each jabber message, jabber-querybot will execute sub run_query,
       that you can write here your application.

       You can control how your jabber response will be:

       •   error = error message stanza

       •   presence = error as presence stanza

       •   ignore = ignore message

OPTIONS
       jabber-querybot has a lot of variables which you can easy modify for
       what you need:

   querystatus
       $querystatus = [ 0 | 1 ]

       •   0 = Bot will not proceed any incoming jabber messages.

       •   1 = Bot will proceed incoming messages.

   penalty_status
       If the bot has too much workload, it goes to penalty status and wait
       some time until his status change back to normal.

       $timer_reconnect_default = 21600

       Every 21600 seconds (6 hours) the bot will shutdown automatically, wait
       10 seconds and starting up again.

       $timer_auto_query = 0

       If you set in your module this variable to 60, the bot will every 60
       seconds call the function run_auto_query() which you may use for
       several things.

   System load
       If your systems load is >=6, this bot will shutdown the jabber
       connection and check every 10 seconds systems load. If load <=2, bot
       will start over.

EXAMPLES
       /usr/share/doc/jabber-querybot/examples/Testbot.pm

FILES
       /etc/jabber-querybot/Querymodule.pm

       /usr/bin/jabber-querybot

RESOURCES
       http://github.com/micressor/jabber-querybot/

METHODS
   InMessage()
       An incoming jabber message to the bot will hook this function.

       • Read parameters of incoming stanza


       • Decode utf8 string


       • increment timer overload and do not process message if bot is
         overloaded.


       • Ignore message if it is from myself


       • Be sure, that it is not a message from another transport


       • Check any systemcommands for the bot


       • If the bot has sleeping status, change it to work


       • We process only normal text or chat type jabber messages


       • And now we give the real text string which was incoming to the bot
         via run_query().

       • If run_query() say us 'ignore` we do a log entry and do not answer
         via jabber to the user.


       • If run_query() says 'error` we send a jabber error stanza wiht the
         status message from run_query() back to the user.


       • If there was no error, we update the statistic vars and send the
         answer from run_query() back to the jabber user.

   connect_server()
       This function connects to the jabber server with the given credentials
       from Querymodule.pm.


       Set the call back functions. This functions will be executed if a
       message of the types <message/> <iq/> or <presence/> are incoming.

   Stop()
       Shutdown jabber connection and exit main program

   disconnect_server()
       Only disconnect from the jabber-server.

   reconnect_server()
       Reconnect and create a log entry.

   InIQ()
       We do not proceed any iq (information query), this is only for
       statisic.

   InPresence()
       • Increment timer overload

       • Do not process message if we are overloaded penalty_handler().


       We have a problem in Net::Jabber. An incoming message with a ` in
       resource blocks the bot. We will hotfix that for the moment.


       A subscription type `subscribe` is incoming. Send `subscribed` tho the
       user and say hello ;)


       • Send presence to user


       • Remove subscription if a user remove this bot from his roster

   sendPresence()
       Send presence information to user

   systemcommands()
       • If user type '!help` send a help instruction to the user


       • Send statistic information to the user if he types '!status`


       • Is it a bot command?

       • Is the bot command from the bot admin? If not, send "not allowed"

       • '!shutdown` will shutdown your bot via jabber invoke.

       • '!query off` turn off queries

       • '!query on` turn on queries

   get_barejid()
       Remove resource id from a jabber id.

   calcualte_stats()
       Calculate message statistics

   jabber_set_presence()
       Set new presence if we have another presence status or we have set the
       force flag (for transport presence).

   jabber_send_message()
       This function send all jabber messages which are outgoing from the
       jabber-querybot.

   set_wakeup_mode()
       Set jabber presence via jabber_set_presence()

   penalty_handler()
       This function checks if the bot is overloaded with incoming mesages and
       reject if it is. Two times that's ok so 2:1 because while in main.


       Bot admin got everytime an answer.

   jabber_add_footer()
       Add footer to the processed message.

   calcualte_elapsed_time()
       Calculate elapsed worktime for a query

   sendError()
       sendError($message, $from, $to, 404, "text");

   system_load_check()
       • Calculate system load

       • If load is too high shutdown bot.

       • If load is ok, starting up bot

   connect_bot()
       Connect bot and initialize all timers.

   check_before_start()
       Check configuration variables in Querybotmodule.pm and give answer if
       anything does not match or is missing.

COPYRIGHT AND LICENSE
       Copyright (C) 2009-2012 Marco Balmer <marco@balmer.name>

       The Debian packaging is licensed under the GPL, see
       `/usr/share/common-licenses/GPL-3'.



perl v5.14.2                      2012-02-03               JABBER-QUERYBOT(1p)