bigbluebutton-api-ruby 0.0.11 → 0.1.0.rc1

data/lib/bigbluebutton_formatter.rb

@@ -5,12 +5,25 @@ module BigBlueButton
     attr_accessor :hash
 
     def initialize(hash)
-      @hash = hash
+      @hash = hash || {}
     end
 
     # converts a value in the @hash to boolean
     def to_boolean(key)
-      @hash[key] = @hash[key].downcase == "true"
+      unless @hash.has_key?(key)
+        false
+      else
+        @hash[key] = @hash[key].downcase == "true"
+      end
+    end
+
+    # converts a value in the @hash to int
+    def to_int(key)
+      unless @hash.has_key?(key)
+        0
+      else
+        @hash[key] = @hash[key].to_i
+      end
     end
 
     # converts a value in the @hash to string
@@ -20,14 +33,51 @@ module BigBlueButton
 
     # converts a value in the @hash to DateTime
     def to_datetime(key)
-      @hash[key] = @hash[key].downcase == "null" ? nil : DateTime.parse(@hash[key])
+      unless @hash.has_key?(key) and @hash[key]
+        nil
+      else
+        # BBB >= 0.8 uses the unix epoch for all time related values
+        # older versions use strings
+
+        # a number but in a String class
+        if (@hash[key].class == String && @hash[key].to_i.to_s == @hash[key])
+          value = @hash[key].to_i
+        else
+          value = @hash[key]
+        end
+
+        if value.is_a?(Numeric)
+          result = value == 0 ? nil : DateTime.parse(Time.at(value/1000.0).to_s)
+        else
+          if value.downcase == "null"
+            result = nil
+          else
+            result = DateTime.parse(value)
+          end
+        end
+
+        @hash[key] = result
+      end
+    end
+
+    # converts a value in the @hash to a symbol
+    def to_sym(key)
+      unless @hash.has_key?(key)
+        ""
+      else
+        if @hash[key].instance_of?(Symbol)
+          @hash[key]
+        elsif @hash[key].empty?
+          ""
+        else
+          @hash[key] = @hash[key].downcase.to_sym
+        end
+      end
     end
 
     # Default formatting for all responses given by a BBB server
     def default_formatting
-
-      # remove the "response" node
-      response = Hash[@hash[:response]].inject({}){|h,(k,v)| h[k] = v; h}
+      response = @hash
 
       # Adjust some values. There will always be a returncode, a message and a messageKey in the hash.
       response[:returncode] = response[:returncode].downcase == "success"                              # true instead of "SUCCESS"
@@ -37,25 +87,61 @@ module BigBlueButton
       @hash = response
     end
 
-    # default formatting for a meeting hash
-    def format_meeting(meeting)
-      meeting[:meetingID] = meeting[:meetingID].to_s
-      meeting[:moderatorPW] = meeting[:moderatorPW].to_s
-      meeting[:attendeePW] = meeting[:attendeePW].to_s
-      meeting[:hasBeenForciblyEnded] = meeting[:hasBeenForciblyEnded].downcase == "true"
-      meeting[:running] = meeting[:running].downcase == "true"
+    # Default formatting for a meeting hash
+    def self.format_meeting(meeting)
+      f = BigBlueButtonFormatter.new(meeting)
+      f.to_string(:meetingID)
+      f.to_string(:moderatorPW)
+      f.to_string(:attendeePW)
+      f.to_boolean(:hasBeenForciblyEnded)
+      f.to_boolean(:running)
+      f.to_int(:createTime) if meeting.has_key?(:createTime)
       meeting
     end
 
-    # default formatting for an attendee hash
-    def format_attendee(attendee)
-      attendee[:userID] = attendee[:userID].to_s
-      attendee[:role] = attendee[:role].downcase.to_sym
+    # Default formatting for an attendee hash
+    def self.format_attendee(attendee)
+      f = BigBlueButtonFormatter.new(attendee)
+      f.to_string(:userID)
+      f.to_sym(:role)
       attendee
     end
 
