Automated bot creation with safeties
Version 2.1.5
Program design: This is a Moose based Class.
The idea behind the module is that someone creating a bot should not really have to know a whole lot about how the Jabber protocol works in order to use it. It also allows us to abstract away all the things that can get a bot maker into trouble. Essentially the object helps protect the coders from their own mistakes.
All someone should have to know and define in the program away from the object is:
The object at present has the following enforced safeties as long as you do not override safety mode:
Minimal:
my $bot = Net::Jabber::Bot->new(
server => 'host.domain.com' # Name of server when sending messages internally.
, conference_server => 'conference.host.domain.com'
, port => 522
, username => 'username'
, password => 'pasword'
, safety_mode => 1
, message_function => \&new_bot_message
, background_function => \&background_checks
, forums_and_responses => \%forum_list
);
All options:
my $bot = Net::Jabber::Bot->new(
server => 'host.domain.com' # Name of server when sending messages internally.
, conference_server => 'conference.host.domain.com'
, server_host => 'talk.domain.com' # used to specify what jabber server to connect to on connect?
, tls => 0 # set to 1 for google
, connection_type => 'tcpip'
, port => 522
, username => 'username'
, password => 'pasword'
, alias => 'cpan_bot'
, message_function => \&new_bot_message
, background_function => \&background_checks
, loop_sleep_time => 15
, process_timeout => 5
, forums_and_responses => \%forum_list
, ignore_server_messages => 1
, ignore_self_messages => 1
, out_messages_per_second => 4
, max_message_size => 1000
, max_messages_per_hour => 100
);
Setup the object and connect to the server. Hash values are passed to new as a hash. The following initialization variables can be passed. Only marked variables are required (\s-1TODO\s0)
safety_mode = (1,0)
Determines if the bot safety features are turned on and enforced. This mode is on by default. Many of the safety features are here to assure you do not crash your favorite jabber server with floods, etc. \s-1DO\s0 \s-1NOT\s0 turn it off unless you're sure you know what you're doing (not just Sledge Hammer ceratin)
Jabber server name
Defaults to the same value set for 'server' above. This is where the bot initially connects. For google for instance, you should set this to 'gmail.com'
conferencee server (usually conference.$server_name)
Defaults to 5222
The user you authenticate with to access the server. Not full name, just the stuff to the left of the @...
password to get into the server
This will be your nickname in rooms, as well as the login resource (which can't have duplicates). I couldn't come up with any reason these should not be the same so hardcoded them to be the same.
A hash ref which lists the forum names to join as the keys and the values are an array reference to a list of strings they are supposed to be responsive to. The array is order sensitive and an empty string means it is going to respond to all messages in this forum. Make sure you list this last. The found 'response string' is assumed to be at the beginning of the message. The message_funtion function will be called with the modified string. alias = jbot:, attention: example1:
message: 'jbot: help'
passed to callback: 'help'
The subroutine the bot will call when a new message is recieved by the bot. Only called if the bot's logic decides it's something you need to know about.
The subroutine the bot will call when every so often (loop_sleep_time) to allow you to do background activities outside jabber stuff (check logs, web pages, etc.)
Frequency background function is called.
Time Process() will wait if no new activity is received from the server
Boolean value as to whether we should ignore messages sent to us from the jabber server (addresses can be a little cryptic and hard to process)
Boolean value as to whether we should ignore messages sent by us. \s-1BE\s0 \s-1CAREFUL\s0 if you turn this on!!! Turning this on risks potentially endless loops. If you're going to do this, please be sure safety is turned on at least initially.
Limits the number of messages per second. Number must be <gt> 0 default: 5 safety: 5
Specify maximimum size a message can be before it's split and sent in pieces. default: 1,000,000 safetey: 1,000
Limits the number of messages per hour before we refuse to send them default: 125 safetey: 166
Joins a jabber forum and sleeps safety time. Also prevents the object from responding to messages for a grace period in efforts to get it to not respond to historical messages. This has failed sometimes. \s-1NOTE:\s0 No error detection for join failure is present at the moment. (\s-1TODO\s0)
Mostly calls it's client connection's \*(L"Process\*(R" call. Also assures a timeout is enforced if not fed to the subroutine You really should not have to call this very often. You should mostly be calling Start() and just let the Bot kernel handle all this.
Primary subroutine save new called by the program. Does an endless loop of: 1. Process 2. If Process failed, Reconnect to server over larger and larger timeout 3. run background process fed from new, telling it who I am and how many loops we have been through. 4. Enforce a sleep to prevent server floods.
You should not ever need to use this. the Start() kernel usually figures this out and calls it. Internal process 1. Disconnects 3. Re-initializes
Disconnects from server if client object is defined. Assures the client object is deleted.
Reports connect state (true/false) based on the status of client_start_time.
Handles incoming messages.
$bot->get_ident($forum_name); Returns the array of messages we are monitoring for in supplied forum or replies with undef.
Called when the client receives new messages during Process of this type.
Called when the client receives new presence messages during Process. Mostly we are just pushing the data down into the client \s-1DB\s0 for later processing.
$bot->respond_to_self_messages($value = 1); Tells the bot to start reacting to it\'s own messages if non-zero is passed. Default is 1.
$bot->get_messages_this_hour(); replys with number of messages sent so far this hour.
Validates that we are in safety mode. Returns a bool as long as we are an object, otherwise returns undef
$bot->SendGroupMessage($name, $message); Tells the bot to send a message to the recipient room name
$bot->SendPersonalMessage($recipient, $message); How to send an individual message to someone. $recipient must read as user@server/Resource or it will not send.
$bot->SendJabberMessage($recipient, $message, $message_type, $subject); The master subroutine to send a message. Called either by the user, SendPersonalMessage, or SendGroupMessage. Sometimes there is call to call it directly when you do not feel like figuring you messaged you. Assures message size does not exceed a limit and chops it into pieces if need be. \s-1NOTE:\s0 non-printable characters (unicode included) will be stripped before sending to the server via:
s/[^[:print:]]+/./xmsg
$bot->SetForumSubject($recipient, $subject); Sets the subject of a forum
$bot->ChangeStatus($presence_mode, $status_string); Sets the Bot's presence status. $presence mode could be something like: (Chat, Available, Away, Ext. Away, Do Not Disturb). $status_string is an optional comment to go with your presence mode. It is not required.
$bot->GetRoster(); Returns a list of the people logged into the server. I suspect we really want to know who is in a paticular forum right? In which case we need another sub for this.
Need documentation from Yago on this sub.
Need documentation from Yago on this sub.
Need documentation from Yago on this sub.
Todd Rinaldo \*(C`<[email protected]) >\*(C'
Please report any bugs or feature requests to \*(C`[email protected]\*(C', or through the web interface at <http://code.google.com/p/perl-net-jabber-bot/issues/entry>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc Net::Jabber::Bot
You can also look for information at:
AnnoCPAN: Annotated \s-1CPAN\s0 documentation <http://annocpan.org/dist/Net-Jabber-Bot>
\s-1CPAN\s0 Ratings <http://cpanratings.perl.org/d/Net-Jabber-Bot>
Search \s-1CPAN\s0 <http://search.cpan.org/dist/Net-Jabber-Bot>
Project homepage <http://code.google.com/p/perl-net-jabber-bot/>
Google Issue Tracker (reporting bugs) <http://code.google.com/p/perl-net-jabber-bot/issues/entry>
Copyright 2007 Todd E Rinaldo, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.