bigbluebutton-api-ruby 0.0.4 → 0.0.6

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+pkg
+*.*~
+test/config.yml
+doc/rdoc

data/CHANGELOG.rdoc

@@ -0,0 +1,23 @@
+== 0.0.5
+
+* New method test_connection.
+* Added comparison method for APIs.
+* Methods attendee_url and moderator_url deprecated. Use join_meeting_url.
+* Better exception throwing when the user is unreachable or the response is incorrect.
+  * BigBlueButtonException has now a "key" attribute to store the "messageKey" returned by BBB in failures.
+
+== 0.0.4
+
+* Added support for BigBlueButton 0.7.
+* Gem renamed from 'bigbluebutton' to 'bigbluebutton-api-ruby'.
+* API functions now return a hash and instead of the XML returned by BBB. The XML is converted to a hash that uses symbols as keys and groups keys with the same name.
+
+== 0.0.3
+
+* Fixes module issue preventing proper throwing of exceptions.
+
+== 0.0.1
+
+* This is the first version of this gem. It provides an implementation of the 0.64 bbb API, with the following exceptions:
+  * Does not implement meeting token, and instead relies on meeting id as the unique identifier for a meeting.
+  * Documentation suggests there is way to call join_meeting as API call (instead of browser URL). This call currently does not work as documented.

data/LICENSE

@@ -1,6 +1,9 @@
 == bigbluebutton-api-ruby
 
 Copyright (c) 2011 Leonardo Crauss Daronco
+GT-Mconf: Multiconference system for interoperable web and mobile
+  * http://www.inf.ufrgs.br/prav/gtmconf
+  * PRAV Labs - UFRGS
 
 Copyright (c) 2010 Joe Kinsella
 

data/README.rdoc

@@ -0,0 +1,32 @@
+= Project: bigbluebutton-api-ruby
+
+== Goal
+
+Provide access to the BigBlueButton web conferencing API.
+
+== Dependencies
+
+Tested in Ruby 1.8.7 and Ruby 1.9.2.
+
+Needs: rake, rubygems, nokogiri
+
+== Releases
+
+See CHANGELOG.rdoc
+
+== Contact
+
+=== Version 0.0.4+
+
+Author::     Leonardo Crauss Daronco
+Email::      leonardodaronco@gmail.com
+Project::    GT-Mconf: Multiconference system for interoperable web and mobile @ PRAV Labs - UFRGS
+Home Page::  http://www.inf.ufrgs.br/prav/gtmconf/
+License::    Distributed under same terms as Ruby
+
+=== Version 0.0.3 and below
+
+Author::     Joe Kinsella
+Email::      joe.kinsella@gmail.com
+Home Page::  http://www.brownbaglunch.com/bigbluebutton
+License::    Distributes under same terms as Ruby

data/Rakefile

@@ -1,45 +1,28 @@
-# 
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
-
 require 'rubygems'
 require 'rake'
 require 'rake/clean'
-require 'rake/gempackagetask'
 require 'rake/rdoctask'
 require 'rake/testtask'
+require 'rake/gempackagetask'
 
-spec = Gem::Specification.new do |s|
-  s.name = 'bigbluebutton-api-ruby'
-  s.version = '0.0.4'
-  s.has_rdoc = true
-  s.extra_rdoc_files = ['README', 'LICENSE']
-  s.summary = 'Provides an interface to the BigBlueButton web meeting API (https://github.com/mconf/bigbluebutton-api-ruby)'
-  s.description = s.summary
-  s.author = 'Leonardo Crauss Daronco'
-  s.email = 'leonardodaronco@gmail.com'
-  s.homepage = "https://github.com/mconf/bigbluebutton-api-ruby/"
-  # s.executables = ['your_executable_here']
-  s.files = %w(LICENSE README Rakefile) + Dir.glob("{bin,lib,doc,test,spec}/**/*")
-  s.require_path = "lib"
-  s.bindir = "bin"
-end
-
-Rake::GemPackageTask.new(spec) do |p|
-  p.gem_spec = spec
-  p.need_tar = true
-  p.need_zip = true
-end
+desc 'Default: run tests.'
+task :default => :test
 
 Rake::RDocTask.new do |rdoc|
-  files =['README', 'LICENSE', 'lib/**/*.rb']
+  files = ['README.rdoc', 'LICENSE', 'CHANGELOG.rdoc', 'lib/**/*.rb']
   rdoc.rdoc_files.add(files)
   rdoc.main = "README" # page to start on
   rdoc.title = "bigbluebutton-api-ruby Docs"
-  rdoc.rdoc_dir = 'doc/' # rdoc output folder
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
   rdoc.options << '--line-numbers'
 end
 
