Merge branch 'master' into add-user-custom-properties

bigbluebutton-client/resources/prod/lib/bbb_api_bridge.js

@@ -1,3 +1,19 @@
+/**
+  This file contains the BigBlueButton client APIs that will allow 3rd-party applications
+  to embed the Flash client and interact with it through Javascript.
+  
+  HOW TO USE:
+     Some APIs allow synchronous and asynchronous calls. When using asynchronous, the 3rd-party
+     JS should register as listener for events listed at the bottom of this file. For synchronous,
+     3rd-party JS should pass in a callback function when calling the API.
+  
+  For an example on how to use these APIs, see: 
+  
+    https://github.com/bigbluebutton/bigbluebutton/blob/master/bigbluebutton-client/resources/prod/lib/3rd-party.js
+    https://github.com/bigbluebutton/bigbluebutton/blob/master/bigbluebutton-client/resources/prod/3rd-party.html
+  
+*/
+
 (function(window, undefined) {
 
     var BBB = {};
@@ -13,7 +29,14 @@
     }
 
      /**
-     * Get info if user is sharing webcam.
+     * Query if the current user is sharing webcam.
+     *
+     * Param:
+     *   callback - function to return the result
+     *
+     * If you want to instead receive an event with the result, register a listener
+     * for AM_I_SHARING_CAM_RESP (see below).
+     *
      */  
     BBB.amISharingWebcam = function(callback) {
       var swfObj = getSwfObj();
@@ -29,7 +52,13 @@
     }
     
     /**
-     * Get my user info.
+     * Query if another user is sharing her camera.
+     * 
+     * Param:
+     *   userID : the id of the user that may be sharing the camera
+     *   callback: function if you want to be informed synchronously. Don't pass a function
+     *             if you want to be informed through an event. You have to register for
+     *             IS_USER_PUBLISHING_CAM_RESP (see below).
      */  
     BBB.isUserSharingWebcam = function(userID, callback) {
       var swfObj = getSwfObj();
@@ -44,6 +73,16 @@
       }
     }
     
+    /**
+     * Issue a switch presenter command.
+     *
+     * Param:
+     *   newPresenterUserID - the user id of the new presenter
+     *
+     * 3rd-party JS must listen for SWITCHED_PRESENTER (see below) to get notified
+     * of switch presenter events.
+     * 
+     */
     BBB.switchPresenter = function(newPresenterUserID) {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -53,10 +92,11 @@
     }
 
     /**
-     * Query the Flash client if user is presenter.
+     * Query if current user is presenter.
+     *
      * Params:
      *    callback - function if you want a callback as response. Otherwise, you need to listen
-     *               for the response as an event.
+     *               for AM_I_PRESENTER_RESP (see below).
      */
     BBB.amIPresenter = function(callback) {
       var swfObj = getSwfObj();
@@ -70,7 +110,13 @@
         }
       }
     }
-    
+
+    /**
+     * Query who is presenter.
+     *
+     * Params:
+     *    callback - function that gets executed for the response.
+     */    
     BBB.getPresenterUserID = function(callback) {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -81,10 +127,10 @@
     }
             
     /**
-     * Query the Flash client for the user's role.
+     * Query the current user's role.
      * Params:
      *    callback - function if you want a callback as response. Otherwise, you need to listen
-     *               for the response as an event.
+     *               for GET_MY_ROLE_RESP (see below).
      */
     BBB.getMyRole = function(callback) {
       var swfObj = getSwfObj();
@@ -100,8 +146,11 @@
     }
 
     /**
-     * Get external userID.
+     * Query the current user's id.
-     */  
+     *
+     * Params:
+     *    callback - function that gets executed for the response.
+     */
     BBB.getMyUserID = function(callback) {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -112,9 +161,12 @@
       }
     }
  
-     /**
+    /**
-     * Get my user info.
+     * Query the current user's role.
-     */  
+     * Params:
+     *    callback - function if you want a callback as response. Otherwise, you need to listen
+     *               for GET_MY_ROLE_RESP (see below).
+     */
     BBB.getMyUserInfo = function(callback) {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -129,8 +181,11 @@
     }
        
     /**
-     * Get external meetingID.
+     * Query the meeting id.
-     */  
+     *
+     * Params:
+     *    callback - function that gets executed for the response.
+     */ 
     BBB.getMeetingID = function(callback) {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -152,6 +207,9 @@
       }
     }
     
+    /**
+     * Leave the voice conference.
+     */  
     BBB.leaveVoiceConference = function() {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -162,6 +220,9 @@
     
     /**
      * Share user's webcam.
+     * 
+     * Params:
+     *   publishInClient : (DO NOT USE - Unimplemented)
      */    
     BBB.shareVideoCamera = function(publishInClient) {
       var swfObj = getSwfObj();
@@ -174,34 +235,54 @@
       }
     }
 
