Tutorial

require 'msn/msn'

First of all, before you even start, you should use the

require 'msn/msn'

statement in order to use the MSN classes. Your own bot script should be next to the msn directory, not in. You can also create a soft link to the msn directory, when you want freedom. Let's move on...

MSNConnection basics

The most important class in RubyMSN is MSNConnection. It handles the connection with the MSN servers, manages your contact lists, initiates chat sessions and so on. This class is your primary tool.

First, we will create it using its constructor which takes 2 parameters: your MSN passport account name (in short, your MSN e-mail address ;-) and your MSN password. Then, we call the start method to initiate the session.

require 'msn/msn'

conn = MSNConnection.new("rubybot@channelwood.org", "secretpassword123")
conn.start

When we run this, and watch the output carefully, we see something like:

--> Sent: "VER 1 MSNP9 CVR0\r\n"

and it immediately exits. Whoops! What are we doing wrong?

The start method in fact starts a new thread which handles all the incoming messages. While that new thread is trying to connect to the MSN servers, our application exits immiately because the main thread is doing nothing anymore. We should keep our application alive somehow. This could be some GUI mainloop thread or something, but for this simple tutorial we will just use a lame method: the endless loop. To save some CPU time, we will put a sleep 1 in it. Now we have:

require 'msn/msn'

conn = MSNConnection.new("rubybot@channelwood.org", "secretpassword123")
conn.start

while true
  sleep 1
end

OK, let's try it again. Wohow! What the hell?! Indeed my friend. What you see now are the exact unfiltered TCP packets carrying commands back and forth. We will define this now as the dump. How we can turn it off is explained later. When your password was correct, you will be successfully logged into the MSN network.

At this point, we are ready to assign some event handlers. What, has Ruby events??? you might ask now. They are not real events in the sense of .NET or Java, but Ruby code blocks containing code which should be executed when appropriate. These blocks can have useful parameters too. It looks almost like .NET events indeed.

At the moment of writing this tutorial, MSNConnection has the following events:

• signed_in
• buddy_update
• new_chat_session

The most interesting event of this list is new_chat_session. It has 2 parameters. We will now create a little handler for it:

require 'msn/msn'

conn = MSNConnection.new("rubybot@channelwood.org", "secretpassword123")
conn.new_chat_session = lambda do |tag, session|
  puts "*** new chat session created with tag '#{tag}'!"
  session.start
end

conn.start

while true
  sleep 1
end

When we run this, and we try to chat with our client, we get somewhere between the dump something like:

*** new chat session created with tag 'jef@hiddendomain.com334'!

The tag parameter is a unique identifier which you can use to refer to that chat session. The session parameter is a MSNChatSession object which represents the chat session itself. Now why do we call the start method on it? This is by design so you can add handlers to events of MSNChatSession before really starting the chat session. More on that in the next section...

Chat sessions

Now we move on to the MSNChatSession class. The main events of this class are:

• message_received
• session_started
• participants_updated

The message_received event is obvious. It has 2 parameters: the username of the sender and the message itself. The session_started event will be fired as soon as the MSNChatSession is ready to accept incoming and outgoing messages. We will not discuss participants_updated in this tutorial. If you are curious, look at the source code. ;-)

Now we will handle the message_received event in our small piece of code:

require 'msn/msn'

conn = MSNConnection.new("rubybot@channelwood.org", "secretpassword123")

conn.debuglog = nil
conn.new_chat_session = lambda do |tag, session|
  puts "*** new chat session created with tag '#{tag}'!"
  
  session.debuglog = nil
  session.message_received = lambda do |sender, message|
    puts "*** #{sender} says: #{message}"
    session.say message.reverse
  end

  session.start
end

conn.start

while true
  sleep 1
end

In this piece of code you can see the say method of the class MSNChatSession. Now we have set up basic two-way communication! We have also turned off the dump by setting the debuglog events to nil.

This is the end of this tutorial. For more information, look at the source! It isn't that hard to understand. Also, don't miss the examples!