+eval("$specification = begin; #{ IO.read('bigbluebutton-api-ruby.gemspec')}; end")
+Rake::GemPackageTask.new $specification do |pkg|
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+
 desc 'Test the gem.'
 Rake::TestTask.new(:test) do |t|
   t.pattern = 'test/**/*test.rb'

data/bigbluebutton-api-ruby.gemspec

@@ -0,0 +1,18 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = 'bigbluebutton-api-ruby'
+  s.version = '0.0.6'
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README.rdoc', 'LICENSE', 'CHANGELOG.rdoc']
+  s.summary = 'Provides an interface to the BigBlueButton web meeting API (https://github.com/mconf/bigbluebutton-api-ruby)'
+  s.description = s.summary
+  s.authors = ['Leonardo Crauss Daronco', 'Joe Kinsella']
+  s.email = ['leonardodaronco@gmail.com', 'joe.kinsella@gmail.com']
+  s.homepage = "https://github.com/mconf/bigbluebutton-api-ruby/"
+  s.bindir = "bin"
+  s.files         = `git ls-files`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency('nokogiri', '~> 1.4.0')
+end

data/lib/bigbluebutton-api.rb

@@ -9,22 +9,32 @@ require 'hash_to_xml'
 module BigBlueButton
 
   class BigBlueButtonException < Exception
+    attr_accessor :key
+
+    def to_s
+      unless key.blank?
+        super.to_s + ", messageKey: #{key}"
+      else
+        super
+      end
+    end
 
   end
 
-  # This class provides access to the BigBlueButton API.  BigBlueButton
+  # This class provides access to the BigBlueButton API. BigBlueButton
   # is an open source project that provides web conferencing for distance
   # education (http://code.google.com/p/bigbluebutton/wiki/API). This API
-  # was developed to support the following version of bbb: 0.64, 0.7
-  # 
+  # was developed to support the following version of BBB: 0.64, 0.7
+  #
   # Sample usage of the API is as follows:
   # 1) Create a meeting with the create_meeting call
-  # 2) Direct a user to either moderator_url or attendee_url
+  # 2) Direct a user to either join_meeting_url
   # 3) To force meeting to end, call end_meeting
   #
   # 0.0.4+:
   # Author::    Leonardo Crauss Daronco  (mailto:leonardodaronco@gmail.com)
   # Copyright:: Copyright (c) 2011 Leonardo Crauss Daronco
+  # Project::   GT-Mconf: Multiconference system for interoperable web and mobile @ PRAV Labs - UFRGS
   # License::   Distributes under same terms as Ruby
   #
   # 0.0.3 and below:
@@ -32,45 +42,54 @@ module BigBlueButton
   # Copyright:: Copyright (c) 2010 Joe Kinsella
   # License::   Distributes under same terms as Ruby
   #
-  # TODO: api version returned on index - added in 0.7
+  # TODO: Automatically detect API version using request to index - added in 0.7
   #
   class BigBlueButtonApi
 
+    attr_accessor :url, :supported_versions, :salt, :version, :debug
+
     # Initializes an instance
-    # base_url::  URL to a BigBlueButton server (e.g. http://demo.bigbluebutton.org/bigbluebutton/api)
+    # url::       URL to a BigBlueButton server (e.g. http://demo.bigbluebutton.org/bigbluebutton/api)
     # salt::      Secret salt for this server
     # version::   API version: 0.64 or 0.7
-    def initialize(base_url, salt, version='0.7', debug=false)
+    def initialize(url, salt, version='0.7', debug=false)
       @supported_versions = ['0.7', '0.64']
       unless @supported_versions.include?(version)
         raise BigBlueButtonException.new("BigBlueButton error: Invalid API version #{version}. Supported versions: #{@supported_versions.join(', ')}")
       end
-      @session = {}
-      @base_url = base_url
+      @url = url
       @salt = salt
       @debug = debug
       @version = version
       puts "BigBlueButtonAPI: Using version #{@version}" if @debug
     end
 
-    # Returns url to login as moderator
-    # meeting_id::  Unique identifier for the meeting
-    # user_name::   Name of the user
-    # password::    Moderator password for this meeting
-    def moderator_url(meeting_id, user_name, password)
-      attendee_url(meeting_id, user_name, password)
+    # DEPRECATED
+    # Use join_meeting_url
+    def moderator_url(meeting_id, user_name, password,
+                      user_id = nil, web_voice_conf = nil)
+      warn "#{caller[0]}: moderator_url is deprecated and will soon be removed, please use join_meeting_url instead."
+      join_meeting_url_url(meeting_id, user_name, password, user_id, web_voice_conf)
     end
 