+    /**
+     * Stop share user's webcam.
+     * 
+     */    
     BBB.stopSharingCamera = function() {
       var swfObj = getSwfObj();
       if (swfObj) {
         swfObj.stopShareCameraRequest();
       }    
     }
-    
+
+    /**
+     * Mute the current user.
+     * 
+     */      
     BBB.muteMe = function() {
       var swfObj = getSwfObj();
       if (swfObj) {
         swfObj.muteMeRequest(); 
       }
     }
-    
+
+    /**
+     * Unmute the current user.
+     * 
+     */        
     BBB.unmuteMe = function() {
       var swfObj = getSwfObj();
       if (swfObj) {
         swfObj.unmuteMeRequest(); 
       }
     }
-    
+
+    /**
+     * Mute all the users.
+     * 
+     */       
     BBB.muteAll = function() {
       var swfObj = getSwfObj();
       if (swfObj) {
         swfObj.muteAllUsersRequest(); 
       }
     }
-    
+
+    /**
+     * Unmute all the users.
+     * 
+     */      
     BBB.unmuteAll = function() {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -209,13 +290,26 @@
       }
     }
     
+    /**
+     * Switch to a new layout.
+     *
+     * Param:
+     *  newLayout : name of the layout as defined in layout.xml (found in /var/www/bigbluebutton/client/conf/layout.xml)
+     * 
+     */
     BBB.switchLayout = function(newLayout) {
       var swfObj = getSwfObj();
       if (swfObj) {
         swfObj.switchLayout(newLayout);
       }
     }
-    
+
+    /**
+     * Lock the layout.
+     *
+     * Locking the layout means that users will have the same layout with the moderator that issued the lock command.
+     * Other users won't be able to move or resize the different windows.
+     */    
     BBB.lockLayout = function(lock) {
       var swfObj = getSwfObj();
       if (swfObj) {
@@ -251,17 +345,21 @@
         swfObj.sendPrivateChatRequest(fontColor, localeLang, message, toUserID);
       }    
     }
-    
+        
+    // Third-party JS apps should use this to query if the BBB SWF file is ready to handle calls.
+    BBB.isSwfClientReady = function() {
+      return swfReady;
+    }
         
     /* ***********************************************************************************
      *       Broadcasting of events to 3rd-party apps.
      *************************************************************************************/
     
-    /** Stores the event listeners ***/ 
+    /** Stores the 3rd-party app event listeners ***/ 
     var listeners = {};
 
     /**
-     * Register to listen for events.
+     * 3rd-party apps should user this method to register to listen for events.
      */
     BBB.listen = function(eventName, handler) {
         if (typeof listeners[eventName] === 'undefined')
@@ -271,7 +369,7 @@
     };
 
     /**
-     * Unregister listener for event.
+     * 3rd-party app should use this method to unregister listener for a given event.
      */
     BBB.unlisten = function(eventName, handler) {
         if (!listeners[eventName])
@@ -286,7 +384,7 @@
     };
 
     /**
-     * Private function to broadcast received event from Flash client to
+     * Private function to broadcast received event from the BigBlueButton Flash client to
      * 3rd-parties.
      */
     function broadcast(bbbEvent) {
@@ -302,12 +400,51 @@
     };
 
     /**
-     * Function called by the Flash client to inform 3rd-parties of internal events.
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+     * NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE!
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+     *
+     *   DO NOT CALL THIS METHOD FROM YOUR JS CODE.
+     *
+     * This is called by the BigBlueButton Flash client to inform 3rd-parties of internal events.
+     *
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+     * NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE!
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=     
      */
     BBB.handleFlashClientBroadcastEvent = function (bbbEvent) {
       console.log("Received [" + bbbEvent.eventName + "]");
       broadcast(bbbEvent);
     }
+
+    
+    // Flag to indicate that the SWF file has been loaded and ready to handle calls.
+    var swfReady = false;
+
+    /**
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+     * NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE!
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+     *
+     *   DO NOT CALL THIS METHOD FROM YOUR JS CODE.
+     *
+     * This is called by the BigBlueButton Flash client to inform 3rd-parties that it is ready.
+     *
+     * WARNING:
+     *   Doesn't actually work as intended. The Flash client calls this function when it's loaded.
+     *   However, the client as to query the BBB server to get the status of the meeting.
+     *   We're working on the proper way to determining that the client is TRULY ready.
+     *
+     *   !!! As a workaround, 3rd-party JS on init should call getUserInfo until it return NOT NULL.
+     *
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+     * NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE! NOTE!
+     * =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=     
+     */    
+    BBB.swfClientIsReady = function () {
+      console.log("BigBlueButton SWF is ready.");
+      swfReady = true;
+    }
     
    /* ********************************************************************* */
 
@@ -315,17 +452,6 @@
       callback;
     }
     