-    # simplifies the hash making a node e.g. :attendee with an array with all attendees
-    # TODO: comments with the expected @hash at this point
+    # Default formatting for a recording hash
+    def self.format_recording(rec)
+      f = BigBlueButtonFormatter.new(rec)
+      f.to_string(:recordID)
+      f.to_string(:meetingID)
+      f.to_string(:name)
+      f.to_boolean(:published)
+      f.to_datetime(:startTime)
+      f.to_datetime(:endTime)
+      rec
+    end
+
+    # Simplifies the XML-styled hash node 'first'. Its value will then always be an Array.
+    #
+    # For example, if the current hash is:
+    #   { :name => "Test", :attendees => { :attendee => [ { :name => "attendee1" }, { :name => "attendee2" } ] } }
+    #
+    # Calling:
+    #  flatten_objects(:attendees, :attendee)
+    #
+    # The hash will become:
+    #   { :name => "Test", :attendees => [ { :name => "attendee1" }, { :name => "attendee2" } ] }
+    #
+    # Other examples:
+    #
+    # Hash:
+    #   { :name => "Test", :attendees => {} }
+    # Result:
+    #   { :name => "Test", :attendees => [] }
+    #
+    # Hash:
+    #   { :name => "Test", :attendees => { :attendee => { :name => "attendee1" } } }
+    # Result:
+    #   { :name => "Test", :attendees => [ { :name => "attendee1" } ] }
+    #
     def flatten_objects(first, second)
       if @hash[first].empty?
         collection = []

data/lib/bigbluebutton_modules.rb

@@ -0,0 +1,92 @@
+require "base64"
+
+module BigBlueButton
+
+  # An object to store the modules configuration to be passed in
+  # BigBlueButtonApi#create_meeting().
+  #
+  # === Usage example:
+  #
+  #   modules = BigBlueButton::BigBlueButtonModules.new
+  #
+  #   # adds presentations by URL
+  #   modules.add_presentation(:url, "http://www.samplepdf.com/sample.pdf")
+  #   modules.add_presentation(:url, "http://www.samplepdf.com/sample2.pdf")
+  #
+  #   # adds presentations from a local file
+  #   # the file will be opened and encoded in base64
+  #   modules.add_presentation(:file, "presentations/class01.ppt")
+  #
+  #   # adds a base64 encoded presentation
+  #   modules.add_presentation(:base64, "JVBERi0xLjQKJ....[clipped here]....0CiUlRU9GCg==", "first-class.pdf")
+  #
+  class BigBlueButtonModules
+
+    attr_accessor :presentation_urls
+    attr_accessor :presentation_files
+    attr_accessor :presentation_base64s
+
+    def initialize
+      @presentation_urls = []
+      @presentation_files = []
+      @presentation_base64s = []
+    end
+
+    def add_presentation(type, value, name=nil)
+      case type
+      when :url
+        @presentation_urls.push(value)
+      when :file
+        @presentation_files.push(value)
+      when :base64
+        @presentation_base64s.push([name, value])
+      end
+    end
+
+    def to_xml
+      unless has_presentations?
+        ""
+      else
+        xml  = xml_header
+        xml << presentations_to_xml
+        xml << xml_footer
+      end
+    end
+
+    private
+
+    def has_presentations?
+      !@presentation_urls.empty? or
+        !@presentation_files.empty? or
+        !@presentation_base64s.empty?
+    end
+
+    def xml_header
+      "<?xml version=\"1.0\" encoding=\"UTF-8\"?><modules>"
+    end
+
+    def xml_footer
+      "</modules>"
+    end
+
+    def presentations_to_xml
+      xml = "<module name=\"presentation\">"
+      @presentation_urls.each { |url| xml << "<document url=\"#{url}\" />" }
+      @presentation_base64s.each do |name, data|
+        xml << "<document name=\"#{name}\">"
+        xml << data
+        xml << "</document>"
+      end
+      @presentation_files.each do |filename|
+        xml << "<document name=\"#{File.basename(filename)}\">"
+        File.open(filename, "r") do |file|
+          xml << Base64.encode64(file.read)
+        end
+        xml << "</document>"
+      end
+      xml << "</module>"
+    end
+
+  end
+
+end

