em-msn 0.2 → 0.3

data/README.md

@@ -0,0 +1,60 @@
+# em-msn
+
+MSN client (EventMachine + Ruby)
+
+## Project Pages
+
+* [Docs](http://rdoc.info/gems/em-msn)
+* [GitHub](https://github.com/manastech/em-msn)
+
+# Usage
+
+## Installation
+
+    gem install em-msn
+
+## Gemfile
+
+    gem 'em-msn'
+
+## Example
+
+    require 'rubygems'
+    require 'em-msn'
+
+    EM.run do
+      EM.schedule do
+        msn = Msn::Messenger.new 'johndoe@hotmail.com', 'password'
+
+        msn.on_login_failed do |reason|
+          puts "Oops... #{reason}"
+        end
+
+        msn.on_ready do
+          msn.set_online_status :online
+        end
+
+        msn.on_message do |message|
+          puts "Got message from #{message.email}: #{message.text}"
+
+          msn.send_message message.email, "Hi #{message.display_name}!"
+        end
+
+        msn.on_contact_request do |email, display_name|
+          puts "Contact request from #{display_name} <#{email}>"
+
+          msn.add_contact email
+        end
+
+        msn.connect
+      end
+    end
+
+# Contributions
+
+All contributions are welcome. The gem doesn't have many tests and a lot of things
+can be improved, as some parts of the protocol are not yet implemented.
+
+# Author
+
+[Ary Borenszweig](http://github.com/asterite)

data/lib/em-msn.rb

@@ -1,4 +1,5 @@
 module Msn
+  # :nodoc:
   ApplicationId = "CFE80F9D-180F-4399-82AB-413F33A1FA11"
 end
 

data/lib/msn/challenge.rb

@@ -1,3 +1,4 @@
+# :nodoc:
 class Msn::Challenge
   ProductKey = "RG@XY*28Q5QHS%Q5"
   ProductId = "PROD0113H11T8$X_"
@@ -37,7 +38,7 @@ class Msn::Challenge
       new_hash_parts[2] ^= high;
       new_hash_parts[3] ^= low;
 
-      new_hash_parts.map do |num| 
+      new_hash_parts.map do |num|
         str = num.to_s(16)
         str = "#{'0' * (8 - str.length)}#{str}" if str.length != 8
         str.scan(/.{2}/).reverse.join

data/lib/msn/contact.rb

@@ -1,16 +1,31 @@
+# A contact returned from Msn::Messenger#get_contacts.
 class Msn::Contact
+
+  # The contact's email
   attr_accessor :email
+
+  # The contact's display name
   attr_accessor :display_name
+
+  # Is the contact in your allow list?
   attr_accessor :allow
+
+  # Is the contact in your blocked list?
   attr_accessor :block
+
+  # Is the contact in your reverse list? (does she has you?)
   attr_accessor :reverse
+
+  # Is the contact in your pending list? (you stil didn't approve her)
   attr_accessor :pending
 
+  # :nodoc:
   def initialize(email, display_name = nil)
     @email = email
     @display_name = display_name
   end
 
+  # :nodoc:
   def to_s
     if display_name && display_name.length > 0
       str = "#{display_name} <#{email}>"

data/lib/msn/message.rb

@@ -1,8 +1,10 @@
+# A message sent to a Messenger.
 class Msn::Message
   attr_accessor :email
   attr_accessor :display_name
   attr_accessor :text
 
+  # :nodoc:
   def initialize(email, display_name, text)
     @email = email
     @display_name = display_name

data/lib/msn/messenger.rb

@@ -1,27 +1,29 @@
+# Main class to communicate with MSN.
 class Msn::Messenger
   attr_reader :username
   attr_reader :password
 
-  class << self
-    attr_accessor :logger
-
-    def log_info(message)
-      return unless logger
-
-      logger.info message
-    end
-  end
-
-
+  # Create an MSN connection with a username (email) and password.
   def initialize(username, password)
     @username = username
     @password = password
   end
 
+  # Connects to the MSN server. Event handlers should be set before calling this method.
   def connect
     @notification_server = EM.connect 'messenger.hotmail.com', 1863, Msn::NotificationServer, self
   end
 
+  # Sets your online status. Status can be:
+  # * :available, :online
+  # * :busy
+  # * :idle
+  # * :brb, :be_right_back
+  # * :away
+  # * :phone, :on_the_phone
+  # * :lunch, :out_to_lunch
+  # It is advisable to call this method as soon as you connect, otherwise you
+  # won't be able to perform certain actions (like sending messages).
   def set_online_status(status)
     case status
     when :available, :online
@@ -43,91 +45,161 @@ class Msn::Messenger
     end
   end
 
+  # Adds a contact. Technically, this adds it to your Friends List.
   def add_contact(email)
     send_contact_command email, 'ADL', '1'
   end
 
+  # Removes a contact. Technically, this removes it from your Friends List.
   def remove_contact(email)
     send_contact_command email, 'RML', '1'
   end
 
+  # Blocks a contact. Technically, this removes it from your Allowed List.
   def block_contact(email)
     send_contact_command email, 'RML', '2'
   end
 
+  # Unblocks a contact. Technically, this adds it to your Allowed List.
   def unblock_contact(email)
     send_contact_command email, 'ADL', '2'
   end
 
+  # Returns all contacts associated to this Messenger account.
+  # This is an array of Msn::Contact.
   def get_contacts
     @notification_server.get_contacts
   end
 
+  # Invoked when this Messenger gets connected to the server.
+  #
+  #     msn.on_ready do
+  #       msn.set_online_status :online
+  #     end
   def on_ready(&handler)
     @on_ready_handler = handler
   end
 
+  # Invoked when the username/password are incorrect.
+  #
+  #     msn.on_login_failed do |reason|
+  #       puts "Login failed: #{reason} :-("
+  #       msn.close
+  #     end
   def on_login_failed(&handler)
     @on_login_failed = handler
   end
 
+  # Invoked when this Messenger gets disconnected from the server.
+  #
+  #     msn.on_disconnect do
+  #       # Try to reconnect
+  #       msn.connect
+  #     end
   def on_disconnect(&handler)
     @on_disconnect = handler
   end
 
+  # Invoked when somebody sends a messages to this account, with an Msn::Message.
+  #
+  #     msn.on_message do |msg|
+  #       # msg is an Msn:Message instance
+  #     end
   def on_message(&handler)
     @on_message_handler = handler
   end
 
+  # Invoked after a message is sent by this Messenger, to know
+  # what happened with it.
+  #
+  #     msn.on_message_ack do |message_id, status|
+  #       # status can be :ack, :nak or :offline
+  #       # message_id is the one you got from send_message
+  #     end
   def on_message_ack(&handler)
     @on_message_ack_handler = handler
   end
 
+  # Invoked when there is a contact request.
+  #
+  #     msn.on_contact_request do |email, display_name|
+  #       ...
+  #     end
   def on_contact_request(&handler)
     @on_contact_request = handler
   end
 
+  # Sends a message to the given email with the given text.
+  # Returns an ID (a number) that can be used to relate the
+  # send messages to ACKs.
   def send_message(email, text)
     @notification_server.send_message email, text
   end
 
+  # Closes the connection to the MSN server.
   def close
     @notification_server.close_connection
   end
 
+  # :nodoc:
   def send_contact_command(email, command, list)
     username, domain = email.split '@', 2
     @notification_server.send_payload_command_and_wait command, %Q(<ml><d n="#{domain}"><c n="#{username}" t="1" l="#{list}" /></d></ml>)
   end
 
+  # :nodoc:
   def accept_message(message)
     call_handler @on_message_handler, message
   end
 
+  # :nodoc:
   def accept_message_ack(id, status)
     call_handler @on_message_ack_handler, id, status
   end
 
+  # :nodoc:
   def contact_request(email, display_name)
     call_handler @on_contact_request, email, display_name
   end
 
+  # :nodoc:
   def ready
     call_handler @on_ready_handler
   end
 
+  # :nodoc:
   def login_failed(message)
     call_handler @on_login_failed, message
   end
 
+  # :nodoc:
   def disconnected
     call_handler @on_disconnect
   end
 
+  # :nodoc:
   def call_handler(handler, *args)
     if handler
       Fiber.new { handler.call(*args) }.resume
     end
   end
+
+  # Sets a logger that will get logged as info all communication to the MSN server
+  # (but not all communication to the MSN nexus server).
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  # :nodoc:
+  def self.logger
+    @logger
+  end
+
+  # :nodoc:
+  def self.log_info(message)
+    return unless logger
+
+    logger.info message
+  end
 end
 

data/lib/msn/nexus.rb

@@ -1,3 +1,4 @@
+# :nodoc:
 class Msn::Nexus
   attr_reader :messenger
   attr_reader :policy

data/lib/msn/notification_server.rb

@@ -1,3 +1,4 @@
+# :nodoc:
 class Msn::NotificationServer < EventMachine::Connection
   include Msn::Protocol
 

data/lib/msn/protocol.rb

@@ -1,3 +1,4 @@
+# :nodoc:
 module Msn::Protocol
   include EventMachine::Protocols::LineText2
 

data/lib/msn/switchboard.rb

@@ -1,3 +1,4 @@
+# :nodoc:
 class Msn::Switchboard < EventMachine::Connection
   include Msn::Protocol
 

data/lib/msn/version.rb

@@ -1,3 +1,3 @@
 module Msn
-  VERSION = "0.2"
+  VERSION = "0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-msn
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-07 00:00:00.000000000 Z
+date: 2012-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine