Class: BigBlueButton::BigBlueButtonApi

Inherits:
Object
  • Object
show all
Defined in:
lib/bigbluebutton_api.rb

Overview

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;

  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 .

Important info about the data returned by the methods:

  • 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 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)

    • :running (boolean)

    • :hasBeenForciblyEnded (boolean)

    • :endTime and :startTime (DateTime or nil)

For more information about the API, see the documentation at:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url, secret, version = nil, logger = nil, sha256 = false) ⇒ BigBlueButtonApi

Initializes an instance

url

URL to a BigBlueButton server (e.g. demo.bigbluebutton.org/bigbluebutton/api)

secret

Shared secret for this server

version

API version e.g. 0.81

logger

Logger object to log actions (so apps can use their own loggers)

sha256

Flag to use sha256 when hashing url contents for checksum



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/bigbluebutton_api.rb', line 74

def initialize(url, secret, version=nil, logger=nil, sha256=false)
  @supported_versions = ['0.8', '0.81', '0.9', '1.0']
  @url = url
  @secret = secret
  @timeout = 10         # default timeout for api requests
  @request_headers = {} # http headers sent in all requests
  @logger = logger
  @sha256 = sha256
  # If logger is not informed, it defaults to STDOUT with INFO level
  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)
    @logger.warn("BigBlueButtonAPI: detected unsupported version, using the closest one that is supported (#{@version})")
  end

  @logger.debug("BigBlueButtonAPI: Using version #{@version}")
end

Instance Attribute Details

#logger ⇒ Object

logger to log reponses and infos



56
57
58
 
# File 'lib/bigbluebutton_api.rb', line 56

def logger
  @logger
end

#request_headers ⇒ Object

HTTP headers to be sent in all GET/POST requests



62
63
64
 
# File 'lib/bigbluebutton_api.rb', line 62

def request_headers
  @request_headers
end

#secret ⇒ Object

Shared secret for this server



50
51
52
 
# File 'lib/bigbluebutton_api.rb', line 50

def secret
  @secret
end

#supported_versions ⇒ Object

Array with the version of BigBlueButton supported TODO: do we really need an accessor? shouldn’t be internal?



66
67
68
 
# File 'lib/bigbluebutton_api.rb', line 66

def supported_versions
  @supported_versions
end

#timeout ⇒ Object

Maximum wait time for HTTP requests (secs)



59
60
61
 
# File 'lib/bigbluebutton_api.rb', line 59

def timeout
  @timeout
end

#url ⇒ Object

URL to a BigBlueButton server (e.g. demo.bigbluebutton.org/bigbluebutton/api)



47
48
49
 
# File 'lib/bigbluebutton_api.rb', line 47

def url
  @url
end

#version ⇒ Object

API version e.g. 0.81



53
54
55
 
# File 'lib/bigbluebutton_api.rb', line 53

def version
  @version
end

Instance Method Details

#==(other) ⇒ Object

API’s are equal if all the following attributes are equal.



647
648
649
650
651
652
653
 
# File 'lib/bigbluebutton_api.rb', line 647

def ==(other)
  r = true
  [:url, :supported_versions, :secret, :version, :logger].each do |param|
    r = r && self.send(param) == other.send(param)
  end
  r
end

#check_url ⇒ Object 



641
642
643
644
 
# File 'lib/bigbluebutton_api.rb', line 641

def check_url
  url, data = get_url(:check)
  url
end

#create_meeting(meeting_name, meeting_id, options = {}, modules = nil) ⇒ Object

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)

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), 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. See usage examples below.

Example

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)

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.81

On successful creation:

{
  :returncode => true,
  :meetingID => "0c521f3d",
  :attendeePW => "12345",
  :moderatorPW => "54321",
  :createTime => 1389464535956,
  :hasBeenForciblyEnded => false,
  :messageKey => "",
  :message => ""
}

When creating a meeting that already exist:

{
  :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."
}



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/bigbluebutton_api.rb', line 167