data/lib/hash_to_xml.rb

@@ -1,62 +1,33 @@
-# Code from: https://gist.github.com/335286
-# USAGE: Hash.from_xml:(YOUR_XML_STRING)
-# modified from http://stackoverflow.com/questions/1230741/convert-a-nokogiri-document-to-a-ruby-hash/1231297#1231297
+require 'xmlsimple'
 
 class Hash
   class << self
-    def from_xml(xml_io) 
+    def from_xml(xml_io)
       begin
-        result = Nokogiri::XML(xml_io)
-        return { result.root.name.to_sym => xml_node_to_hash(result.root)} 
+        # we'll not use 'KeyToSymbol' because it doesn't symbolize the keys for node attributes
+        opts = { 'ForceArray' => false, 'ForceContent' => false } #
+        hash = XmlSimple.xml_in(xml_io, opts)
+        return symbolize_keys(hash)
       rescue Exception => e
         raise BigBlueButton::BigBlueButtonException.new("Impossible to convert XML to hash. Error: #{e.message}")
       end
-    end 
-
-    def xml_node_to_hash(node) 
-      # If we are at the root of the document, start the hash 
-      if node.element?
-        result_hash = {}
-        if node.attributes != {}
-          result_hash[:attributes] = {}
-          node.attributes.keys.each do |key|
-            result_hash[:attributes][node.attributes[key].name.to_sym] = prepare(node.attributes[key].value)
-          end
-        end
-        if node.children.size > 0
-          node.children.each do |child| 
-            result = xml_node_to_hash(child) 
-
-            if child.name == "text"
-              unless child.next_sibling || child.previous_sibling
-                return prepare(result)
-              end
-            elsif result_hash[child.name.to_sym]
-              if result_hash[child.name.to_sym].is_a?(Object::Array)
-                result_hash[child.name.to_sym] << prepare(result)
-              else
-                result_hash[child.name.to_sym] = [result_hash[child.name.to_sym]] << prepare(result)
-              end
-            else 
-              result_hash[child.name.to_sym] = prepare(result)
-            end
-          end
-
-          return result_hash 
-        else 
-          return result_hash
-        end 
-      else 
-        return prepare(node.content.to_s) 
-      end 
-    end          
+    end
 
-    def prepare(data)
-      (data.class == String && data.to_i.to_s == data) ? data.to_i : data
+    def symbolize_keys(arg)
+      case arg
+      when Array
+        arg.map {  |elem| symbolize_keys elem }
+      when Hash
+        Hash[
+             arg.map {  |key, value|
+               k = key.is_a?(String) ? key.to_sym : key
+               v = symbolize_keys value
+               [k,v]
+             }]
+      else
+        arg
+      end
     end
-  end
-  
-  def to_struct(struct_name)
-      Struct.new(struct_name,*keys).new(*values)
+
   end
 end

data/spec/bigbluebutton_api_0.8_spec.rb

