bigbluebutton-api-ruby 0.0.11 → 0.1.0.rc1

data/features/step_definitions/common_steps.rb

@@ -0,0 +1,122 @@
+# Common steps, used in several features
+
+When /^the default BigBlueButton server$/ do
+  @api = BigBlueButton::BigBlueButtonApi.new(@config_server['url'],
+                                             @config_server['salt'],
+                                             @config_server['version'].to_s,
+                                             @config['debug'])
+  @api.timeout = @config['timeout_req']
+end
+
+# default create call, with no optional parameters (only the mod pass)
+When /^that a meeting was created$/ do
+  steps %Q{ When the default BigBlueButton server }
+
+  @req.id = Forgery(:basic).random_name("test")
+  @req.name = @req.id
+  @req.mod_pass = Forgery(:basic).password
+  @req.opts = { :moderatorPW => @req.mod_pass }
+  @req.method = :create
+  @req.response = @api.create_meeting(@req.id, @req.name, @req.opts)
+end
+
+When /^that a meeting was created with all the optional arguments$/i do
+  steps %Q{ When the default BigBlueButton server }
+
+  @req.id = Forgery(:basic).random_name("test-create")
+  @req.name = @req.id
+  @req.mod_pass = Forgery(:basic).password
+  @req.opts = { :moderatorPW => @req.mod_pass,
+                :attendeePW => Forgery(:basic).password,
+                :welcome => Forgery(:lorem_ipsum).words(10),
+                :dialNumber => Forgery(:basic).number(:at_most => 999999999).to_s,
+                :logoutURL => Forgery(:internet).url,
+                :voiceBridge => Forgery(:basic).number(:at_least => 70000, :at_most => 79999),
+                :webVoice => Forgery(:basic).text,
+                :maxParticipants => Forgery(:basic).number }
+  if @api.version >= "0.8"
+    @req.opts.merge!( { :record => false,
+                        :duration => Forgery(:basic).number(:at_least => 10, :at_most => 60),
+                        :meta_one => "one", :meta_TWO => "TWO" } )
+  end
+  @req.method = :create
+  @req.response = @api.create_meeting(@req.id, @req.name, @req.opts)
+end
+
+When /^the meeting is running$/ do
+  steps %Q{ When the meeting is running with 1 attendees }
+end
+
+When /^the meeting is running with (\d+) attendees$/ do |count|
+  mobile_salt = @config_server.has_key?('mobile_salt') ? @config_server['mobile_salt'] : ""
+  BigBlueButtonBot.new(@api, @req.id, mobile_salt, count.to_i, @config['timeout_bot_start'])
+end
+
+When /^the response is an error with the key "(.*)"$/ do |key|
+  @req.exception.should_not be_nil
+  @req.exception.key.should == key
+end
+
+When /^the response is successful$/ do
+  @req.response[:returncode].should be_true
+end
+
+When /^the response is successful with no messages$/ do
+  @req.response[:returncode].should be_true
+  @req.response[:messageKey].should == ""
+  @req.response[:message].should == ""
+end
+
+When /^the response has the messageKey "(.*)"$/ do |key|
+  @req.response[:messageKey].should == key
+  @req.response[:message].should_not be_empty
+end
+
+When /^the response is successful and well formatted$/ do
+  case @req.method
+  when :create
+    steps %Q{ When the response to the create method is successful and well formatted }
+  when :end
+    steps %Q{ When the response to the end method is successful and well formatted }
+  when :get_recordings
+    steps %Q{ When the response to the get_recordings method is successful and well formatted }
+  end
+end
+
+When /^the response to the create method is successful and well formatted$/ do
+  @req.response[:returncode].should be_true
+  @req.response[:meetingID].should == @req.id
+  @req.response[:hasBeenForciblyEnded].should be_false
+  @req.response[:messageKey].should == ""
+  @req.response[:message].should == ""
+
+  if @req.opts.has_key?(:attendeePW)
+    @req.response[:attendeePW].should == @req.opts[:attendeePW]
+  else # auto generated password
+    @req.response[:attendeePW].should be_a(String)
+    @req.response[:attendeePW].should_not be_empty
+    @req.opts[:attendeePW] = @req.response[:attendeePW]
+  end
+  if @req.opts.has_key?(:moderatorPW)
+    @req.response[:moderatorPW].should == @req.opts[:moderatorPW]
+  else # auto generated password
+    @req.response[:moderatorPW].should be_a(String)
+    @req.response[:moderatorPW].should_not be_empty
+    @req.opts[:moderatorPW] = @req.response[:moderatorPW]
+  end
+
+  if @api.version >= "0.8"
+    @req.response[:createTime].should be_a(Numeric)
+  end
+end
+
+When /^the response to the end method is successful and well formatted$/ do
+  @req.response[:returncode].should be_true
+  @req.response[:messageKey].should == "sentEndMeetingRequest"
+  @req.response[:message].should_not be_empty
+end
+
+When /^the response to the get_recordings method is successful and well formatted$/ do
+  @req.response[:returncode].should be_true
+  @req.response[:recordings].should == []
+end