def create_meeting(meeting_name, meeting_id, options={}, modules=nil)
  params = { :name => meeting_name, :meetingID => meeting_id }.merge(options)

  # :record is passed as string, but we accept boolean as well
  if params[:record] and !!params[:record] == params[:record]
    params[:record] = params[:record].to_s
  end

  # 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)
  end

  formatter = BigBlueButtonFormatter.new(response)
  formatter.to_string(:meetingID)
  formatter.to_string(:moderatorPW)
  formatter.to_string(:attendeePW)
  formatter.to_boolean(:hasBeenForciblyEnded)
  formatter.to_int(:createTime)

  response
end

#delete_recordings(recordIDs, options = {}) ⇒ Object

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"]
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 }



547
548
549
550
551
 
# File 'lib/bigbluebutton_api.rb', line 547

def delete_recordings(recordIDs, options={})
  recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
  params = { :recordID => recordIDs }.merge(options)
  send_api_request(:deleteRecordings, params)
end

#end_meeting(meeting_id, moderator_password, options = {}) ⇒ Object

Ends an existing meeting. Throws BigBlueButtonException on failure.

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.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."
}



209
210
211
212
 
# File 'lib/bigbluebutton_api.rb', line 209

def end_meeting(meeting_id, moderator_password, options={})
  params = { :meetingID => meeting_id, :password => moderator_password }.merge(options)
  send_api_request(:end, params)
end

#get_api_version ⇒ 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!



400
401
402
403
 
# File 'lib/bigbluebutton_api.rb', line 400

def get_api_version
  response = send_api_request(:index)
  response[:returncode] ? response[:version].to_s : ""
end

#get_available_layouts(config_xml = nil) ⇒ Object

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.



614
615
616
617
618
619
620
621
622
623
624
625
 
# File 'lib/bigbluebutton_api.rb', line 614

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

#get_default_config_xml(asObject = false, options = {}) ⇒ Object

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.



569
570
571
572
573
574
575
576
 
# File 'lib/bigbluebutton_api.rb', line 569

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

#get_default_layouts ⇒ Object

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 get_available_layouts.



630
631
632
633
 
# File 'lib/bigbluebutton_api.rb', line 630

def get_default_layouts
  # this is the list for BigBlueButton 0.81
  ["Default", "Video Chat", "Meeting", "Webinar", "Lecture assistant", "Lecture"]
end

#get_meeting_info(meeting_id, password, options = {}) ⇒ Object

Returns a hash object containing the information of a 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.81

Running with attendees and metadata:

{
  :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 => ""
}

Created but not started yet:

{
  :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 => ""
}



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/bigbluebutton_api.rb', line 310

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)
  response[:attendees].each { |a| BigBlueButtonFormatter.format_attendee(a) }

  formatter.to_string(:meetingID)
  formatter.to_string(:moderatorPW)
  formatter.to_string(:attendeePW)
  formatter.to_boolean(:hasBeenForciblyEnded)
  formatter.to_boolean(:running)
  formatter.to_datetime(:startTime)
  formatter.to_datetime(:endTime)
  formatter.to_int(:participantCount)
  formatter.to_int(:moderatorCount)
  formatter.to_string(:meetingName)
  formatter.to_int(:maxUsers)
  formatter.to_int(:voiceBridge)
  formatter.to_int(:createTime)
  formatter.to_boolean(:recording)

  response
end

#get_meetings(options = {}) ⇒ Object

Returns a hash object with information about all the meetings currently created in the server, either they are running or not.

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,
  :meetings => [
    { :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 => ""
}

Server with no meetings:

{
  :returncode => true,
  :meetings => [],
  :messageKey => "noMeetings",
  :message => "no meetings were found on this server"
}



388
389
390
391
392
393
394
395
 
# File 'lib/bigbluebutton_api.rb', line 388

def get_meetings(options={})
  response = send_api_request(:getMeetings, options)

  formatter = BigBlueButtonFormatter.new(response)
  formatter.flatten_objects(:meetings, :meeting)
  response[:meetings].each { |m| BigBlueButtonFormatter.format_meeting(m) }
  response
end

#get_recordings(options = {}) ⇒ Object

Retrieves the recordings that are available for playback for a given meetingID (or set of meeting IDs).

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

{ :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=125468758b24fa27551e7a065849dda3ce65dd32-1329872486268",
            :length => 64
          },
          { :type => "presentation",
            :url => "http://test-install.blindsidenetworks.com/presentation/slides/playback.html?meetingId=125468758b24fa27551e7a065849dda3ce65dd32-1329872486268",
            :length => 64
          }
        ]
      }
    },
    { :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
        }
      }
    }
  ]
}



