bigbluebutton-api-ruby 1.2.0 → 1.3.0

data/.gitignore

@@ -5,3 +5,4 @@ features/config.yml
 logs/bbb.log
 rdoc/
 logs/*
+.bundle/

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p484

data/CHANGELOG.rdoc

@@ -1,3 +1,11 @@
+=== 1.3.0
+
+* Drop support to BigBlueButton 0.7 and add BigBlueButton to 0.81. Includes support to the new API calls <tt>getDefaultConfigXML</tt> and <tt>setConfigXML</tt>.
+* Reviewed all methods responses (some changed a bit) and documentation.
+* Allow non standard options to be passed to *all* API calls.
+* Removed method <tt>join_meeting</tt> that was usually not used. Should always use <tt>join_meeting_url</tt>.
+* Moved the hash extension method <tt>from_xml</tt> to its own class to prevent conflicts with Rails. See https://github.com/mconf/bigbluebutton-api-ruby/pull/6.
+
 === 1.2.0
 
 * Allow non standard options to be passed to some API calls. These API calls are: create_meeting, join_meeting_url,

data/Gemfile.lock

@@ -1,13 +1,13 @@
 GIT
   remote: git://github.com/mconf/bbbot-ruby.git
-  revision: 6b47fe212ea49a3120e9ee787cedd6097c9c81bd
+  revision: fcfd8c4c71371653335a46d7462ee14a9301f546
   specs:
     bbbot-ruby (0.0.1)
 
 PATH
   remote: .
   specs:
-    bigbluebutton-api-ruby (1.2.0)
+    bigbluebutton-api-ruby (1.3.0)
       xml-simple (>= 1.1.1)
 
 GEM
@@ -67,7 +67,7 @@ GEM
       multi_json (~> 1.0)
       rubyzip
     term-ansicolor (1.0.7)
-    xml-simple (1.1.1)
+    xml-simple (1.1.3)
     xpath (0.1.4)
       nokogiri (~> 1.3)
 

data/README.rdoc

@@ -1,40 +1,44 @@
 = bigbluebutton-api-ruby {<img src="http://travis-ci.org/mconf/bigbluebutton-api-ruby.png"/>}[http://travis-ci.org/mconf/bigbluebutton-api-ruby]
 
-This is a ruby gem that provides access to the {BigBlueButton}[http://bigbluebutton.org] API.
-For the API documentation see {this page}[http://code.google.com/p/bigbluebutton/wiki/API].
+This is a ruby gem that provides access to the API of {BigBlueButton}[http://bigbluebutton.org].
+See the documentation of the API {here}[http://code.google.com/p/bigbluebutton/wiki/API].
 
-Basically it enables a ruby application to interact with BigBlueButton by calling ruby methods instead of HTTP requests making it a lot easier to
-interact with BigBlueButton. And also formats the responses to a ruby-friendly format.
+It enables a ruby application to interact with BigBlueButton by calling ruby methods instead of
+HTTP requests, making it a lot easier to interact with BigBlueButton. It also formats the responses
+to a ruby-friendly format and includes helper classes to deal with more complicated API calls, such
+as the pre-upload of slides.
 
-Some details:
+A few features it has:
 
 * Provides methods to perform all API calls and get the responses;
 * Converts the XML responses to ruby hashes, that are easier to work with;
 * Converts the string values returned to native ruby types. For instance:
   * Dates are converted DateTime objects (e.g. "Thu Sep 01 17:51:42 UTC 2011");
   * Response codes are converted to boolean (e.g. "SUCCESS" becomes <tt>true</tt>);
-* Deals with errors (e.g. timeouts) throwing BigBlueButtonException exceptions;
+* Deals with errors (e.g. timeouts) throwing <tt>BigBlueButtonException</tt> exceptions;
 * Support to multiple BigBlueButton API versions (see below).
 
 == Supported BigBlueButton versions
 
-The current version of this gem supports *all* the following versions of BigBlueButton:
+The current version of this gem supports <em>all</em> the following versions of BigBlueButton:
 
-* 0.8: currently in the beta3 stage.
-* 0.7: including 0.7, 0.71 and 0.71a.
+* 0.8
+* 0.81
 
 Older versions:
 
-* 0.64: see the branch "api-0.64". The last version with support to 0.64 is {version 0.0.10}[https://github.com/mconf/bigbluebutton-api-ruby/tree/v0.0.10]. It supports both 0.64 and 0.7.
+* 0.7 (including 0.7, 0.71 and 0.71a): The last version with support to 0.7* is {version 1.2.0}[https://github.com/mconf/bigbluebutton-api-ruby/tree/v1.2.0]. It supports versions 0.7 and 0.8.
+* 0.64: see the branch <tt>api-0.64</tt>. The last version with support to 0.64 is {version 0.0.10}[https://github.com/mconf/bigbluebutton-api-ruby/tree/v0.0.10]. It supports versions 0.64 and 0.7.
 
 == Supported ruby versions
 
 Tested in rubies:
 
-* ruby-1.8.7
-* ruby-1.9.2
-* ree-1.8.7
-* jruby
+* ruby-2.0.0 (p353)
+* ruby-1.9.3 (p484) *recommended*
+* ruby-1.9.2 (p290)
+
+Use these versions to be sure it will work. Other patches of these rubies (e.g. ruby 1.9.3-p194) should work as well.
 
 == Releases
 
@@ -42,9 +46,9 @@ For a list of releases and release notes see {CHANGELOG.rdoc}[https://github.com
 
 == Development
 
-Information about the development of <tt>bigbluebutton-api-ruby</tt> can be found in {our wiki}[https://github.com/mconf/bigbluebutton-api-ruby/wiki].
+Information for developers of <tt>bigbluebutton-api-ruby</tt> can be found in {our wiki}[https://github.com/mconf/bigbluebutton-api-ruby/wiki].
 
-The development of this gem is guided by the requirements of the project Mconf. To know more about it visit the {project's wiki}[http://code.google.com/p/mconf/].
+The development of this gem is guided by the requirements of the project Mconf. To know more about it visit the {project's wiki}[https://github.com/mconf/wiki/wiki].
 
 == License
 

data/Rakefile

@@ -17,11 +17,12 @@ Cucumber::Rake::Task.new do |t|
     prepend = "--tags ~@need-bot"
   end
 
-  # defaults to BBB 0.8
-  if ENV["V"] == "0.7" or ENV["VERSION"] == "0.7"
-    t.cucumber_opts = "--format pretty --tags ~@wip --tags @version-all,@version-07 #{prepend}"
+  # defaults to BBB 0.81, that runs all tests
+  # if set to 0.8 only, won't run tests for newer versions
+  if ENV["V"] == "0.8" or ENV["VERSION"] == "0.8"
+    t.cucumber_opts = "--format pretty --tags ~@wip --tags @version-all #{prepend}"
   else
-    t.cucumber_opts = "--format pretty --tags ~@wip --tags @version-all,@version-08 #{prepend}"
+    t.cucumber_opts = "--format pretty --tags ~@wip --tags @version-all,@version-081 #{prepend}"
   end
 end
 

data/bigbluebutton-api-ruby.gemspec

@@ -2,7 +2,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name = 'bigbluebutton-api-ruby'
-  s.version = '1.2.0'
+  s.version = '1.3.0'
   s.extra_rdoc_files = ['README.rdoc', 'LICENSE', 'LICENSE_003', 'CHANGELOG.rdoc']
   s.summary = 'Provides an interface to the BigBlueButton web meeting API (https://github.com/mconf/bigbluebutton-api-ruby)'
   s.description = s.summary

data/examples/config_xml.rb

@@ -0,0 +1,74 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+$:.unshift File.join(File.expand_path(File.dirname(__FILE__)), '..', 'lib')
+
+require 'bigbluebutton_api'
+require 'prepare'
+
+begin
+  prepare
+
+  puts "---------------------------------------------------"
+  config_xml = @api.get_default_config_xml
+  config_xml = BigBlueButton::BigBlueButtonConfigXml.new(config_xml)
+  puts "The default config.xml was taken from the server"
+
+  puts "---------------------------------------------------"
+  layouts = @api.get_available_layouts
+  puts "The available layouts are"
+  puts layouts.inspect
+  puts "The default layouts are"
+  puts @api.get_default_layouts.inspect
+
+  puts "---------------------------------------------------"
+  num = rand(1000)
+  meeting_name = "Test Meeting #{num}"
+  meeting_id = "test-meeting-#{num}"
+  username = "House #{rand(1000)}"
+  username2 = "Cameron #{rand(1000)}"
+  options = { :moderatorPW => "54321",
+    :attendeePW => "12345",
+    :welcome => 'Welcome to my meeting',
+    :dialNumber => '1-800-000-0000x00000#',
+    :logoutURL => 'https://github.com/mconf/bigbluebutton-api-ruby',
+    :maxParticipants => 25 }
+  response = @api.create_meeting(meeting_name, meeting_id, options)
+  puts "A meeting has been created: #{meeting_id}"
+
+  puts "---------------------------------------------------"
+  url = @api.join_meeting_url(meeting_id, username, options[:moderatorPW])
+  puts "Please join the meeting as moderator using the link: #{url}"
+  puts "*** You will be using the DEFAULT config.xml ***"
+  puts "Waiting 30 seconds for you to join..."
+  puts
+  sleep(30)
+
+  puts "---------------------------------------------------"
+  puts "Creating a new config.xml"
+  # config_xml.set_attribute("layout", "showToolbar", "false", false)
+  config_xml.set_attribute("skinning", "enabled", "false", false)
+  config_xml.set_attribute("layout", "defaultLayout", "Webinar", false)
+  config_xml.set_attribute("layout", "showLayoutTools", "false", false)
+  config_xml.set_attribute("ChatModule", "privateEnabled", "false")
+  config_xml.set_attribute("VideoconfModule", "resolutions", "320x240")
+  config_xml.set_attribute("VideoconfModule", "presenterShareOnly", "true")
+
+  puts "---------------------------------------------------"
+  token = @api.set_config_xml(meeting_id, config_xml)
+  puts "Setting the new config.xml returned the token: #{token}"
+
+  puts "---------------------------------------------------"
+  url = @api.join_meeting_url(meeting_id, username2, options[:moderatorPW], { :configToken => token })
+  puts "Please join the meeting again using the link: #{url}"
+  puts "*** You will be using the MODIFIED config.xml, with the following modifications: ***"
+  puts "***  - Disabled layout (will show the default layout, as was used in BBB < 0.8)"
+  puts "***  - Default layout to Webinar"
+  puts "***  - Hidden layout tools"
+  puts "***  - Disabled private chat"
+  puts "***  - Restricted video resolutions to 320x240 only"
+  puts "***  - Disabled video sharing except for the presenter"
+  puts
+
+rescue Exception => ex
+  puts "Failed with error #{ex.message}"
+  puts ex.backtrace
+end

data/examples/create.rb

@@ -0,0 +1,29 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+$:.unshift File.join(File.expand_path(File.dirname(__FILE__)), '..', 'lib')
+
+require 'bigbluebutton_api'
+require 'prepare'
+
+begin
+  prepare
+
+  num = rand(1000)
+  meeting_name = "Test Meeting #{num}"
+  meeting_id = "test-meeting-#{num}"
+  moderator_name = "House"
+  attendee_name = "Cameron"
+  puts "---------------------------------------------------"
+  options = { :moderatorPW => "54321",
+    :attendeePW => "12345",
+    :welcome => 'Welcome to my meeting',
+    :dialNumber => '1-800-000-0000x00000#',
+    :logoutURL => 'https://github.com/mconf/bigbluebutton-api-ruby',
+    :maxParticipants => 25 }
+  response = @api.create_meeting(meeting_name, meeting_id, options)
+  puts "The meeting has been created with the response:"
+  puts response.inspect
+
+rescue Exception => ex
+  puts "Failed with error #{ex.message}"
+  puts ex.backtrace
+end

data/examples/join_example.rb

@@ -45,14 +45,6 @@ begin
   puts "Meeting info:"
   puts response.inspect
 
-  puts
-  puts
-  puts
-  puts "---------------------------------------------------"
-  response = @api.join_meeting(meeting_id, attendee_name, options[:attendeePW])
-  puts "Join meeting response:"
-  puts response.inspect
-
 rescue Exception => ex
   puts "Failed with error #{ex.message}"
   puts ex.backtrace

data/features/config.yml.example

@@ -10,12 +10,13 @@ timeout_ending: 30
 timeout_bot_start: 60
 
 servers:
-  bbb-dev-07:
-    salt: 'your-salt'
-    url: 'http://your-server/bigbluebutton/api'
-    version: '0.7'
-  test-install-08:
+  test-install-081:
     salt: '8cd8ef52e8e101574e400365b55e11a6'
     url: 'http://test-install.blindsidenetworks.com/bigbluebutton/api'
+    version: '0.81'
+    mobile_salt: '03b07' # needed for >= 0.8
+  bbb-08:
+    salt: 'lka98f52e8akdlsoie400365b55e98s7'
+    url: 'http://yourserver.com/bigbluebutton/api'
     version: '0.8'
     mobile_salt: '03b07' # needed for >= 0.8

data/features/create_meetings.feature

@@ -19,16 +19,7 @@ Feature: Create rooms
     When the create method is called with a duplicated meeting id
     Then the response is an error with the key "idNotUnique"
 
-  @version-07 @need-bot
-  Scenario: Try to recreate a previously ended meeting
-    Given the create method is called
-      # note: meeting needs to be running to be ended in 0.7
-      And the meeting is running
-      And the meeting is forcibly ended
-    When the create method is called again with the same meeting id
-    Then the response is an error with the key "idNotUnique"
-
-  @version-08 @need-bot
+  @version-all @need-bot
   Scenario: Try to recreate a previously ended meeting
     Given the create method is called
       And the meeting is running

data/features/end_meetings.feature

@@ -2,34 +2,16 @@ Feature: End rooms
   To stop a meeting using the API
   One needs to be able to call 'end' to this meeting
 
-  @version-07 @need-bot
+  @version-all @need-bot
   Scenario: End a meeting
     Given that a meeting was created
       And the meeting is running
     When the method to end the meeting is called
     Then the response is successful and well formatted
       And the meeting should be ended
-      And the information returned by get_meeting_info is correct
 
-  @version-08 @need-bot
-  Scenario: End a meeting
-    Given that a meeting was created
-      And the meeting is running
-    When the method to end the meeting is called
-    Then the response is successful and well formatted
-      And the meeting should be ended
-      # the meeting may not exist anymore in 0.8
-
-  # in 0.7 ending a meeting that is not running generates an error
-  @version-07
-  Scenario: Try to end a meeting that is not running in 0.7
-    Given that a meeting was created
-    When the method to end the meeting is called
-    Then the response is an error with the key "notFound"
-
-  # in 0.8 ending a meeting that is not running is ok
-  @version-08
-  Scenario: Try to end a meeting that is not running in 0.8
+  @version-all
+  Scenario: Try to end a meeting that is not running
     Given that a meeting was created
     When the method to end the meeting is called
     Then the response is successful

data/features/pre_upload_slides.feature

@@ -1,4 +1,4 @@
-@version-08
+@version-all
 Feature: Pre-upload slides
   To have presentations ready in the meeting when the users join
   One needs to pre-upload these presentations when the meeting is created

data/features/recordings.feature

@@ -1,4 +1,4 @@
-@version-08
+@version-all
 Feature: Record a meeting and manage recordings
   To record a meeting or manage the recorded meeting
   One needs be able to list the recordings, publish and unpublish them

data/features/support/features_helpers.rb

@@ -37,7 +37,7 @@ module BigBlueButton
           else
             server = self.cfg['servers'].first[1]
           end
-          server['version'] = '0.7' unless server.has_key?('version')
+          server['version'] = '0.81' unless server.has_key?('version')
           server
         end
 

data/lib/bigbluebutton_api.rb

@@ -3,10 +3,12 @@ require 'cgi'
 require 'rexml/document'
 require 'digest/sha1'
 require 'rubygems'
-require 'hash_to_xml'
+require 'bigbluebutton_hash_to_xml'
 require 'bigbluebutton_exception'
 require 'bigbluebutton_formatter'
 require 'bigbluebutton_modules'
+require 'bigbluebutton_config_xml'
+require 'bigbluebutton_config_layout'
 
 module BigBlueButton
 
@@ -19,13 +21,14 @@ module BigBlueButton
   # 4. To force meeting to end, call end_meeting .
   #
   # 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.
+  # * The XML returned by BigBlueButton is converted to a BigBlueButton::BigBlueButtonHash. See each 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:
+  # * Some of the values returned by BigBlueButton are converted to better represent the data.
+  #   Some of these are listed bellow. They will *always* have the type informed:
   #   * :meetingID (string)
   #   * :attendeePW (string)
   #   * :moderatorPW (string)
@@ -33,6 +36,9 @@ module BigBlueButton
   #   * :hasBeenForciblyEnded (boolean)
   #   * :endTime and :startTime (DateTime or nil)
   #
+  # For more information about the API, see the documentation at:
+  # * http://code.google.com/p/bigbluebutton/wiki/API
+  #
   class BigBlueButtonApi
 
     # URL to a BigBlueButton server (e.g. http://demo.bigbluebutton.org/bigbluebutton/api)
@@ -41,7 +47,7 @@ module BigBlueButton
     # Secret salt for this server
     attr_accessor :salt
 
-    # API version e.g. 0.7 (valid for 0.7, 0.71 and 0.71a)
+    # API version e.g. 0.81
     attr_accessor :version
 
     # Flag to turn on/off debug mode
@@ -60,9 +66,9 @@ 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
-    # version::   API version e.g. 0.7 (valid for 0.7, 0.71 and 0.71a)
-    def initialize(url, salt, version='0.7', debug=false)
-      @supported_versions = ['0.7', '0.8']
+    # version::   API version e.g. 0.81
+    def initialize(url, salt, version='0.81', debug=false)
+      @supported_versions = ['0.8', '0.81']
       @url = url
       @salt = salt
       @debug = debug
@@ -77,32 +83,37 @@ module BigBlueButton
       puts "BigBlueButtonAPI: Using version #{@version}" if @debug
     end
 
-
-    #
-    # API calls since 0.7
-    #
-
-
-    # Creates a new meeting. Returns the hash with the response or
-    # throws BigBlueButtonException on failure.
+    # Creates a new meeting. Returns the hash with the response or throws BigBlueButtonException
+    # on failure.
     # 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),
+    # meeting_id (string)::             Unique identifier for the meeting
+    # options (Hash)::                  Hash with additional parameters. The accepted parameters are:
+    #                                   moderatorPW (string), attendeePW (string), 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.
+    #                                   voiceBridge (int), record (boolean), duration (int), redirectClient (string),
+    #                                   clientURL (string), and "meta" parameters (usually strings).
+    #                                   For details about each see BigBlueButton's API docs.
+    #                                   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.
     # 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.
+    #                                   "presentation" module is available.
     #                                   See usage examples below.
     #
     # === 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" }
+    #   options = {
+    #     :attendeePW => "321",
+    #     :moderatorPW => "123",
+    #     :welcome => "Welcome here!",
+    #     :dialNumber => 5190909090,
+    #     :voiceBridge => 76543,
+    #     :logoutURL => "http://mconf.org",
+    #     :record => true,
+    #     :duration => 0,
+    #     :maxParticipants => 25,
+    #     :meta_category => "Remote Class"
+    #   }
     #   create_meeting("My Meeting", "my-meeting", options)
     #
     # === Example with modules (see BigBlueButtonModules docs for more)
@@ -114,31 +125,32 @@ module BigBlueButton
     #   modules.add_presentation(:base64, "JVBERi0xLjQKJ....[clipped here]....0CiUlRU9GCg==", "first-class.pdf")
     #   create_meeting("My Meeting", "my-meeting", nil, modules)
     #
-    # === Example response for 0.7
+    # === Example response for 0.81
     #
     # On successful creation:
     #
     #   {
-    #    :returncode => true, :meetingID => "test",
-    #    :attendeePW => "1234", :moderatorPW => "4321", :hasBeenForciblyEnded => false,
-    #    :messageKey => "", :message => ""
+    #     :returncode => true,
+    #     :meetingID => "0c521f3d",
+    #     :attendeePW => "12345",
+    #     :moderatorPW => "54321",
+    #     :createTime => 1389464535956,
+    #     :hasBeenForciblyEnded => false,
+    #     :messageKey => "",
+    #     :message => ""
     #   }
     #
-    # Meeting that was forcibly ended:
+    # When creating a meeting that already exist:
     #
     #   {
-    #    :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."
-    #   }
-    #
-    # === Example response for 0.8
-    #
-    #   {
-    #    :returncode => true, :meetingID => "Test", :createTime => 1308591802,
-    #    :attendeePW => "1234", :moderatorPW => "4321", :hasBeenForciblyEnded => false,
-    #    :messageKey => "", :message => ""
+    #     :returncode => true,
+    #     :meetingID => "7a1d614b",
+    #     :attendeePW => "12345",
+    #     :moderatorPW => "54321",
+    #     :createTime => 1389464682402,
+    #     :hasBeenForciblyEnded => false,
+    #     :messageKey => "duplicateWarning",
+    #     :message => "This conference was already in existence and may currently be in progress."
     #   }
     #
     def create_meeting(meeting_name, meeting_id, options={}, modules=nil)
@@ -149,8 +161,8 @@ module BigBlueButton
         params[:record] = params[:record].to_s
       end
 
-      # with modules we send a post request (only for >= 0.8)
-      if modules and @version >= "0.8"
+      # with modules we send a post request
+      if modules
         response = send_api_request(:create, params, modules.to_xml)
       else
         response = send_api_request(:create, params)
@@ -161,112 +173,131 @@ module BigBlueButton
       formatter.to_string(:moderatorPW)
       formatter.to_string(:attendeePW)
       formatter.to_boolean(:hasBeenForciblyEnded)
-      if @version >= "0.8"
-        formatter.to_int(:createTime)
-      end
+      formatter.to_int(:createTime)
 
       response
     end
 
     # Ends an existing meeting. Throws BigBlueButtonException on failure.
-    # meeting_id (string, int)::          Unique identifier for the meeting
-    # moderator_password (string, int)::  Moderator password
+    # meeting_id (string)::          Unique identifier for the meeting
+    # moderator_password (string)::  Moderator password
+    # 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.
     #
-    # === Return examples (for 0.7)
+    # === Return examples (for 0.81)
     #
     # On success:
     #
     #   {
-    #    :returncode=>true, :messageKey=>"sentEndMeetingRequest",
-    #    :message=>"A request to end the meeting was sent.  Please wait a few seconds, and then use the getMeetingInfo
-    #               or isMeetingRunning API calls to verify that it was ended."
+    #     :returncode=>true,
+    #     :messageKey => "sentEndMeetingRequest",
+    #     :message => "A request to end the meeting was sent.  Please wait a few seconds, and then use the getMeetingInfo or isMeetingRunning API calls to verify that it was ended."
     #   }
     #
-    def end_meeting(meeting_id, moderator_password)
-      send_api_request(:end, { :meetingID => meeting_id, :password => moderator_password } )
+    def end_meeting(meeting_id, moderator_password, options={})
+      params = { :meetingID => meeting_id, :password => moderator_password }.merge(options)
+      send_api_request(:end, params)
     end
 
-    # Returns true or false as to whether meeting is open.  A meeting is
-    # only open after at least one participant has joined.
-    # meeting_id (string, int)::          Unique identifier for the meeting
-    def is_meeting_running?(meeting_id)
-      hash = send_api_request(:isMeetingRunning, { :meetingID => meeting_id } )
+    # Returns whether the meeting is running or not. A meeting is only running after at least
+    # one participant has joined. Returns true or false.
+    # meeting_id (string)::    Unique identifier for the meeting
+    # 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.
+    def is_meeting_running?(meeting_id, options={})
+      params = { :meetingID => meeting_id }.merge(options)
+      hash = send_api_request(:isMeetingRunning, params)
       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.
+    # Returns a string with the url used to join the meeting
+    # meeting_id (string)::   Unique identifier for the meeting
+    # user_name (string)::    Name of the user
+    # password (string)::     Password for this meeting - will be used to decide if the user is a
+    #                         moderator or attendee
+    # options (Hash)::        Hash with additional parameters. The accepted parameters are:
+    #                         userID (string), webVoiceConf (string), createTime (int),
+    #                         configToken (string), and avatarURL (string).
+    #                         For details about each see BigBlueButton's API docs.
+    #                         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.
     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)
     end
 
-    # Warning: As of this version of the gem, this call does not work
-    # (instead of returning XML response, it should join the meeting).
-    #
-    # Joins a user into the meeting using an API call, instead of
-    # 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 (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={})
-      params = { :meetingID => meeting_id, :password => password, :fullName => user_name }.merge(options)
-      send_api_request(:join, params)
-    end
-
-    # 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).
+    # Returns a hash object containing the information of a meeting.
     #
-    # meeting_id (string, int)::  Unique identifier for the meeting
-    # password (string, int)::    Moderator password for this meeting
+    # meeting_id (string)::  Unique identifier for the meeting
+    # password (string)::    Moderator password for this meeting
+    # 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 for 0.7
+    # === Example responses for 0.81
     #
-    # With attendees:
+    # Running with attendees and metadata:
     #
-    #   {
-    #    :returncode=>true, :meetingID=>"bigbluebutton-api-ruby-test", :attendeePW=>"1234", :moderatorPW=>"4321", :running=>true,
-    #    :hasBeenForciblyEnded=>false, :startTime=>DateTime("Wed Apr 06 17:09:57 UTC 2011"), :endTime=>nil, :participantCount=>4, :moderatorCount=>2,
-    #    :attendees => [
-    #      {:userID=>"ndw1fnaev0rj", :fullName=>"House M.D.", :role=>:moderator},
-    #      {:userID=>"gn9e22b7ynna", :fullName=>"Dexter Morgan", :role=>:moderator},
-    #      {:userID=>"llzihbndryc3", :fullName=>"Cameron Palmer", :role=>:viewer},
-    #      {:userID=>"rbepbovolsxt", :fullName=>"Trinity", :role=>:viewer}
-    #    ], :messageKey=>"", :message=>""
-    #   }
-    #
-    # Without attendees (not started):
     #
     #   {
-    #    :returncode=>true, :meetingID=>"bigbluebutton-api-ruby-test", :attendeePW=>"1234", :moderatorPW=>"4321", :running=>false,
-    #    :hasBeenForciblyEnded=>false, :startTime=>nil, :endTime=>nil, :participantCount=>0, :moderatorCount=>0,
-    #    :attendees=>[], :messageKey=>"", :message=>""
+    #     :returncode => true,
+    #     :meetingName => "e56ef2c5",
+    #     :meetingID => "e56ef2c5",
+    #     :createTime => 1389465592542,
+    #     :voiceBridge => 72519,
+    #     :dialNumber => "1-800-000-0000x00000#",
+    #     :attendeePW => "12345",
+    #     :moderatorPW => "54321",
+    #     :running => true,
+    #     :recording => false,
+    #     :hasBeenForciblyEnded => false,
+    #     :startTime => #<DateTime: 2014-01-11T16:39:58-02:00 ((2456669j,67198s,0n),-7200s,2299161j)>,
+    #     :endTime => nil,
+    #     :participantCount => 2,
+    #     :maxUsers => 25,
+    #     :moderatorCount => 1,
+    #     :attendees => [
+    #       { :userID => "wsfoiqtnugul", :fullName => "Cameron", :role => :viewer, :customdata => {} },
+    #       { :userID => "qsaogaoqifjk", :fullName => "House", :role => :moderator, :customdata => {} }
+    #     ],
+    #     :metadata => {
+    #       :category => "Testing",
+    #       :anything => "Just trying it out"
+    #     },
+    #     :messageKey => "",
+    #     :message => ""
     #   }
     #
-    # === Example responses for 0.8
+    # Created but not started yet:
     #
     #   {
-    #     :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 => ""
+    #     :returncode => true,
+    #     :meetingName => "fe3ea879",
+    #     :meetingID => "fe3ea879",
+    #     :createTime => 1389465320050,
+    #     :voiceBridge => 79666,
+    #     :dialNumber => "1-800-000-0000x00000#",
+    #     :attendeePW => "12345",
+    #     :moderatorPW => "54321",
+    #     :running => false,
+    #     :recording => false,
+    #     :hasBeenForciblyEnded => false,
+    #     :startTime => nil,
+    #     :endTime => nil,
+    #     :participantCount => 0,
+    #     :maxUsers => 25,
+    #     :moderatorCount => 0,
+    #     :attendees => [],
+    #     :metadata => {},
+    #     :messageKey => "",
+    #     :message => ""
     #   }
     #
-    def get_meeting_info(meeting_id, password)
-      response = send_api_request(:getMeetingInfo, { :meetingID => meeting_id, :password => password } )
+    def get_meeting_info(meeting_id, password, options={})
+      params = { :meetingID => meeting_id, :password => password }.merge(options)
+      response = send_api_request(:getMeetingInfo, params)
 
       formatter = BigBlueButtonFormatter.new(response)
       formatter.flatten_objects(:attendees, :attendee)
@@ -281,38 +312,69 @@ module BigBlueButton
       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
+      formatter.to_string(:meetingName)
+      formatter.to_int(:maxUsers)
+      formatter.to_int(:voiceBridge)
+      formatter.to_int(:createTime)
+      formatter.to_boolean(:recording)
 
       response
     end
 
-    # Returns a hash object containing information about the meetings currently existent in the BBB
+    # Returns a hash object with information about all the meetings currently created in the
     # server, either they are running or not.
     #
-    # === Example responses for 0.7
+    # 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 for 0.81
     #
     # Server with one or more meetings:
     #
-    #   { :returncode => true,
+    #   {
+    #     :returncode => true,
     #     :meetings => [
-    #       {:meetingID=>"Demo Meeting", :attendeePW=>"ap", :moderatorPW=>"mp", :hasBeenForciblyEnded=>false, :running=>true},
-    #       {:meetingID=>"I was ended Meeting", :attendeePW=>"pass", :moderatorPW=>"pass", :hasBeenForciblyEnded=>true, :running=>false}
+    #       { :meetingID => "e66e88a3",
+    #         :meetingName => "e66e88a3",
+    #         :createTime => 1389466124414,
+    #         :voiceBridge => 78730,
+    #         :dialNumber=>"1-800-000-0000x00000#",
+    #         :attendeePW => "12345",
+    #         :moderatorPW => "54321",
+    #         :hasBeenForciblyEnded => false,
+    #         :running => false,
+    #         :participantCount => 0,
+    #         :listenerCount => 0,
+    #         :videoCount => 0 }
+    #       { :meetingID => "8f21cc63",
+    #         :meetingName => "8f21cc63",
+    #         :createTime => 1389466073245,
+    #         :voiceBridge => 78992,
+    #         :dialNumber => "1-800-000-0000x00000#",
+    #         :attendeePW => "12345",
+    #         :moderatorPW => "54321",
+    #         :hasBeenForciblyEnded => false,
+    #         :running => true,
+    #         :participantCount => 2,
+    #         :listenerCount => 0,
+    #         :videoCount => 0 }
     #     ],
-    #    :messageKey=>"", :message=>""
+    #     :messageKey => "",
+    #     :message => ""
     #   }
     #
     # Server with no meetings:
     #
-    #   {:returncode=>true, :meetings=>[], :messageKey=>"noMeetings", :message=>"no meetings were found on this server"}
+    #   {
+    #     :returncode => true,
+    #     :meetings => [],
+    #     :messageKey => "noMeetings",
+    #     :message => "no meetings were found on this server"
+    #   }
     #
-    def get_meetings
-      response = send_api_request(:getMeetings, { :random => rand(9999999999) } )
+    def get_meetings(options={})
+      response = send_api_request(:getMeetings, options)
 
       formatter = BigBlueButtonFormatter.new(response)
       formatter.flatten_objects(:meetings, :meeting)
@@ -320,28 +382,30 @@ module BigBlueButton
       response
     end
 
-    # Returns the API version (as string) of the associated server. This actually returns
-    # the version returned by the BBB server, and not the version set by the user in
-    # the initialization of this object.
+    # Returns the API version of the server as a string. Will return the version in the response
+    # given by the BigBlueButton server, and not the version set by the user in the initialization
+    # of this object!
     def get_api_version
       response = send_api_request(:index)
       response[:returncode] ? response[:version].to_s : ""
     end
 
 
-
     #
     # 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"]
+    # options (Hash)::       Hash with additional parameters. The accepted parameters are:
+    #                        :meetingID (string, Array). For details about each see BigBlueButton's
+    #                        API docs.
+    #                        Any of the following values are accepted for :meetingID :
+    #                          :meetingID => "id1"
+    #                          :meetingID => "id1,id2,id3"
+    #                          :meetingID => ["id1"]
+    #                          :meetingID => ["id1", "id2", "id3"]
+    #                        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
     #
@@ -349,7 +413,7 @@ module BigBlueButton
     #     :recordings => [
     #       {
     #         :recordID => "7f5745a08b24fa27551e7a065849dda3ce65dd32-1321618219268",
-    #         :meetingID=>"bd1811beecd20f24314819a52ec202bf446ab94b",
+    #         :meetingID => "bd1811beecd20f24314819a52ec202bf446ab94b",
     #         :name => "Evening Class1",
     #         :published => true,
     #         :startTime => #<DateTime: 2011-11-18T12:10:23+00:00 (212188378223/86400,0/1,2299161)>,
@@ -370,16 +434,26 @@ module BigBlueButton
     #           ]
     #         }
     #       },
-    #       { :recordID => "183f0bf3a0982a127bdb8161-13085974450", :meetingID => "CS102",
-    #         ...
-    #         ...
+    #       { :recordID => "1254kakap98sd09jk2lk2-1329872486234",
+    #         :recordID => "7f5745a08b24fa27551e7a065849dda3ce65dd32-1321618219268",
+    #         :meetingID => "bklajsdoiajs9d8jo23id90",
+    #         :name => "Evening Class2",
+    #         :published => false,
+    #         :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 => {},
+    #         :playback => {
+    #           :format => { # notice that this is now a hash, not an array
+    #             :type => "slides",
+    #             :url => "http://test-install.blindsidenetworks.com/playback/slides/playback.html?meetingId=1254kakap98sd09jk2lk2-1329872486234",
+    #             :length => 64
+    #           }
+    #         }
     #       }
     #     ]
     #   }
     #
     def get_recordings(options={})
-      raise BigBlueButtonException.new("Method only supported for versions >= 0.8") if @version < "0.8"
-
       # ["id1", "id2", "id3"] becomes "id1,id2,id3"
       if options.has_key?(:meetingID)
         options[:meetingID] = options[:meetingID].join(",") if options[:meetingID].instance_of?(Array)
@@ -400,17 +474,19 @@ module BigBlueButton
     #                                "id1,id2,id3"
     #                                ["id1"]
     #                                ["id1", "id2", "id3"]
-    # publish (boolean)::          Publish or unpublish the recordings?
+    # publish (boolean)::     Whether to publish or unpublish the recording(s)
+    # 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 => true, :published => true }
     #
-    def publish_recordings(recordIDs, publish)
-      raise BigBlueButtonException.new("Method only supported for versions >= 0.8") if @version < "0.8"
-
+    def publish_recordings(recordIDs, publish, options={})
       recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
-      send_api_request(:publishRecordings, { :recordID => recordIDs, :publish => publish.to_s })
+      params = { :recordID => recordIDs, :publish => publish.to_s }.merge(options)
+      send_api_request(:publishRecordings, params)
     end
 
     # Delete one or more recordings for a given recordID (or set of record IDs).
@@ -420,16 +496,69 @@ module BigBlueButton
     #                                "id1,id2,id3"
     #                                ["id1"]
     #                                ["id1", "id2", "id3"]
+    # 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 => true, :deleted => true }
     #
-    def delete_recordings(recordIDs)
-      raise BigBlueButtonException.new("Method only supported for versions >= 0.8") if @version < "0.8"
-
+    def delete_recordings(recordIDs, options={})
       recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
-      send_api_request(:deleteRecordings, { :recordID => recordIDs })
+      params = { :recordID => recordIDs }.merge(options)
+      send_api_request(:deleteRecordings, params)
+    end
+
+
+    #
+    # API calls since 0.81
+    #
+
+    # Retrieves the default config.xml file from the server.
+    # Returns the XML as a string by default, but if `asObject` is set to true, returns the XML
+    # parsed as an XmlSimple object ().
+    # asObject (Hash)::       If true, returns the XML parsed as an XmlSimple object, using:
+    #                           data = XmlSimple.xml_in(response, { 'ForceArray' => false, 'KeepRoot' => true })
+    #                         You can then parse it back into an XML string using:
+    #                           XmlSimple.xml_out(data, { 'RootName' => nil, 'XmlDeclaration' => true })
+    #                         If set to false, returns the XML as a string.
+    # 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.
+    def get_default_config_xml(asObject=false, options={})
+      response = send_api_request(:getDefaultConfigXML, options, nil, true)
+      if asObject
+        XmlSimple.xml_in(response, { 'ForceArray' => false, 'KeepRoot' => true })
+      else
+        response
+      end
+    end
+
+    # Sets a config.xml file in the server.
+    # Returns the token returned by the server (that can be later used in a 'join' call) in case
+    # of success.
+    # meeting_id (string)::                   The ID of the meeting where this config.xml will be used.
+    # xml (string|BigBlueButtonConfigXml)::   The XML that should be sent as a config.xml.
+    #                                         It will usually be an edited output of the default config.xml:
+    #                                           xml = api.get_default_config_xml
+    #                                         Or you can use directly a BigBlueButtonConfigXml object:
+    #                                           BigBlueButtonConfigXml.new(xml)
+    # 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.
+    # TODO: Right now we are sending the configXML parameters in the URL and in the body of the POST
+    #   request. It works if left only in the URL, but the documentation of the API claims that it has
+    #   to be in the body of the request. So it's no clear yet and this might change in the future.
+    def set_config_xml(meeting_id, xml, options={})
+      if xml.instance_of?(BigBlueButton::BigBlueButtonConfigXml)
+        data = xml.as_string
+      else
+        data = xml
+      end
+      params = { :meetingID => meeting_id, :configXML => data }.merge(options)
+      response = send_api_request(:setConfigXML, params, data)
+      response[:configToken]
     end
 
 
@@ -437,6 +566,32 @@ module BigBlueButton
     # Helper functions
     #
 
+    # Returns an array with the name of all layouts available in the server.
+    # Will fetch the config.xml file (unless passed in the arguments), fetch the
+    # layout definition file, and return the layouts.
+    # If something goes wrong, returns nil. Otherwise returns the list of layout
+    # names or an empty array if there's no layout defined.
+    def get_available_layouts(config_xml=nil)
+      config_xml = get_default_config_xml if config_xml.nil?
+      config_xml = BigBlueButton::BigBlueButtonConfigXml.new(config_xml)
+      layout_config = config_xml.get_attribute("LayoutModule", "layoutConfig", true)
+      unless layout_config.nil?
+        response = send_request(layout_config)
+        layout_config = BigBlueButton::BigBlueButtonConfigLayout.new(response.body)
+        layout_config.get_available_layouts
+      else
+        nil
+      end
+    end
+
+    # Returns an array with the layouts that exist by default in a BigBlueButton
+    # server. If you want to query the server to get a real list of layouts, use
+    # <tt>get_available_layouts</tt>.
+    def get_default_layouts
+      # this is the list for BigBlueButton 0.81
+      ["Default", "Video Chat", "Meeting", "Webinar", "Lecture assistant", "Lecture"]
+    end
+
     # Make a simple request to the server to test the connection.
     def test_connection
       response = send_api_request(:index)
@@ -474,6 +629,10 @@ module BigBlueButton
 
       # stringify and escape all params
       params.delete_if { |k, v| v.nil? } unless params.nil?
+      # some API calls require the params to be sorted
+      # first make all keys symbols, so the comparison works
+      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("&")
 
@@ -498,32 +657,39 @@ module BigBlueButton
     # 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)
+    # 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)
 
       @http_response = send_request(url, data)
-      return { } if @http_response.body.empty?
-
-      # 'Hashify' the XML
+      return {} if @http_response.body.empty?
       @xml_response = @http_response.body
-      hash = Hash.from_xml(@xml_response)
 
-      # simple validation of the xml body
-      unless hash.has_key?(:returncode)
-        raise BigBlueButtonException.new("Invalid response body. Is the API URL correct? \"#{@url}\", version #{@version}")
-      end
+      if raw
+        result = @xml_response
+      else
 
-      # default cleanup in the response
-      hash = BigBlueButtonFormatter.new(hash).default_formatting
+        # 'Hashify' the XML
+        result = BigBlueButtonHash.from_xml(@xml_response)
 
-      # 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] : ""
-        raise exception
+        # simple validation of the xml body
+        unless result.has_key?(:returncode)
+          raise BigBlueButtonException.new("Invalid response body. Is the API URL correct? \"#{@url}\", version #{@version}")
+        end
+
+        # default cleanup in the response
+        result = BigBlueButtonFormatter.new(result).default_formatting
+
+        # if the return code is an error generates an exception
+        unless result[:returncode]
+          exception = BigBlueButtonException.new(result[:message])
+          exception.key = result.has_key?(:messageKey) ? result[:messageKey] : ""
+          raise exception
+        end
       end
 
-      hash
+      result
     end
 
     protected