data/features/step_definitions/create_meetings_steps.rb

@@ -0,0 +1,54 @@
+When /^the create method is called with all the optional arguments$/i do
+  steps %Q{ When that a meeting was created with all the optional arguments }
+end
+
+When /^the create method is called with no optional arguments$/i do
+  steps %Q{ When the default BigBlueButton server }
+  steps %Q{ When that a meeting was created }
+end
+
+When /^the create method is called with a duplicated meeting id$/ do
+  steps %Q{ When the default BigBlueButton server }
+
+  @req.id = Forgery(:basic).random_name("test-create")
+  @req.name = @req.id
+
+  # first meeting
+  @req.method = :create
+  @api.create_meeting(@req.id, @req.name)
+
+  begin
+    # duplicated meeting to be tested
+    @req.method = :create
+    @req.response = @api.create_meeting(@req.id, @req.name)
+  rescue Exception => @req.exception
+  end
+end
+
+When /^the create method is called$/ do
+  steps %Q{ When the default BigBlueButton server }
+
+  @req.id = Forgery(:basic).random_name("test-create")
+  @req.name = @req.id
+  @req.method = :create
+  @req.response = @api.create_meeting(@req.id, @req.name)
+  @req.mod_pass = @req.response[:moderatorPW]
+end
+
+When /^the meeting is forcibly ended$/ do
+  @req.response = @api.end_meeting(@req.id, @req.mod_pass)
+end
+
+When /^the create method is called again with the same meeting id$/ do
+  begin
+    @req.method = :create
+    @req.response = @api.create_meeting(@req.id, @req.name)
+  rescue Exception => @req.exception
+  end
+end
+
+When /^the meeting exists in the server$/ do
+  @req.response = @api.get_meetings
+  @req.response[:meetings].reject!{ |m| m[:meetingID] != @req.id }
+  @req.response[:meetings].count.should == 1
+end

data/features/step_definitions/end_meetings_steps.rb

@@ -0,0 +1,49 @@
+When /^the method to end the meeting is called$/ do
+  begin
+    @req.method = :end
+    @req.response = @api.end_meeting(@req.id, @req.mod_pass)
+  rescue Exception => @req.exception
+  end
+end
+
+When /^the meeting should be ended$/ do
+  # the meeting only ends when everybody closes the session
+  BigBlueButtonBot.finalize
+
+  # wait for the meeting to end
+  Timeout::timeout(@config['timeout_ending']) do
+    running = true
+    while running
+      sleep 1
+      response = @api.get_meetings
+      selected = response[:meetings].reject!{ |m| m[:meetingID] != @req.id }
+      running = selected[0][:running] unless selected.nil?
+    end
+  end
+
+end
+
+When /^the flag hasBeenForciblyEnded should be set$/ do
+  @req.response[:hasBeenForciblyEnded].should be_true
+end
+
+When /^the information returned by get_meeting_info is correct$/ do
+  # check only what is different in a meeting that WAS ENDED
+  # the rest is checked in other scenarios
+
+  @req.response = @api.get_meeting_info(@req.id, @req.mod_pass)
+  @req.response[:running].should be_false
+  @req.response[:hasBeenForciblyEnded].should be_true
+  @req.response[:participantCount].should == 0
+  @req.response[:moderatorCount].should == 0
+  @req.response[:attendees].should == []
+
+  # start and end times that should be within 2 hours from now
+  @req.response[:startTime].should be_a(DateTime)
+  @req.response[:startTime].should < DateTime.now
+  @req.response[:startTime].should >= DateTime.now - (2/24.0)
+  @req.response[:endTime].should be_a(DateTime)
+  @req.response[:endTime].should < DateTime.now
+  @req.response[:endTime].should >= DateTime.now - (2/24.0)
+  @req.response[:endTime].should > @req.response[:startTime]
+end

data/features/step_definitions/join_meetings_steps.rb

