bigbluebutton-api-ruby 1.3.0 → 1.8.0

data/lib/bigbluebutton_api.rb

@@ -9,10 +9,11 @@ require 'bigbluebutton_formatter'
 require 'bigbluebutton_modules'
 require 'bigbluebutton_config_xml'
 require 'bigbluebutton_config_layout'
+require 'logger'
 
 module BigBlueButton
 
-  # This class provides access to the BigBlueButton API. For more details see README.rdoc.
+  # This class provides access to the BigBlueButton API. For more details see README.
   #
   # Sample usage of the API is as follows:
   # 1. Create a meeting with create_meeting;
@@ -44,14 +45,14 @@ module BigBlueButton
     # URL to a BigBlueButton server (e.g. http://demo.bigbluebutton.org/bigbluebutton/api)
     attr_accessor :url
 
-    # Secret salt for this server
-    attr_accessor :salt
+    # Shared secret for this server
+    attr_accessor :secret
 
     # API version e.g. 0.81
     attr_accessor :version
 
-    # Flag to turn on/off debug mode
-    attr_accessor :debug
+    # logger to log reponses and infos
+    attr_accessor :logger
 
     # Maximum wait time for HTTP requests (secs)
     attr_accessor :timeout
@@ -65,22 +66,27 @@ module BigBlueButton
 
     # Initializes an instance
     # url::       URL to a BigBlueButton server (e.g. http://demo.bigbluebutton.org/bigbluebutton/api)
-    # salt::      Secret salt for this server
+    # secret::    Shared secret for this server
     # version::   API version e.g. 0.81
-    def initialize(url, salt, version='0.81', debug=false)
-      @supported_versions = ['0.8', '0.81']
+    def initialize(url, secret, version=nil, logger=nil)
+      @supported_versions = ['0.8', '0.81', '0.9', '1.0']
       @url = url
-      @salt = salt
-      @debug = debug
+      @secret = secret
       @timeout = 10         # default timeout for api requests
       @request_headers = {} # http headers sent in all requests
-
-      @version = version || get_api_version
+      @logger = logger
+      if logger.nil?
+        @logger = Logger.new(STDOUT)
+        @logger.level = Logger::INFO
+      end
+      
+      version = nil if version && version.strip.empty?
+      @version = nearest_version(version || get_api_version)
       unless @supported_versions.include?(@version)
-        raise BigBlueButtonException.new("BigBlueButton error: Invalid API version #{version}. Supported versions: #{@supported_versions.join(', ')}")
+        @logger.warn("BigBlueButtonAPI: detected unsupported version, using the closest one that is supported (#{@version})")
       end
 
-      puts "BigBlueButtonAPI: Using version #{@version}" if @debug
+      @logger.debug("BigBlueButtonAPI: Using version #{@version}")
     end
 
     # Creates a new meeting. Returns the hash with the response or throws BigBlueButtonException
@@ -225,7 +231,8 @@ module BigBlueButton
     #                         in this hash and they will be added to the API call.
     def join_meeting_url(meeting_id, user_name, password, options={})
       params = { :meetingID => meeting_id, :password => password, :fullName => user_name }.merge(options)
-      get_url(:join, params)
+      url, data = get_url(:join, params)
+      url
     end
 
     # Returns a hash object containing the information of a meeting.
@@ -459,6 +466,10 @@ module BigBlueButton
         options[:meetingID] = options[:meetingID].join(",") if options[:meetingID].instance_of?(Array)
       end
 
+      if options.has_key?(:state)
+        options[:state] = options[:state].join(",") if options[:state].instance_of?(Array)
+      end
+
       response = send_api_request(:getRecordings, options)
 
       formatter = BigBlueButtonFormatter.new(response)
@@ -467,6 +478,30 @@ module BigBlueButton
       response
     end
 