@@ -0,0 +1,273 @@
+require 'spec_helper'
+
+# Tests for BBB API version 0.8
+describe BigBlueButton::BigBlueButtonApi do
+
+  # default variables and API object for all tests
+  let(:url) { "http://server.com" }
+  let(:salt) { "1234567890abcdefghijkl" }
+  let(:version) { "0.8" }
+  let(:debug) { false }
+  let(:api) { BigBlueButton::BigBlueButtonApi.new(url, salt, version, debug) }
+
+  describe "#create_meeting" do
+
+    context "without modules" do
+      let(:req_params) {
+        { :name => "name", :meetingID => "meeting-id", :moderatorPW => "mp", :attendeePW => "ap",
+          :welcome => "Welcome!", :dialNumber => 12345678, :logoutURL => "http://example.com",
+          :maxParticipants => 25, :voiceBridge => 12345, :record => "true", :duration => 20,
+          :meta_1 => "meta1", :meta_2 => "meta2" }
+      }
+      let(:req_response) {
+        { :meetingID => 123, :moderatorPW => 111, :attendeePW => 222, :hasBeenForciblyEnded => "FALSE", :createTime => "123123123" }
+      }
+      let(:final_response) {
+        { :meetingID => "123", :moderatorPW => "111", :attendeePW => "222", :hasBeenForciblyEnded => false, :createTime => 123123123 }
+      }
+
+      before { api.should_receive(:send_api_request).with(:create, req_params).and_return(req_response) }
+      subject {
+        options = { :moderatorPW => "mp", :attendeePW => "ap", :welcome => "Welcome!", :dialNumber => 12345678,
+          :logoutURL => "http://example.com", :maxParticipants => 25, :voiceBridge => 12345, :record => true,
+          :duration => 20, :meta_1 => "meta1", :meta_2 => "meta2" }
+        api.create_meeting("name", "meeting-id", options)
+      }
+      it { subject.should == final_response }
+    end
+
+    context "with modules" do
+      let(:req_params) {
+        { :name => "name", :meetingID => "meeting-id", :moderatorPW => "mp", :attendeePW => "ap" }
+      }
+      let(:req_response) {
+        { :meetingID => 123, :moderatorPW => 111, :attendeePW => 222, :hasBeenForciblyEnded => "FALSE", :createTime => "123123123" }
+      }
+      let(:final_response) {
+        { :meetingID => "123", :moderatorPW => "111", :attendeePW => "222", :hasBeenForciblyEnded => false, :createTime => 123123123 }
+      }
+      let(:modules) {
+        m = BigBlueButton::BigBlueButtonModules.new
+        m.add_presentation(:url, "http://www.samplepdf.com/sample.pdf")
+        m.add_presentation(:url, "http://www.samplepdf.com/sample2.pdf")
+        m.add_presentation(:base64, "JVBERi0xLjQKJ....[clipped here]....0CiUlRU9GCg==", "first-class.pdf")
+        m
+      }
+
+      before {
+        api.should_receive(:send_api_request).with(:create, req_params, modules.to_xml).
+          and_return(req_response)
+      }
+      subject {
+        options = { :moderatorPW => "mp", :attendeePW => "ap" }
+        api.create_meeting("name", "meeting-id", options, modules)
+      }
+      it { subject.should == final_response }
+    end
+  end
+
+  describe "#join_meeting_url" do
+    let(:params) {
+      { :meetingID => "meeting-id", :password => "pw", :fullName => "Name",
+        :userID => "id123", :webVoiceConf => 12345678, :createTime => 9876543 }
+    }
+
+    before { api.should_receive(:get_url).with(:join, params).and_return("test-url") }
+    it {
+      options = { :userID => "id123", :webVoiceConf => 12345678, :createTime => 9876543 }
+      api.join_meeting_url("meeting-id", "Name", "pw", options).should == "test-url"
+    }
+  end
+
+  describe "#join_meeting" do
+    let(:params) {
+      { :meetingID => "meeting-id", :password => "pw", :fullName => "Name",
+        :userID => "id123", :webVoiceConf => 12345678, :createTime => 9876543 }
+    }
+
+    before { api.should_receive(:send_api_request).with(:join, params).and_return("join-return") }
+    it {
+      options = { :userID => "id123", :webVoiceConf => 12345678, :createTime => 9876543 }
+      api.join_meeting("meeting-id", "Name", "pw", options).should == "join-return"
+    }
+  end
+
+  describe "#get_recordings" do
+    let(:recording1) { { :recordID => "id1", :meetindID => "meeting-id" } } # simplified "recording" node in the response
+    let(:recording2) { { :recordID => "id2", :meetindID => "meeting-id" } }
+    let(:response) {
+      { :returncode => true, :recordings => { :recording => [ recording1, recording2 ] }, :messageKey => "mkey", :message => "m" }
+    }
+    let(:flattened_response) {
+      { :returncode => true, :recordings => [ recording1, recording2 ], :messageKey => "mkey", :message => "m" }
+    } # hash *after* the flatten_objects call
+
+    context "only supported for >= 0.8" do
+      let(:api) { BigBlueButton::BigBlueButtonApi.new(url, salt, "0.7", debug) }
+      it { expect { api.get_recordings }.to raise_error(BigBlueButton::BigBlueButtonException) }
+    end
+
+    context "discards invalid options" do
+      let(:req_params) { { :meetingID => "meeting-id" } }
+      before { api.should_receive(:send_api_request).with(:getRecordings, req_params).and_return(response) }
+      it { api.get_recordings({ :meetingID => "meeting-id", :invalidParam1 => "1" }) }
+    end
+
+    context "without meeting ID" do
+      before { api.should_receive(:send_api_request).with(:getRecordings, {}).and_return(response) }
+      it { api.get_recordings.should == response }
+    end
+
+    context "with one meeting ID" do
+      context "in an array" do
+        let(:options) { { :meetingID => ["meeting-id"] } }
+        let(:req_params) { { :meetingID => "meeting-id" } }
+        before { api.should_receive(:send_api_request).with(:getRecordings, req_params).and_return(response) }
+        it { api.get_recordings(options).should == response }
+      end
+
+      context "in a string" do
+        let(:options) { { :meetingID => "meeting-id" } }
+        let(:req_params) { { :meetingID => "meeting-id" } }
+        before { api.should_receive(:send_api_request).with(:getRecordings, req_params).and_return(response) }
+        it { api.get_recordings(options).should == response }
+      end
+    end
+
+    context "with several meeting IDs" do
+      context "in an array" do
+        let(:options) { { :meetingID => ["meeting-id-1", "meeting-id-2"] } }
+        let(:req_params) { { :meetingID => "meeting-id-1,meeting-id-2" } }
+        before { api.should_receive(:send_api_request).with(:getRecordings, req_params).and_return(response) }
+        it { api.get_recordings(options).should == response }
+      end
+
+      context "in a string" do
+        let(:options) { { :meetingID => "meeting-id-1,meeting-id-2" } }
+        let(:req_params) { { :meetingID => "meeting-id-1,meeting-id-2" } }
+        before { api.should_receive(:send_api_request).with(:getRecordings, req_params).and_return(response) }
+        it { api.get_recordings(options).should == response }
+      end
+    end
+
+    context "formats the response" do
+      before {
+        api.should_receive(:send_api_request).with(:getRecordings, anything).and_return(flattened_response)
+        formatter_mock = mock(BigBlueButton::BigBlueButtonFormatter)
+        formatter_mock.should_receive(:flatten_objects).with(:recordings, :recording)
+        BigBlueButton::BigBlueButtonFormatter.should_receive(:format_recording).with(recording1)
+        BigBlueButton::BigBlueButtonFormatter.should_receive(:format_recording).with(recording2)
+        BigBlueButton::BigBlueButtonFormatter.should_receive(:new).and_return(formatter_mock)
+      }
+      it { api.get_recordings }
+    end
+  end
+
+  describe "#publish_recordings" do
+    context "only supported for >= 0.8" do
+      let(:api) { BigBlueButton::BigBlueButtonApi.new(url, salt, "0.7", debug) }
+      it { expect { api.publish_recordings("id", true) }.to raise_error(BigBlueButton::BigBlueButtonException) }
+    end
+
+    context "publish is converted to string" do
+      let(:recordIDs) { "any" }
+      let(:req_params) { { :publish => "false", :recordID => "any" } }
+      before { api.should_receive(:send_api_request).with(:publishRecordings, req_params) }
+      it { api.publish_recordings(recordIDs, false) }
+    end
+
+    context "with one recording ID" do
+      context "in an array" do
+        let(:recordIDs) { ["id-1"] }
+        let(:req_params) { { :publish => "true", :recordID => "id-1" } }
+        before { api.should_receive(:send_api_request).with(:publishRecordings, req_params) }
+        it { api.publish_recordings(recordIDs, true) }
+      end
+
+      context "in a string" do
+        let(:recordIDs) { "id-1" }
+        let(:req_params) { { :publish => "true", :recordID => "id-1" } }
+        before { api.should_receive(:send_api_request).with(:publishRecordings, req_params) }
+        it { api.publish_recordings(recordIDs, true) }
+      end
+    end
+
+    context "with several recording IDs" do
+      context "in an array" do
+        let(:recordIDs) { ["id-1", "id-2"] }
+        let(:req_params) { { :publish => "true", :recordID => "id-1,id-2" } }
+        before { api.should_receive(:send_api_request).with(:publishRecordings, req_params) }
+        it { api.publish_recordings(recordIDs, true) }
+      end
+
+      context "in a string" do
+        let(:recordIDs) { "id-1,id-2,id-3" }
+        let(:req_params) { { :publish => "true", :recordID => "id-1,id-2,id-3" } }
+        before { api.should_receive(:send_api_request).with(:publishRecordings, req_params) }
+        it { api.publish_recordings(recordIDs, true) }
+      end
+    end
+  end
+
+  describe "#delete_recordings" do
+    context "only supported for >= 0.8" do
+      let(:api) { BigBlueButton::BigBlueButtonApi.new(url, salt, "0.7", debug) }
+      it { expect { api.delete_recordings("id") }.to raise_error(BigBlueButton::BigBlueButtonException) }
+    end
+
+    context "with one recording ID" do
+      context "in an array" do
+        let(:recordIDs) { ["id-1"] }
+        let(:req_params) { { :recordID => "id-1" } }
+        before { api.should_receive(:send_api_request).with(:deleteRecordings, req_params) }
+        it { api.delete_recordings(recordIDs) }
+      end
+
+      context "in a string" do
+        let(:recordIDs) { "id-1" }
+        let(:req_params) { { :recordID => "id-1" } }
+        before { api.should_receive(:send_api_request).with(:deleteRecordings, req_params) }
+        it { api.delete_recordings(recordIDs) }
+      end
+    end
+
+    context "with several recording IDs" do
+      context "in an array" do
+        let(:recordIDs) { ["id-1", "id-2"] }
+        let(:req_params) { { :recordID => "id-1,id-2" } }
+        before { api.should_receive(:send_api_request).with(:deleteRecordings, req_params) }
+        it { api.delete_recordings(recordIDs) }
+      end
+
+      context "in a string" do
+        let(:recordIDs) { "id-1,id-2,id-3" }
+        let(:req_params) { { :recordID => "id-1,id-2,id-3" } }
+        before { api.should_receive(:send_api_request).with(:deleteRecordings, req_params) }
+        it { api.delete_recordings(recordIDs) }
+      end
+    end
+  end
+
+  describe "#get_meeting_info" do
+    let(:params) { { :meetingID => "meeting-id", :password => "password" } }
+
+    # new values were added in the response in 0.8 (we'll only test these values):
+    #   meetingName, participantCount, maxUsers, voiceBridge, recording, metadata
+    let(:response) {
+      { :meetingName => 123, :maxUsers => "100", :voiceBridge => "12341234",
+        :createTime => "123123123", :attendees => { :attendee => [ ] },
+        :messageKey => "mkey", :message => "m", :recording => "false", :meta_1 => "abc", :meta_2 => "2" }
+    }
+
+    before { api.should_receive(:send_api_request).with(:getMeetingInfo, params).and_return(response) }
+    subject { api.get_meeting_info("meeting-id", "password") }
+    it { subject[:meetingName].should == "123" }
+    it { subject[:maxUsers].should == 100 }
+    it { subject[:voiceBridge].should == 12341234 }
+    it { subject[:createTime].should == 123123123 }
+    it { subject[:recording].should == false }
+    it { subject[:meta_1].should == "abc" }
+    it { subject[:meta_2].should == "2" }
+  end
+
+end