468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/bigbluebutton_api.rb', line 468

def get_recordings(options={})
  # ["id1", "id2", "id3"] becomes "id1,id2,id3"
  if options.has_key?(:meetingID)
    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)
  formatter.flatten_objects(:recordings, :recording)
  response[:recordings].each { |r| BigBlueButtonFormatter.format_recording(r) }
  response
end

#get_url(method, params = {}) ⇒ Object

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



668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
 
# File 'lib/bigbluebutton_api.rb', line 668

def get_url(method, params={})
  if method == :index
    return @url, nil
  elsif method == :check
    baseurl = URI.join(@url, "/").to_s
    return "#{baseurl}check", nil
  end

  # 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}=" + URI.encode_www_form_component(v.to_s) unless k.nil? || v.nil? }.join("&")

  # checksum calc
  checksum_param = params_string + @secret
  checksum_param = method.to_s + checksum_param
  checksum = @sha256 ? Digest::SHA256.hexdigest(checksum_param) : Digest::SHA1.hexdigest(checksum_param)

  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

#is_meeting_running?(meeting_id, options = {}) ⇒ Boolean

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.

Returns:

  • (Boolean) 


220
221
222
223
224
 
# File 'lib/bigbluebutton_api.rb', line 220

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

#join_meeting_url(meeting_id, user_name, password, options = {}) ⇒ Object

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.



237
238
239
240
241
 
# File 'lib/bigbluebutton_api.rb', line 237

def join_meeting_url(meeting_id, user_name, password, options={})
  params = { :meetingID => meeting_id, :password => password, :fullName => user_name }.merge(options)
  url, data = get_url(:join, params)
  url
end

#last_http_response ⇒ Object

Returns the HTTP response object returned in the last API call.



656
657
658
 
# File 'lib/bigbluebutton_api.rb', line 656

def last_http_response
  @http_response
end

#last_xml_response ⇒ Object

Returns the XML returned in the last API call.



661
662
663
 
# File 'lib/bigbluebutton_api.rb', line 661

def last_xml_response
  @xml_response
end

#publish_recordings(recordIDs, publish, options = {}) ⇒ Object

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)

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 }



526
527
528
529
530
 
# File 'lib/bigbluebutton_api.rb', line 526

def publish_recordings(recordIDs, publish, options={})
  recordIDs = recordIDs.join(",") if recordIDs.instance_of?(Array) # ["id1", "id2"] becomes "id1,id2"
  params = { :recordID => recordIDs, :publish => publish.to_s }.merge(options)
  send_api_request(:publishRecordings, params)
end

#send_api_request(method, params = {}, data = nil, raw = false) ⇒ Object

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.

raw (boolean)

If true, returns the data as it was received. Will not parse it into a Hash, check for errors or throw exceptions.



714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
 
# File 'lib/bigbluebutton_api.rb', line 714

def send_api_request(method, params={}, data=nil, raw=false)
  # 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?
  @xml_response = @http_response.body

  if raw
    result = @xml_response
  else

    # 'Hashify' the XML
    result = BigBlueButtonHash.from_xml(@xml_response)

    # 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

  result
end

#set_config_xml(meeting_id, xml, options = {}) ⇒ Object

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.



593
594
595
596
597
598
599
600
601
602
 
# File 'lib/bigbluebutton_api.rb', line 593

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

#test_connection ⇒ Object

Make a simple request to the server to test the connection.



636
637
638
639
 
# File 'lib/bigbluebutton_api.rb', line 636

def test_connection
  response = send_api_request(:index)
  response[:returncode]
end

#update_recordings(recordIDs, meta = nil, options = {}) ⇒ Object

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 }



503
504
505
506
507
 
# File 'lib/bigbluebutton_api.rb', line 503

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