+    # Available since BBB v1.1
+    # Update metadata (or other attributes depending on the API implementation) 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"]
+    # meta (String)::         Pass one or more metadata values to be update (format is the same as in create call)
+    # options (Hash)::        Hash with additional parameters. This method doesn't accept additional
+    #                         parameters, but if you have a custom API with more parameters, you
+    #                         can simply pass them in this hash and they will be added to the API call.
+    #
+    # === Example responses
+    #
+    #   { :returncode => success, :updated => true }      
+    #
+    def update_recordings(recordIDs, meta=nil, options={})
+       recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
+       params = { :recordID => recordIDs, :meta => meta }.merge(options)
+       send_api_request(:updateRecordings, params)
+    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:
@@ -598,10 +633,15 @@ module BigBlueButton
       response[:returncode]
     end
 
+    def check_url
+      url, data = get_url(:check)
+      url
+    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|
+      [:url, :supported_versions, :secret, :version, :logger].each do |param|
         r = r && self.send(param) == other.send(param)
       end
       r
@@ -622,11 +662,12 @@ module BigBlueButton
     # params (Hash)::    The parameters to be passed in the URL
     def get_url(method, params={})
       if method == :index
-        return @url
+        return @url, nil
+      elsif method == :check
+        baseurl = URI.join(@url, "/").to_s
+        return "#{baseurl}check", nil
       end
 
-      url = "#{@url}/#{method}?"
-
       # stringify and escape all params
       params.delete_if { |k, v| v.nil? } unless params.nil?
       # some API calls require the params to be sorted
@@ -634,16 +675,22 @@ module BigBlueButton
       params = params.inject({}){ |memo,(k,v)| memo[k.to_sym] = v; memo }
       params = Hash[params.sort]
       params_string = ""
-      params_string = params.map{ |k,v| "#{k}=" + CGI::escape(v.to_s) unless k.nil? || v.nil? }.join("&")
+      params_string = params.map{ |k,v| "#{k}=" + URI.encode_www_form_component(v.to_s) unless k.nil? || v.nil? }.join("&")
 
       # checksum calc
-      checksum_param = params_string + @salt
+      checksum_param = params_string + @secret
       checksum_param = method.to_s + checksum_param
       checksum = Digest::SHA1.hexdigest(checksum_param)
 
-      # final url
-      url += "#{params_string}&" unless params_string.empty?
-      url += "checksum=#{checksum}"
+      if method == :setConfigXML
+        params_string = "checksum=#{checksum}&#{params_string}"
+        return "#{@url}/#{method}", params_string
+      else
+        url = "#{@url}/#{method}?"
+        url += "#{params_string}&" unless params_string.empty?
+        url += "checksum=#{checksum}"
+        return url, nil
+      end
     end
 
     # Performs an API call.
@@ -660,7 +707,9 @@ module BigBlueButton
     # raw (boolean)::    If true, returns the data as it was received. Will not parse it into a Hash,
     #                    check for errors or throw exceptions.
     def send_api_request(method, params={}, data=nil, raw=false)
-      url = get_url(method, params)
+      # if the method returns a body, use it as the data in the post request
+      url, body = get_url(method, params)
+      data = body if body
 
       @http_response = send_request(url, data)
       return {} if @http_response.body.empty?
@@ -699,29 +748,59 @@ module BigBlueButton
     # Otherwise uses GET
     def send_request(url, data=nil)
       begin
-        puts "BigBlueButtonAPI: URL request = #{url}" if @debug
+        @logger.debug("BigBlueButtonAPI: URL request = #{url}")
         url_parsed = URI.parse(url)
         http = Net::HTTP.new(url_parsed.host, url_parsed.port)
         http.open_timeout = @timeout
         http.read_timeout = @timeout
+        http.use_ssl = true if url_parsed.scheme.downcase == 'https'
+
         if data.nil?
           response = http.get(url_parsed.request_uri, @request_headers)
         else