-    # Returns url to login as attendee
+    # DEPRECATED
+    # Use join_meeting_url
+    def attendee_url(meeting_id, user_name, password,
+                     user_id = nil, web_voice_conf = nil)
+      warn "#{caller[0]}: attendee_url is deprecated and will soon be removed, please use join_meeting_url instead."
+      join_meeting_url(meeting_id, user_name, password, user_id, web_voice_conf)
+    end
+
+    # Returns the url used to join the meeting
     # meeting_id::        Unique identifier for the meeting
     # user_name::         Name of the user
-    # password::          Attendee password for this meeting
-    # user_id::           Unique identifier for this user (>=0.7)
-    # web_voice_conf::    Custom voice-extension for users using VoIP (>=0.7)
-    def attendee_url(meeting_id, user_name, attendee_password,
-                     user_id = nil, web_voice_conf = nil)
+    # password::          Password for this meeting - used to set the user as moderator or attendee
+    # user_id::           Unique identifier for this user (>= 0.7)
+    # web_voice_conf::    Custom voice-extension for users using VoIP (>= 0.7)
+    def join_meeting_url(meeting_id, user_name, password,
+                         user_id = nil, web_voice_conf = nil)
 
-      params = { :meetingID => meeting_id, :password => attendee_password, :fullName => user_name }
+      params = { :meetingID => meeting_id, :password => password, :fullName => user_name }
       if @version == '0.7'
         params[:userID] = user_id
         params[:webVoiceConf] = web_voice_conf
@@ -89,7 +108,7 @@ module BigBlueButton
     # logout_url::          URL to return user to after exiting meeting
     # voice_bridge::        Voice conference number (>=0.7)
     # TODO check if voice_bridge exists in 0.64
