/ 
Net-Jabber-Bot-1.1
River stage zero No dependents
/ Net::Jabber::Bot

NAME

Net::Jabber::Bot - Automated Bot creation with safeties

VERSION

Version 1.1

SYNOPSIS

Program design: This module is an inside out Perl Module Currently it's called Net::Jabber::Bot, but I'm thinking of also releasing Net::Jabber::SafeteyBot as a child since so many things are hard coded in the base object that probably shouldn't be.

The idea behind the module is that someone creating a bot shouldn't 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: 1. Config - Where to connect, how often to do things, timers, etc. 2. A function to be called by the bot object when a new message comes in. 3. A function to be called by the bot object every so often that let's the user do background activities (check logs, monitor web pages, etc.),

The object at present has the following enforced safeties 1. Jabber client object is not directly accessible because the bot is an inside out object, forcing the user to use the Net::Jabber::Bot's interface only 2. Limits messages per second, configurable at start up, (Max is 5 per second) by requiring a sleep timer in the message sending subroutine each time one is sent. 3. Endless loops of responding to self prevented by now allowing the bot message processing function to know about messages from self 4. Forum join grace period to prevent bot from reacting to historical messages 5. Configurable aliases the bot will respond to 6. Limits maximum message size, preventing messages that are too large from being sent (largest configurable message size limit is 1000). 7. Automatic chunking of messages to split up large messages in message sending subroutine 8. ADDED YESTERDAY: Limit on messages per hour. (max configurable limit of 125) Messages will alert in the log, but not ever be sent once the message limit is reached for that hour.

EXPORT

A list of functions that can be exported. You can delete this section if you don't export anything, such as for a purely object-oriented module.

FUNCTIONS

new

my $bot = Net::Jabber::Bot->new({ server => 'host.domain.com' , conference_server => 'conference.host.domain.com' , port => 522 , username => 'username' , password => 'pasword' , alias => 'cpan_bot' , message_callback => \&new_bot_message , background_activity => \&background_checks , loop_sleep_time => 15 , process_timeout => 5 , forums => \@forums_to_join , aliases_to_respond_to => \@responses , 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 ref (I think) uses Class::Std

The following initialization variables can be passed. Only marked variables are required (TODO)

safety_mode
safety_mode = (1,0,'on','off')

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. DO NOT turn it off unless you're sure you know what you're doing (not just Sledge Hammer ceratin)

server

Jabber server name

conference_server

conferencee server (usually conference.$server_name)

port

Defaults to 5222

username

The user you authenticate with to access the server. Not full name, just the stuff to the left of the @...

password

password to get into the server

alias

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 shouldn't be the same so hardcoded them to be the same.

forums

an array ref to a list of strings that the bot will join upon login.

message_callback

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.

background_activity

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.)

loop_sleep_time

Frequency background activity is called.

process_timeout

Time Process() will wait if no new activity is received from the server

ignore_server_messages

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)

ignore_self_messages

Boolean value as to whether we should ignore messages sent by us.

BE CAREFUL 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.

aliases_to_respond_to

An array ref listing the strings we look for at the front of the line to determine if we should react to the message and call the message_callback function. the alias addressed will be stripped out of the message before being passed to the callback function.

Strings are processed left to right so be careful of order.

example:

alias = mbot:, attention:

example1:

message: 'mbot: help'

passed to callback: 'help'

out_messages_per_second

Limits the number of messages per second. Number must be <gt> 0

default: 5

safety: 5

max_message_size

Specify maximimum size a message can be before it's split and sent in pieces.

default: 1,000,000

safetey: 1,000

max_messages_per_hour

Limits the number of messages per hour before we refuse to send them

default: 125

safetey: 166

START

Sets up the special message handling and then initializes the connection.

JoinForum - PUBLIC

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.

NOTE: No error detection for join failure is present at the moment. (TODO)

Process - PUBLIC

Mostly calls it's client connection's "Process" 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.

Start - PUBLIC

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\'ve been through. 4. Enforce a sleep to prevent server floods.

ReconnectToServer - PUBLIC

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

Disconnect - PUBLIC
Disconnects from server if client object is defined. Assures the client object is deleted.
ProcessJabberMessage - DO NOT CALL

Handles incoming messages ***NEED VERY GOOD DOCUMENTATION HERE***** (TODO)

get_alias - PUBLIC

Returns the alias name we are connected as or undef if we are not an object

InIQ - DO NOT CALL

Called when the client receives new messages during Process of this type.

JabberPresenceMessage - DO NOT CALL

Called when the client receives new presence messages during Process. Mostly we are just pushing the data down into the client DB for later processing.

respond_to_self_messages - PUBLIC
$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.

get_messages_this_hour - PUBLIC
$bot->get_messages_this_hour();

replys with number of messages sent so far this hour.

get_safety_mode - PUBLIC

Validates that we are in safety mode. Returns a bool as long as we are an object, otherwise returns undef

SendGroupMessage - PUBLIC
$bot->SendGroupMessage($name, $message);

Tells the bot to send a message to the recipient room name

SendPersonalMessage - PUBLIC
$bot->SendPersonalMessage($recipient, $message);

How to send an individual message to someone.

$recipient must read as user@server/Resource or it will not send.

SetForumSubject - PUBLIC
$bot->SetForumSubject($recipient, $subject);

Sets the subject of a forum

AUTHOR

Todd E Rinaldo, <todd.e.rinaldo at jpmorgan.com>

BUGS

Please report any bugs or feature requests to bug-net-jabber-bot at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Jabber-Bot. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::Jabber::Bot

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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.