-          puts "BigBlueButtonAPI: Sending as a POST request with data.size = #{data.size}" if @debug
-          opts = { 'Content-Type' => 'text/xml' }.merge @request_headers
+          @logger.debug("BigBlueButtonAPI: Sending as a POST request with data.size = #{data.size}")
+          opts = { 'Content-Type' => 'application/xml' }.merge @request_headers
           response = http.post(url_parsed.request_uri, data, opts)
         end
-        puts "BigBlueButtonAPI: URL response = #{response.body}" if @debug
+        @logger.info("BigBlueButtonAPI: request=#{url} response_status=#{response.class.name} response_code=#{response.code}  message_key=#{response.message}")
+        @logger.debug("BigBlueButtonAPI: URL response = #{response.body}")
 
-      rescue TimeoutError => error
-        raise BigBlueButtonException.new("Timeout error. Your server is probably down: \"#{@url}\". Error: #{error}")
+      rescue Timeout::Error => error
+        exception = BigBlueButtonException.new("Timeout error. Your server is probably down: \"#{@url}\". Error: #{error}")
+        exception.key = 'TimeoutError'
+        raise exception
 
       rescue Exception => error
-        raise BigBlueButtonException.new("Connection error. Your URL is probably incorrect: \"#{@url}\". Error: #{error}")
+        exception = BigBlueButtonException.new("Connection error. Your URL is probably incorrect: \"#{@url}\". Error: #{error}")
+        exception.key = 'IncorrectUrlError'
+        raise exception
       end
 
       response
     end
 
+    def nearest_version(target)
+      version = target
+
+      # 0.81 in BBB is actually < than 0.9, but not when comparing here
+      # so normalize x.xx versions to x.x.x
+      match = version.match(/(\d)\.(\d)(\d)/)
+      version = "#{match[1]}.#{match[2]}.#{match[3]}" if match
+
+      # we don't allow older versions than the one supported, use an old version of the gem for that
+      if Gem::Version.new(version) < Gem::Version.new(@supported_versions[0])
+        exception = BigBlueButtonException.new("BigBlueButton error: Invalid API version #{version}. Supported versions: #{@supported_versions.join(', ')}")
+        exception.key = 'APIVersionError'
+        raise exception
+
+      # allow newer versions by using the newest one we support
+      elsif Gem::Version.new(version) > Gem::Version.new(@supported_versions.last)
+        @supported_versions.last
+
+      else
+        target
+      end
+    end
+
   end
 end

data/lib/bigbluebutton_config_layout.rb

@@ -29,7 +29,9 @@ module BigBlueButton
       begin
         @xml = XmlSimple.xml_in(xml, opts)
       rescue Exception => e
-        raise BigBlueButton::BigBlueButtonException.new("Error parsing the layouts XML. Error: #{e.message}")
+        exception = BigBlueButton::BigBlueButtonException.new("Error parsing the layouts XML. Error: #{e.message}")
+        exception.key = 'XMLParsingError'
+        raise exception
       end
     end
 

data/lib/bigbluebutton_config_xml.rb

@@ -25,15 +25,17 @@ module BigBlueButton
     attr_accessor :xml
 
     def initialize(xml)
-      @original_xml = nil
+      @original_string = nil
       @xml = nil
       unless xml.nil?
         opts = { 'ForceArray' => false, 'KeepRoot' => true }
         begin
           @xml = XmlSimple.xml_in(xml, opts)
-          @original_xml = Marshal.load(Marshal.dump(@xml))
+          @original_string = self.as_string.clone
         rescue Exception => e
-          raise BigBlueButton::BigBlueButtonException.new("Error parsing the config XML. Error: #{e.message}")
+          exception = BigBlueButton::BigBlueButtonException.new("Error parsing the config XML. Error: #{e.message}")
+          exception.key = 'XMLParsingError'
+          raise exception
         end
       end
     end