-    def create_meeting(meeting_name, meeting_id, moderator_password, attendee_password, 
+    def create_meeting(meeting_name, meeting_id, moderator_password, attendee_password,
                        welcome_message = nil, dial_number = nil, logout_url = nil,
                        max_participants = nil, voice_bridge = nil)
 
@@ -131,7 +150,7 @@ module BigBlueButton
     def join_meeting(meeting_id, user_name, password, user_id = nil, web_voice_conf = nil)
       params = { :meetingID => meeting_id, :password => password, :fullName => user_name }
       if @version == '0.64'
-        params[:redirectImmediately] = 0 
+        params[:redirectImmediately] = 0
       elsif @version == '0.7'
         params[:userID] = user_id
         params[:webVoiceConf] = web_voice_conf
@@ -152,47 +171,81 @@ module BigBlueButton
     # Returns a hash object containing the meeting information.
     # See the API documentation for details on the return XML
     # (http://code.google.com/p/bigbluebutton/wiki/API).
-    # >= 0.7
-    #
-    # TODO check if getMeetings exists in 0.64
     def get_meetings
+      send_api_request(:getMeetings, { :random => rand(9999999999) } )
+    end
+
+    # Make a simple request to the server to test the connection
+    # TODO implement test for version 0.64
+    def test_connection
       if @version == '0.7'
-        send_api_request(:getMeetings, { :random => rand(9999999999) } )
+        response = send_api_request(:index)
+        response[:returncode] == "SUCCESS"
       else
-        {}
+        true
+      end
+    end
+
+    # API's are equal if all the following attributes are equal
+    def == other
+      r = true
+      [:url, :supported_versions, :salt, :version, :debug].each do |param|
+        r = r and self.send(param) == other.send(param)
       end
+      r
     end
 
     protected
 
     def get_url(method, data)
-      base_url = "#{@base_url}/#{method}?"
+      if method == :index
+        return @url
+      end
+
+      url = "#{@url}/#{method}?"
+
+      data.delete_if { |k, v| v.nil? } unless data.nil?
       params = ""
       params = data.map{ |k,v| "#{k}=" + CGI::escape(v.to_s) unless k.nil? || v.nil? }.join("&")
+
       checksum_param = params + @salt
       checksum_param = method.to_s + checksum_param if @version == '0.7'
       checksum = Digest::SHA1.hexdigest(checksum_param)
-      "#{base_url}#{params}&checksum=#{checksum}"
+
+      "#{url}#{params}&checksum=#{checksum}"
     end
 
     def send_api_request(method, data = {})
       url = get_url(method, data)
-      res = Net::HTTP.get_response(URI.parse(url))
-      puts "BigBlueButtonAPI: URL request = #{url}" if @debug
-      puts "BigBlueButtonAPI: URL response = #{res.body}" if @debug
+      begin
+        res = Net::HTTP.get_response(URI.parse(url))
+        puts "BigBlueButtonAPI: URL request = #{url}" if @debug
+        puts "BigBlueButtonAPI: URL response = #{res.body}" if @debug
+      rescue Exception => socketerror
+        raise BigBlueButtonException.new("Connection error. Your URL is probably incorrect: \"#{@url}\"")
+      end
 
       if res.body.empty?
-        raise BigBlueButtonException.new("BigBlueButton error: No XML in the response body")
+        raise BigBlueButtonException.new("No response body")
       end
 
-      # 'Hashfy' the XML and remove the "response" node
+      # 'Hashify' the XML
       hash = Hash.from_xml res.body
+
+      # simple validation of the xml body
+      unless hash.has_key?(:response) and hash[:response].has_key?(:returncode)
+        raise BigBlueButtonException.new("Invalid response body. Is the API URL correct? \"#{@url}\", version #{@version}")
+      end
+
+      # and remove the "response" node
       hash = Hash[hash[:response]].inject({}){|h,(k,v)| h[k] = v; h}
       puts "BigBlueButtonAPI: URL response hash = #{hash.inspect}" if @debug
 
       return_code = hash[:returncode]
       unless return_code == "SUCCESS"
-        raise BigBlueButtonException.new("BigBlueButton error: #{hash[:message]}")
+        exception = BigBlueButtonException.new(hash[:message])
+        exception.key = hash.has_key?(:messageKey) ? hash[:messageKey] : ""
+        raise exception
       end
       hash
     end

data/lib/hash_to_xml.rb

@@ -9,7 +9,7 @@ class Hash
         result = Nokogiri::XML(xml_io)
         return { result.root.name.to_sym => xml_node_to_hash(result.root)} 
       rescue Exception => e
-        raise BigBlueButton::BigBlueButtonException.new("BigBlueButton error: Impossible to convert XML to hash. Error: #{e.message}")
+        raise BigBlueButton::BigBlueButtonException.new("Impossible to convert XML to hash. Error: #{e.message}")
       end
     end 
 

data/test/test.rb

@@ -24,6 +24,15 @@ end
 
 def general_test
 
+  puts
+  puts "---------------------------------------------------"
+  if @api.test_connection
+    puts "Connection success! continuing..."
+  else
+    puts "Connection failed! The server might be unreachable. Exiting..."
+    Kernel.exit!
+  end
+
   puts
   puts "---------------------------------------------------"
   response = @api.get_meetings
@@ -45,14 +54,14 @@ def general_test
   puts "---------------------------------------------------"
   @api.create_meeting(@config['meeting_name'], @config['meeting_id'], @config['moderator_password'], @config['attendee_password'],
                      'Welcome to my meeting', '1-800-000-0000x00000#', 'https://github.com/mconf/bigbluebutton-api-ruby', 10)
-  puts "The meeting has been created. Please open a web browser and enter the meeting using either of the below URLs."
+  puts "The meeting has been created. Please open a web browser and enter the meeting using either of the URLs below."
 
   puts
   puts "---------------------------------------------------"
-  url = @api.moderator_url(@config['meeting_id'], @config['moderator_name'], @config['moderator_password'])
+  url = @api.join_meeting_url(@config['meeting_id'], @config['moderator_name'], @config['moderator_password'])
   puts "1) Moderator URL = #{url}"
   puts ""
-  url = @api.attendee_url(@config['meeting_id'], @config['attendee_name'], @config['attendee_password'])
+  url = @api.join_meeting_url(@config['meeting_id'], @config['attendee_name'], @config['attendee_password'])
   puts "2) Attendee URL = #{url}"
 
   puts
@@ -88,12 +97,12 @@ def join_test
     @api.create_meeting(@config['meeting_name'], @config['meeting_id'], @config['moderator_password'], @config['attendee_password'],
                        'Welcome to my meeting', '1-800-000-0000x00000#', 'https://github.com/mconf/bigbluebutton-api-ruby', 10)
     puts "The meeting has been created. Please open a web browser and enter the meeting as moderator."
-    
+
     puts
     puts "---------------------------------------------------"
-    url = @api.moderator_url(@config['meeting_id'], @config['moderator_name'], @config['moderator_password'])
+    url = @api.join_meeting_url(@config['meeting_id'], @config['moderator_name'], @config['moderator_password'])
     puts "1) Moderator URL = #{url}"
-    
+
     puts
     puts "---------------------------------------------------"
     puts "Waiting 30 seconds for you to enter via browser"
@@ -105,7 +114,7 @@ def join_test
     Kernel.exit!
   end
   puts "You have successfully entered the meeting"
- 
+
   puts
   puts "---------------------------------------------------"
   response = @api.get_meeting_info(@config['meeting_id'], @config['moderator_password'])
@@ -119,7 +128,7 @@ def join_test
   response = @api.join_meeting(@config['meeting_id'], @config['attendee_name'], @config['attendee_password'])
   puts "Join meeting response:"
   puts response.inspect
- 
+
 end
 
 begin