@@ -0,0 +1,39 @@
+When /^the user tries to access the link to join the meeting as (.*)$/ do |role|
+  case role.downcase.to_sym
+  when :moderator
+    @req.response = @api.join_meeting_url(@req.id, "any-mod", @req.mod_pass)
+  when :attendee
+    @req.response = @api.join_meeting_url(@req.id, "any-attendee", @req.response[:attendeePW])
+  end
+end
+
+When /^he is redirected to the BigBlueButton client$/ do
+  # requests the join url and expects a redirect
+  uri = URI(@req.response)
+  response = Net::HTTP.get_response(uri)
+  response.should be_a(Net::HTTPFound)
+  response.code.should == "302"
+
+  # check redirect to the correct bbb client page
+  bbb_client_url = @api.url.gsub(URI(@api.url).path, "") + "/client/BigBlueButton.html"
+  response["location"].should match(/#{bbb_client_url}/)
+end
+
+When /^the user tries to access the link to join a meeting that was not created$/ do
+  @req.response = @api.join_meeting_url("should-not-exist-in-server", "any", "any")
+end
+
+When /^the response is an xml with the error "(.*)"$/ do |error|
+  # requests the join url and expects an ok with an xml in the response body
+  uri = URI(@req.response)
+  response = Net::HTTP.get_response(uri)
+  response.should be_a(Net::HTTPOK)
+  response.code.should == "200"
+  response["content-type"].should match(/text\/xml/)
+  response.body.should match(/#{error}/)
+end
+
+When /^the user tries to access the link to join the meeting using a wrong password$/ do
+  @req.response = @api.join_meeting_url(@req.id, "any-attendee", @req.mod_pass + "is wrong")
+end
+

data/features/step_definitions/pre_upload_slides_steps.rb

@@ -0,0 +1,13 @@
+When /^the user creates a meeting pre\-uploading the following presentations:$/ do |table|
+  modules = BigBlueButton::BigBlueButtonModules.new
+  table.hashes.each do |pres|
+    modules.add_presentation(pres["type"].to_sym, pres["presentation"])
+  end
+
+  @req.id = Forgery(:basic).random_name("test-pre-upload")
+  @req.name = @req.id
+  @req.method = :create
+  @req.opts = {}
+  @req.response = @api.create_meeting(@req.id, @req.name, @req.opts, modules)
+  @req.mod_pass = @req.response[:moderatorPW]
+end

data/features/step_definitions/recordings_steps.rb

@@ -0,0 +1,38 @@
+When /^the user creates a meeting with the record flag$/ do
+  steps %Q{ When the default BigBlueButton server }
+
+  @req.id = Forgery(:basic).random_name("test-recordings")
+  @req.name = @req.id
+  @req.method = :create
+  @req.opts = { :record => true }
+  @req.response = @api.create_meeting(@req.id, @req.name, @req.opts)
+  @req.mod_pass = @req.response[:moderatorPW]
+end
+
+When /^the meeting is set to be recorded$/ do
+  @req.response = @api.get_meeting_info(@req.id, @req.mod_pass)
+  @req.response[:returncode].should be_true
+  @req.response[:recording].should be_true
+end
+
+When /^the user creates a meeting without the record flag$/ do
+  steps %Q{ When the default BigBlueButton server }
+
+  @req.id = Forgery(:basic).random_name("test-recordings")
+  @req.name = @req.id
+  @req.method = :create
+  @req.opts = {}
+  @req.response = @api.create_meeting(@req.id, @req.name)
+  @req.mod_pass = @req.response[:moderatorPW]
+end
+
+When /^the meeting is not set to be recorded$/i do
+  @req.response = @api.get_meeting_info(@req.id, @req.mod_pass)
+  @req.response[:returncode].should be_true
+  @req.response[:recording].should be_false
+end
+
+When /^the user calls the get_recordings method$/ do
+  @req.method = :get_recordings
+  @req.response = @api.get_recordings
+end

data/features/support/api_tests/configs.rb

@@ -0,0 +1,51 @@
+module BigBlueButtonAPITests
+
+  # Test object that stores information about an API request
+  class APIRequest
+    attr_accessor :opts       # options hash
+    attr_accessor :id         # meetind id
+    attr_accessor :mod_pass   # moderator password
+    attr_accessor :name       # meeting name
+    attr_accessor :method     # last api method called
+    attr_accessor :response   # last api response
+    attr_accessor :exception  # last exception
+  end
+
+  # Global configurations
+  module Configs
+    class << self
+      attr_accessor :cfg           # configuration file
+      attr_accessor :cfg_server    # shortcut to the choosen server configs
+      attr_accessor :req           # api request
+
+      def initialize_cfg
+        config_file = File.join(File.dirname(__FILE__), '..', '..', 'config.yml')
+        unless File.exist? config_file
+          throw Exception.new(config_file + " does not exists. Copy the example and configure your server.")
+        end
+        config = YAML.load_file(config_file)
+        config
+      end
+
+      def initialize_cfg_server
+        if ENV['SERVER']
+          unless self.cfg['servers'].has_key?(ENV['SERVER'])
+            throw Exception.new("Server #{ENV['SERVER']} does not exists in your configuration file.")
+          end
+          srv = self.cfg['servers'][ENV['SERVER']]
+        else
+          srv = self.cfg['servers'][self.cfg['servers'].keys.first]
+        end
+        srv['bbb_version'] = '0.7' unless srv.has_key?('bbb_version')
+        srv
+      end
+
+      def load
+        self.cfg = initialize_cfg
+        self.cfg_server = initialize_cfg_server
+        self.req = BigBlueButtonAPITests::APIRequest.new
+      end
+
+    end
+  end
+end

data/features/support/env.rb

@@ -0,0 +1,7 @@
+$:.unshift File.join(File.expand_path(File.dirname(__FILE__)), '..', '..', 'lib')
+
+require 'bigbluebutton_api'
+require 'forgery'
+Dir["#{File.dirname(__FILE__)}/../../spec/support/forgery/**/*.rb"].each { |f| require f }
+
+Dir["#{File.dirname(__FILE__)}/../../extras/**/*.rb"].each { |f| require f }

data/features/support/hooks.rb

@@ -0,0 +1,11 @@
+Before do
+  # stores the global configurations in variables that are easier to access
+  BigBlueButtonAPITests::Configs.load
+  @config = BigBlueButtonAPITests::Configs.cfg
+  @config_server = BigBlueButtonAPITests::Configs.cfg_server
+  @req = BigBlueButtonAPITests::Configs.req
+end
+
+After do |scenario|
+  BigBlueButtonBot.finalize
+end

data/lib/bigbluebutton_api.rb

@@ -3,37 +3,27 @@ require 'cgi'
 require 'rexml/document'
 require 'digest/sha1'
 require 'rubygems'
-require 'nokogiri'
 require 'hash_to_xml'
 require 'bigbluebutton_exception'
 require 'bigbluebutton_formatter'
+require 'bigbluebutton_modules'
 
 module 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.7, 0.8 (soon)
+  # This class provides access to the BigBlueButton API. For more details see README.rdoc.
   #
   # Sample usage of the API is as follows:
-  # 1) Create a meeting with the create_meeting call
-  # 2) Direct a user to either join_meeting_url
-  # 3) To force meeting to end, call end_meeting
+  # 1. Create a meeting with create_meeting;
+  # 2. Redirect a user to the URL returned by join_meeting_url;
+  # 3. Get information about the meetings with get_meetings and get_meeting_info;
+  # 4. 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:
-  # Author::    Joe Kinsella  (mailto:joe.kinsella@gmail.com)
-  # Copyright:: Copyright (c) 2010 Joe Kinsella
-  # License::   Distributes under same terms as Ruby
-  #
-  # Considerations about the returning hash:
-  # * The XML returned by BBB is converted to a Hash. See the desired method's documentation for examples.
-  # * Three values will *always* exist in the hash: :returncode (boolean), :messageKey (string) and :message (string)
+  # Important info about the data returned by the methods:
+  # * The XML returned by BBB is converted to a Hash. See individual method's documentation for examples.
+  # * Three values will *always* exist in the hash:
+  #   * :returncode (boolean)
+  #   * :messageKey (string)
+  #   * :message (string)
   # * Some of the values returned by BBB are converted to better represent the data. Some of these are listed
   #   bellow. They will *always* have the type informed:
   #   * :meetingID (string)
@@ -52,11 +42,11 @@ module BigBlueButton
     # salt::      Secret salt for this server
     # version::   API version: 0.7 (valid for 0.7, 0.71 and 0.71a)
     def initialize(url, salt, version='0.7', debug=false)
-      @supported_versions = ['0.7']
+      @supported_versions = ['0.7', '0.8']
       @url = url
       @salt = salt
       @debug = debug
-      @timeout = 2 # 2 seconds timeout for get requests
+      @timeout = 10 # default timeout for api requests
 
       @version = version || get_api_version
       unless @supported_versions.include?(@version)
@@ -66,74 +56,107 @@ module BigBlueButton
       puts "BigBlueButtonAPI: Using version #{@version}" if @debug
     end
 
-    # Returns the url used to join the meeting
-    # meeting_id::        Unique identifier for the meeting
-    # user_name::         Name of the user
-    # password::          Password for this meeting - used to set the user as moderator or attendee
-    # user_id::           Unique identifier for this user
-    # web_voice_conf::    Custom voice-extension for users using VoIP
-    def join_meeting_url(meeting_id, user_name, password,
-                         user_id = nil, web_voice_conf = nil)
-
-      params = { :meetingID => meeting_id, :password => password, :fullName => user_name,
-                 :userID => user_id, :webVoiceConf => web_voice_conf }
-      get_url(:join, params)
-    end
+
+    #
+    # API calls since 0.7
+    #
+
 
     # Creates a new meeting. Returns the hash with the response or
     # throws BigBlueButtonException on failure.
-    # meeting_name::        Name for the meeting
-    # meeting_id::          Unique identifier for the meeting
-    # moderator_password::  Moderator password
-    # attendee_password::   Attendee password
-    # welcome_message::     Welcome message to display in chat window
-    # dialin_number::       Dial in number for conference using a regular phone
-    # logout_url::          URL to return user to after exiting meeting
-    # voice_bridge::        Voice conference number
+    # meeting_name (string)::           Name for the meeting
+    # meeting_id (string, integer)::    Unique identifier for the meeting
+    # options (Hash)::                  Hash with optional parameters. The accepted parameters are:
+    #                                   moderatorPW (string, int), attendeePW (string, int), welcome (string),
+    #                                   dialNumber (int), logoutURL (string), maxParticipants (int),
+    #                                   voiceBridge (int), record (boolean), duration (int) and "meta" parameters
+    #                                   (usually strings). If a parameter passed in the hash is not supported it will
+    #                                   simply be discarded. For details about each see BBB API docs.
+    # modules (BigBlueButtonModules)::  Configuration for the modules. The modules are sent as an xml and the
+    #                                   request will use an HTTP POST instead of GET. Currently only the
+    #                                   "presentation" module is available. Only used for version > 0.8.
+    #                                   See usage examples below.
     #
-    # === Return examples (for 0.7)
+    # === Example
+    #
+    #   options = { :moderatorPW => "123", :attendeePW => "321", :welcome => "Welcome here!",
+    #               :dialNumber => 5190909090, :logoutURL => "http://mconf.org", :maxParticipants => 25,
+    #               :voiceBridge => 76543, :record => "true", :duration => 0, :meta_category => "Remote Class" }
+    #   create_meeting("My Meeting", "my-meeting", options)
+    #
+    # === Example with modules (see BigBlueButtonModules docs for more)
+    #
+    #   modules = BigBlueButton::BigBlueButtonModules.new
+    #   modules.add_presentation(:url, "http://www.samplepdf.com/sample.pdf")
+    #   modules.add_presentation(:url, "http://www.samplepdf.com/sample2.pdf")
+    #   modules.add_presentation(:file, "presentations/class01.ppt")
+    #   modules.add_presentation(:base64, "JVBERi0xLjQKJ....[clipped here]....0CiUlRU9GCg==", "first-class.pdf")
+    #   create_meeting("My Meeting", "my-meeting", nil, modules)
+    #
+    # === Example response for 0.7
     #
     # On successful creation:
     #
     #   {
-    #    :returncode=>true, :meetingID=>"bigbluebutton-api-ruby-test",
-    #    :attendeePW=>"1234", :moderatorPW=>"4321", :hasBeenForciblyEnded=>false,
-    #    :messageKey=>"", :message=>""
+    #    :returncode => true, :meetingID => "test",
+    #    :attendeePW => "1234", :moderatorPW => "4321", :hasBeenForciblyEnded => false,
+    #    :messageKey => "", :message => ""
     #   }
     #
     # Meeting that was forcibly ended:
     #
     #   {
-    #    :returncode=>true, :meetingID=>"bigbluebutton-api-ruby-test",
-    #    :attendeePW=>"1234", :moderatorPW=>"4321", :hasBeenForciblyEnded=>true,
-    #    :messageKey=>"duplicateWarning",
-    #    :message=>"This conference was already in existence and may currently be in progress."
+    #    :returncode => true, :meetingID => "test",
+    #    :attendeePW => "1234", :moderatorPW => "4321", :hasBeenForciblyEnded => true,
+    #    :messageKey => "duplicateWarning",
+    #    :message => "This conference was already in existence and may currently be in progress."
     #   }
     #
-    def create_meeting(meeting_name, meeting_id, moderator_password = nil, attendee_password = nil,
-                       welcome_message = nil, dial_number = nil, logout_url = nil,
-                       max_participants = nil, voice_bridge = nil)
-
-      params = { :name => meeting_name, :meetingID => meeting_id,
-                 :moderatorPW => moderator_password, :attendeePW => attendee_password,
-                 :welcome => welcome_message, :dialNumber => dial_number,
-                 :logoutURL => logout_url, :maxParticpants => max_participants,
-                 :voiceBridge => voice_bridge }
+    # === Example response for 0.8
+    #
+    #   {
+    #    :returncode => true, :meetingID => "Test", :createTime => 1308591802,
+    #    :attendeePW => "1234", :moderatorPW => "4321", :hasBeenForciblyEnded => false,
+    #    :messageKey => "", :message => ""
+    #   }
+    #
+    def create_meeting(meeting_name, meeting_id, options={}, modules=nil)
+      valid_options = [:moderatorPW, :attendeePW, :welcome, :maxParticipants,
+                       :dialNumber, :voiceBridge, :webVoice, :logoutURL]
+
+      selected_opt = options.clone
+      if @version >= "0.8"
+        # v0.8 added "record", "duration" and "meta_" parameters
+        valid_options += [:record, :duration]
+        selected_opt.reject!{ |k,v| !valid_options.include?(k) and !(k.to_s =~ /^meta_.*$/) }
+        selected_opt[:record] = selected_opt[:record].to_s if selected_opt.has_key?(:record)
+      else
+        selected_opt.reject!{ |k,v| !valid_options.include?(k) }
+      end
+      params = { :name => meeting_name, :meetingID => meeting_id }.merge(selected_opt)
 
-      response = send_api_request(:create, params)
+      # with modules we send a post request (only for >= 0.8)
+      if modules and @version >= "0.8"
+        response = send_api_request(:create, params, modules.to_xml)
+      else
+        response = send_api_request(:create, params)
+      end
 
       formatter = BigBlueButtonFormatter.new(response)
       formatter.to_string(:meetingID)
       formatter.to_string(:moderatorPW)
       formatter.to_string(:attendeePW)
       formatter.to_boolean(:hasBeenForciblyEnded)
+      if @version >= "0.8"
+        formatter.to_int(:createTime)
+      end
 
       response
     end
 
     # Ends an existing meeting. Throws BigBlueButtonException on failure.
-    # meeting_id::          Unique identifier for the meeting
-    # moderator_password::  Moderator password
+    # meeting_id (string, int)::          Unique identifier for the meeting
+    # moderator_password (string, int)::  Moderator password
     #
     # === Return examples (for 0.7)
     #
@@ -151,12 +174,29 @@ module BigBlueButton
 
     # Returns true or false as to whether meeting is open.  A meeting is
     # only open after at least one participant has joined.
-    # meeting_id::          Unique identifier for the meeting
+    # meeting_id (string, int)::          Unique identifier for the meeting
     def is_meeting_running?(meeting_id)
       hash = send_api_request(:isMeetingRunning, { :meetingID => meeting_id } )
       BigBlueButtonFormatter.new(hash).to_boolean(:running)
     end
 
+    # Returns the url used to join the meeting
+    # meeting_id (string, int)::   Unique identifier for the meeting
+    # user_name (string)::         Name of the user
+    # password (string)::          Password for this meeting - used to set the user as moderator or attendee
+    # options (Hash)::             Hash with optional parameters. The accepted parameters are:
+    #                              userID (string, int), webVoiceConf (string, int) and createTime (int).
+    #                              For details about each see BBB API docs.
+    def join_meeting_url(meeting_id, user_name, password, options={})
+      valid_options = [:userID, :webVoiceConf]
+      valid_options += [:createTime] if @version >= "0.8"
+      options.reject!{ |k,v| !valid_options.include?(k) }
+
+      params = { :meetingID => meeting_id, :password => password, :fullName => user_name }.merge(options)
+
+      get_url(:join, params)
+    end
+
     # Warning: As of this version of the gem, this call does not work
     # (instead of returning XML response, it should join the meeting).
     #
@@ -164,14 +204,19 @@ module BigBlueButton
     # directing the user's browser to moderator_url or attendee_url
     # (note: this will still be required however to actually use bbb).
     # Returns the URL a user can use to enter this meeting.
-    # meeting_id::        Unique identifier for the meeting
-    # user_name::         Name of the user
-    # password::          Moderator or attendee password for this meeting
-    # user_id::           Unique identifier for this user
-    # web_voice_conf::    Custom voice-extension for users using VoIP
-    def join_meeting(meeting_id, user_name, password, user_id = nil, web_voice_conf = nil)
-      params = { :meetingID => meeting_id, :password => password, :fullName => user_name,
-                 :userID => user_id, :webVoiceConf => web_voice_conf }
+    # meeting_id (string, int)::  Unique identifier for the meeting
+    # user_name (string)::        Name of the user
+    # password (string, int)::    Moderator or attendee password for this meeting
+    # options (Hash)::             Hash with optional parameters. The accepted parameters are:
+    #                              userID (string, int), webVoiceConf (string, int) and createTime (int).
+    #                              For details about each see BBB API docs.
+    def join_meeting(meeting_id, user_name, password, options={})
+      valid_options = [:userID, :webVoiceConf]
+      valid_options += [:createTime] if @version >= "0.8"
+      options.reject!{ |k,v| !valid_options.include?(k) }
+
+      params = { :meetingID => meeting_id, :password => password, :fullName => user_name }.merge(options)
+
       send_api_request(:join, params)
     end
 
@@ -179,10 +224,10 @@ module BigBlueButton
     # See the API documentation for details on the return XML
     # (http://code.google.com/p/bigbluebutton/wiki/API).
     #
-    # meeting_id::  Unique identifier for the meeting
-    # password::    Moderator password for this meeting
+    # meeting_id (string, int)::  Unique identifier for the meeting
+    # password (string, int)::    Moderator password for this meeting
     #
-    # === Return examples (for 0.7)
+    # === Example responses for 0.7
     #
     # With attendees:
     #
@@ -205,12 +250,23 @@ module BigBlueButton
     #    :attendees=>[], :messageKey=>"", :message=>""
     #   }
     #
+    # === Example responses for 0.8
+    #
+    #   {
+    #     :returncode => true, :meetingName => "test", :meetingID => "test", :createTime => 1321906390524,
+    #     :voiceBridge => 72194, :attendeePW => "1234", :moderatorPW => "4321", :running => false, :recording => false,
+    #     :hasBeenForciblyEnded => false, :startTime => nil, :endTime => nil, :participantCount => 0, :maxUsers => 9,
+    #     :moderatorCount => 0, :attendees => [],
+    #     :metadata => { :two => "TWO", :one => "one" },
+    #     :messageKey => "", :message => ""
+    #   }
+    #
     def get_meeting_info(meeting_id, password)
       response = send_api_request(:getMeetingInfo, { :meetingID => meeting_id, :password => password } )
 
       formatter = BigBlueButtonFormatter.new(response)
       formatter.flatten_objects(:attendees, :attendee)
-      response[:attendees].each { |a| formatter.format_attendee(a) }
+      response[:attendees].each { |a| BigBlueButtonFormatter.format_attendee(a) }
 
       formatter.to_string(:meetingID)
       formatter.to_string(:moderatorPW)
@@ -219,6 +275,15 @@ module BigBlueButton
       formatter.to_boolean(:running)
       formatter.to_datetime(:startTime)
       formatter.to_datetime(:endTime)
+      formatter.to_int(:participantCount)
+      formatter.to_int(:moderatorCount)
+      if @version >= "0.8"
+        formatter.to_string(:meetingName)
+        formatter.to_int(:maxUsers)
+        formatter.to_int(:voiceBridge)
+        formatter.to_int(:createTime)
+        formatter.to_boolean(:recording)
+      end
 
       response
     end
@@ -226,7 +291,7 @@ module BigBlueButton
     # Returns a hash object containing information about the meetings currently existent in the BBB
     # server, either they are running or not.
     #
-    # === Return examples (for 0.7)
+    # === Example responses for 0.7
     #
     # Server with one or more meetings:
     #
@@ -247,7 +312,7 @@ module BigBlueButton
 
       formatter = BigBlueButtonFormatter.new(response)
       formatter.flatten_objects(:meetings, :meeting)
-      response[:meetings].each { |m| formatter.format_meeting(m) }
+      response[:meetings].each { |m| BigBlueButtonFormatter.format_meeting(m) }
       response
     end
 
@@ -259,13 +324,119 @@ module BigBlueButton
       response[:returncode] ? response[:version].to_s : ""
     end
 
-    # Make a simple request to the server to test the connection
+
+
+    #
+    # API calls since 0.8
+    #
+
+    # Retrieves the recordings that are available for playback for a given meetingID (or set of meeting IDs).
+    # options (Hash)::                Hash with optional parameters. The accepted parameters are:
+    #                                 :meetingID (string, Array). For details about each see BBB API docs.
+    #                                 Any of the following values are accepted for :meetingID :
+    #                                   :meetingID => "id1"
+    #                                   :meetingID => "id1,id2,id3"
+    #                                   :meetingID => ["id1"]
+    #                                   :meetingID => ["id1", "id2", "id3"]
+    #
+    # === Example responses
+    # TODO: this example is not accurate yet
+    #
+    #   { :returncode => true,
+    #     :recordings => [
+    #       {
+    #         :recordID => "7f5745a08b24fa27551e7a065849dda3ce65dd32-1321618219268", :meetingID=>"bd1811beecd20f24314819a52ec202bf446ab94b",
+    #         :name => "Evening Class1", :published => true,
+    #         :startTime => #<DateTime: 2011-11-18T12:10:23+00:00 (212188378223/86400,0/1,2299161)>,
+    #         :endTime => #<DateTime: 2011-11-18T12:12:25+00:00 (42437675669/17280,0/1,2299161)>,
+    #         :metadata => { :course => "Fundamentals Of JAVA",
+    #                        :description => "List of recordings",
+    #                        :activity => "Evening Class1" },
+    #         :playback => {
+    #           :format => {
+    #             :type => "slides",
+    #             :url => "http://test-install.blindsidenetworks.com/playback/slides/playback.html?meetingId=7f5745a08b24fa27551e7a065849dda3ce65dd32-1321618219268",
+    #             :length=>3
+    #           }
+    #         }
+    #       },
+    #       { :recordID => "183f0bf3a0982a127bdb8161-13085974450", :meetingID => "CS102",
+    #         ...
+    #         ...
+    #       }
+    #     ]
+    #   }
+    #
+    def get_recordings(options={})
+      raise BigBlueButtonException.new("Method only supported for versions >= 0.8") if @version < "0.8"
+
+      valid_options = [:meetingID]
+      options.reject!{ |k,v| !valid_options.include?(k) }
+
+      # ["id1", "id2", "id3"] becomes "id1,id2,id3"
+      if options.has_key?(:meetingID)
+        options[:meetingID] = options[:meetingID].join(",") if options[:meetingID].instance_of?(Array)
+      end
+
+      response = send_api_request(:getRecordings, options)
+
+      formatter = BigBlueButtonFormatter.new(response)
+      formatter.flatten_objects(:recordings, :recording)
+      response[:recordings].each { |r| BigBlueButtonFormatter.format_recording(r) }
+      response
+    end
+
+    # Publish and unpublish recordings for a given recordID (or set of record IDs).
+    # recordIDs (string, Array)::  ID or IDs of the target recordings.
+    #                              Any of the following values are accepted:
+    #                                "id1"
+    #                                "id1,id2,id3"
+    #                                ["id1"]
+    #                                ["id1", "id2", "id3"]
+    # publish (boolean)::          Publish or unpublish the recordings?
+    #
+    # === Example responses
+    #
+    #   { :returncode => true, :published => true }
+    #
+    def publish_recordings(recordIDs, publish)
+      raise BigBlueButtonException.new("Method only supported for versions >= 0.8") if @version < "0.8"
+
+      recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
+      response = send_api_request(:publishRecordings, { :recordID => recordIDs, :publish => publish.to_s })
+    end
+
+    # Delete one or more recordings for a given recordID (or set of record IDs).
+    # recordIDs (string, Array)::  ID or IDs of the target recordings.
+    #                              Any of the following values are accepted:
+    #                                "id1"
+    #                                "id1,id2,id3"
+    #                                ["id1"]
+    #                                ["id1", "id2", "id3"]
+    #
+    # === Example responses
+    #
+    #   { :returncode => true, :deleted => true }
+    #
+    def delete_recordings(recordIDs)
+      raise BigBlueButtonException.new("Method only supported for versions >= 0.8") if @version < "0.8"
+
+      recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
+      response = send_api_request(:deleteRecordings, { :recordID => recordIDs })
+    end
+
+
+    #
+    # Helper functions
+    #
+
+    # Make a simple request to the server to test the connection.
     def test_connection
       response = send_api_request(:index)
       response[:returncode]
     end
 
-    # API's are equal if all the following attributes are equal
+    # API's are equal if all the following attributes are equal.
     def ==(other)
       r = true
       [:url, :supported_versions, :salt, :version, :debug].each do |param|
@@ -274,11 +445,20 @@ module BigBlueButton
       r
     end
 
+    # Returns the HTTP response object returned in the last API call.
     def last_http_response
       @http_response
     end
 
-    def get_url(method, data={})
+    # Returns the XML returned in the last API call.
+    def last_xml_response
+      @xml_response
+    end
+
+    # Formats an API call URL for the method 'method' using the parameters in 'params'.
+    # method (symbol)::  The API method to be called (:create, :index, :join, and others)
+    # params (Hash)::    The parameters to be passed in the URL
+    def get_url(method, params={})
       if method == :index
         return @url
       end
@@ -286,38 +466,50 @@ module BigBlueButton
       url = "#{@url}/#{method}?"
 
       # stringify and escape all params
-      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("&")
+      params.delete_if { |k, v| v.nil? } unless params.nil?
+      params_string = ""
+      params_string = params.map{ |k,v| "#{k}=" + CGI::escape(v.to_s) unless k.nil? || v.nil? }.join("&")
 
       # checksum calc
-      checksum_param = params + @salt
+      checksum_param = params_string + @salt
       checksum_param = method.to_s + checksum_param
       checksum = Digest::SHA1.hexdigest(checksum_param)
 
       # final url
-      url += "#{params}&" unless params.empty?
+      url += "#{params_string}&" unless params_string.empty?
       url += "checksum=#{checksum}"
     end
 
-    def send_api_request(method, data = {})
-      url = get_url(method, data)
-
-      @http_response = send_request(url)
+    # Performs an API call.
+    #
+    # Throws a BigBlueButtonException if something goes wrong (e.g. server offline).
+    # Also throws an exception of the request was not successful (i.e. returncode == FAILED).
+    #
+    # Only formats the standard values in the response (the ones that exist in all responses).
+    #
+    # method (symbol)::  The API method to be called (:create, :index, :join, and others)
+    # params (Hash)::    The parameters to be passed in the URL
+    # data (string)::    Data to be sent with the request. If set, the request will use an HTTP
+    #                    POST instead of a GET and the data will be sent in the request body.
+    def send_api_request(method, params={}, data=nil)
+      url = get_url(method, params)
+
+      @http_response = send_request(url, data)
       return { } if @http_response.body.empty?
 
       # 'Hashify' the XML
-      hash = Hash.from_xml(@http_response.body)
+      @xml_response = @http_response.body
+      hash = Hash.from_xml(@xml_response)
 
       # simple validation of the xml body
-      unless hash.has_key?(:response) and hash[:response].has_key?(:returncode)
+      unless hash.has_key?(:returncode)
         raise BigBlueButtonException.new("Invalid response body. Is the API URL correct? \"#{@url}\", version #{@version}")
       end
 
       # default cleanup in the response
       hash = BigBlueButtonFormatter.new(hash).default_formatting
 
-      # all responses should have a returncode
+      # if the return code is an error generates an exception
       unless hash[:returncode]
         exception = BigBlueButtonException.new(hash[:message])
         exception.key = hash.has_key?(:messageKey) ? hash[:messageKey] : ""
@@ -329,20 +521,32 @@ module BigBlueButton
 
     protected
 
-    def send_request(url)
+    # :nodoc:
+    # If data is set, uses a POST with data in the request body
+    # Otherwise uses GET
+    def send_request(url, data=nil)
       begin
         puts "BigBlueButtonAPI: URL request = #{url}" if @debug
         url_parsed = URI.parse(url)
         http = Net::HTTP.new(url_parsed.host, url_parsed.port)
         http.open_timeout = @timeout
         http.read_timeout = @timeout
-        response = http.get(url_parsed.request_uri)
+        if data.nil?
+          response = http.get(url_parsed.request_uri)
+        else
+          puts "BigBlueButtonAPI: Sending as a POST request with data.size = #{data.size}" if @debug
+          opts = { 'Content-Type' => 'text/xml' }
+          response = http.post(url_parsed.request_uri, data, opts)
+        end
         puts "BigBlueButtonAPI: URL response = #{response.body}" if @debug
+
       rescue TimeoutError => error
         raise BigBlueButtonException.new("Timeout error. Your server is probably down: \"#{@url}\"")
+
       rescue Exception => error
         raise BigBlueButtonException.new("Connection error. Your URL is probably incorrect: \"#{@url}\"")
       end
+
       response
     end