@@ -60,7 +62,8 @@ module BigBlueButton
       if tag
         attr = find_attribute(tag, attr_name)
         if attr
-          tag[attr_name] = value
+          # saves always as string
+          tag[attr_name] = value.is_a?(String) ? value : value.to_s
         else
           nil
         end
@@ -75,7 +78,7 @@ module BigBlueButton
 
     def is_modified?
       @xml and
-        @xml != @original_xml
+        self.as_string != @original_string
     end
 
     protected

data/lib/bigbluebutton_exception.rb

@@ -1,6 +1,6 @@
 module BigBlueButton
 
-  class BigBlueButtonException < Exception
+  class BigBlueButtonException < StandardError
     attr_accessor :key
 
     def to_s

data/lib/bigbluebutton_formatter.rb

@@ -22,7 +22,7 @@ module BigBlueButton
       unless @hash.has_key?(key)
         0
       else
-        @hash[key] = @hash[key].to_i
+        @hash[key] = @hash[key].to_i rescue 0
       end
     end
 
@@ -49,7 +49,9 @@ module BigBlueButton
         if value.is_a?(Numeric)
           result = value == 0 ? nil : DateTime.parse(Time.at(value/1000.0).to_s)
         else
-          if value.downcase == "null"
+          if (value.is_a?(Hash) || value.is_a?(Array)) && value.empty?
+            result = nil
+          elsif value.is_a?(String) && (value.empty? || value.downcase == 'null')
             result = nil
           else
             # note: just in case the value comes as a string in the format: "Thu Sep 01 17:51:42 UTC 2011"

data/lib/bigbluebutton_hash_to_xml.rb

@@ -10,7 +10,9 @@ module BigBlueButton
           hash = XmlSimple.xml_in(xml_io, opts)
           return symbolize_keys(hash)
         rescue Exception => e
-          raise BigBlueButtonException.new("Impossible to convert XML to hash. Error: #{e.message}")
+          exception = BigBlueButtonException.new("Impossible to convert XML to hash. Error: #{e.message}")
+          exception.key = 'XMLConversionError'  
+          raise exception
         end
       end
 

data/spec/bigbluebutton_api_0.81_spec.rb

@@ -5,10 +5,9 @@ describe BigBlueButton::BigBlueButtonApi do
 
   # default variables and API object for all tests
   let(:url) { "http://server.com" }
-  let(:salt) { "1234567890abcdefghijkl" }
+  let(:secret) { "1234567890abcdefghijkl" }
   let(:version) { "0.81" }
-  let(:debug) { false }
-  let(:api) { BigBlueButton::BigBlueButtonApi.new(url, salt, version, debug) }
+  let(:api) { BigBlueButton::BigBlueButtonApi.new(url, secret, version) }
 
   describe "#get_default_config_xml" do
     let(:response) { "<response><returncode>1</returncode></response>" }

data/spec/bigbluebutton_api_0.9_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+# Tests for BBB API version 0.81
+describe BigBlueButton::BigBlueButtonApi do
+
+  # default variables and API object for all tests
+  let(:url) { "http://server.com" }
+  let(:secret) { "1234567890abcdefghijkl" }
+  let(:version) { "0.9" }
+  let(:api) { BigBlueButton::BigBlueButtonApi.new(url, secret, version) }
+
+  describe "#create_meeting" do
+    context "accepts the new parameters" do
+      let(:req_params) {
+        { :name => "name", :meetingID => "meeting-id",
+          :moderatorOnlyMessage => "my-msg", :autoStartRecording => "false",
+          :allowStartStopRecording => "true"
+        }
+      }
+
+      before { api.should_receive(:send_api_request).with(:create, req_params) }
+      it {
+        options = {
+          :moderatorOnlyMessage => "my-msg",
+          :autoStartRecording => "false",
+          :allowStartStopRecording => "true"
+        }
+        api.create_meeting("name", "meeting-id", options)
+      }
+    end
+  end
+end