jabber-querybot (1p)

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

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.

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

/etc/jabber-querybot/Querymodule.pm

/usr/bin/jabber-querybot

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

\fIInMessage()\fP

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.

\fIconnect_server()\fP

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.

\fIStop()\fP

Shutdown jabber connection and exit main program

\fIdisconnect_server()\fP

Only disconnect from the jabber-server.

\fIreconnect_server()\fP

Reconnect and create a log entry.

\fIInIQ()\fP

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

\fIInPresence()\fP

• 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

\fIsendPresence()\fP

Send presence information to user

\fIsystemcommands()\fP

• 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 \*(L"not allowed\*(R"

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

• '!query off` turn off queries

• '!query on` turn on queries

\fIget_barejid()\fP

Remove resource id from a jabber id.

\fIcalcualte_stats()\fP

Calculate message statistics

\fIjabber_set_presence()\fP

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

\fIjabber_send_message()\fP

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

\fIset_wakeup_mode()\fP

Set jabber presence via jabber_set_presence()

\fIpenalty_handler()\fP

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.

\fIjabber_add_footer()\fP

Add footer to the processed message.

\fIcalcualte_elapsed_time()\fP

Calculate elapsed worktime for a query

\fIsendError()\fP

sendError($message, $from, $to, 404, \*(L"text\*(R");

\fIsystem_load_check()\fP

• Calculate system load

• If load is too high shutdown bot.

• If load is ok, starting up bot

\fIconnect_bot()\fP

Connect bot and initialize all timers.

\fIcheck_before_start()\fP

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

Copyright (C) 2009-2012 Marco Balmer <[email protected]>

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