-    // Flag to indicate that the SWF file has been loaded and ready to handle calls.
-    var swfReady = false;
-    BBB.swfClientIsReady = function () {
-      console.log("BigBlueButton SWF is ready.");
-      swfReady = true;
-    }
-    
-    // Third-party JS apps should use this to query if the BBB SWF file is ready to handle calls.
-    BBB.isSwfClientReady = function() {
-      return swfReady;
-    }
      
     /************************************************
      * EVENT NAME CONSTANTS
@@ -333,27 +459,30 @@
      * See https://github.com/bigbluebutton/bigbluebutton/blob/master/bigbluebutton-client/src/org/bigbluebutton/core/EventConstants.as
      *
      ************************************************/
-    var GET_MY_ROLE_RESP           = 'GetMyRoleResponse';
+    var GET_MY_ROLE_RESP            = 'GetMyRoleResponse';
-    var AM_I_PRESENTER_RESP        = 'AmIPresenterQueryResponse';
+    var AM_I_PRESENTER_RESP         = 'AmIPresenterQueryResponse';
-    var AM_I_SHARING_CAM_RESP      = 'AmISharingCamQueryResponse';
+    var AM_I_SHARING_CAM_RESP       = 'AmISharingCamQueryResponse';
-    var BROADCASTING_CAM_STARTED   = 'BroadcastingCameraStartedEvent';
+    var BROADCASTING_CAM_STARTED    = 'BroadcastingCameraStartedEvent';
-    var BROADCASTING_CAM_STOPPED   = 'BroadcastingCameraStoppedEvent';
+    var BROADCASTING_CAM_STOPPED    = 'BroadcastingCameraStoppedEvent';
-    var I_AM_SHARING_CAM           = 'IAmSharingCamEvent';
+    var I_AM_SHARING_CAM            = 'IAmSharingCamEvent';
-    var CAM_STREAM_SHARED          = 'CamStreamSharedEvent';
+    var CAM_STREAM_SHARED           = 'CamStreamSharedEvent';
-    var USER_JOINED                = 'UserJoinedEvent';
+    var USER_JOINED                 = 'UserJoinedEvent';
-    var USER_LEFT                  = 'UserLeftEvent';
+    var USER_LEFT                   = 'UserLeftEvent';
-    var SWITCHED_PRESENTER         = 'SwitchedPresenterEvent';
+    var SWITCHED_PRESENTER          = 'SwitchedPresenterEvent';
-    var NEW_PRIVATE_CHAT           = 'NewPrivateChatEvent';
+    var NEW_ROLE                    = 'NewRoleEvent';
-    var NEW_PUBLIC_CHAT            = 'NewPublicChatEvent';
+    var NEW_PRIVATE_CHAT            = 'NewPrivateChatEvent';
-    var SWITCHED_LAYOUT            = 'SwitchedLayoutEvent';
+    var NEW_PUBLIC_CHAT             = 'NewPublicChatEvent';
-    var REMOTE_LOCKED_LAYOUT       = 'RemoteLockedLayoutEvent';
+    var SWITCHED_LAYOUT             = 'SwitchedLayoutEvent';
-    var REMOTE_UNLOCKED_LAYOUT     = 'RemoteUnlockedLayoutEvent';
+    var REMOTE_LOCKED_LAYOUT        = 'RemoteLockedLayoutEvent';
-    var USER_JOINED_VOICE          = 'UserJoinedVoiceEvent';
+    var REMOTE_UNLOCKED_LAYOUT      = 'RemoteUnlockedLayoutEvent';
-    var USER_LEFT_VOICE            = 'UserLeftVoiceEvent';
+    var USER_JOINED_VOICE           = 'UserJoinedVoiceEvent';
-    var USER_MUTED_VOICE           = 'UserVoiceMutedEvent';
+    var USER_LEFT_VOICE             = 'UserLeftVoiceEvent';
-    var USER_TALKING               = 'UserTalkingEvent';
+    var USER_MUTED_VOICE            = 'UserVoiceMutedEvent';
-    var USER_LOCKED_VOICE          = 'UserLockedVoiceEvent';
+    var USER_TALKING                = 'UserTalkingEvent';
-    var START_PRIVATE_CHAT         = 'StartPrivateChatEvent';
+    var USER_LOCKED_VOICE           = 'UserLockedVoiceEvent';
+    var START_PRIVATE_CHAT          = "StartPrivateChatEvent";
+    var GET_MY_USER_INFO_REP        = "GetMyUserInfoResponse";
+    var IS_USER_PUBLISHING_CAM_RESP  = "IsUserPublishingCamResponse";
            
     window.BBB = BBB;
 })(this);

bigbluebutton-client/src/org/bigbluebutton/main/api/ExternalApiCalls.as

@@ -174,7 +174,7 @@ package org.bigbluebutton.main.api
     public function handleGetMyRoleResponse(event:CoreEvent):void {
       var payload:Object = new Object();
       payload.eventName = EventConstants.GET_MY_ROLE_RESP;
-      payload.myRole = event.message.myRole;
+      payload.myRole = UserManager.getInstance().getConference().whatsMyRole();
       broadcastEvent(payload);        
     }