feat(conference): expose method to select multiple participants (#784)

* feat(conference): expose method to select multiple participants

* squash: fix typo

* squash: reduce to one code flow

* squash: default to empty array to mimic previous null default

* squash: fix typos, change docs, default params

* squash: remove defaults

* squash: update comment about array arg

JitsiConference.js

  * Or cache it if channel is not created and send it once channel is available.
  * @param participantId the identifier of the participant
  * @throws NetworkError or InvalidStateError or Error if the operation fails.
+ * @returns {void}
  */
 JitsiConference.prototype.selectParticipant = function(participantId) {
-    this.rtc.selectEndpoint(participantId);
+    this.selectParticipants([ participantId ]);
+};
+
+/*
+ * Elects participants with given ids to be the selected participants in order
+ * to receive higher video quality (if simulcast is enabled). The argument
+ * should be an array of participant id strings or an empty array; an error will
+ * be thrown if a non-array is passed in. The error is thrown as a layer of
+ * protection against passing an invalid argument, as the error will happen in
+ * the bridge and may not be visible in the client.
+ *
+ * @param {Array<strings>} participantIds - An array of identifiers for
+ * participants.
+ * @returns {void}
+ */
+JitsiConference.prototype.selectParticipants = function(participantIds) {
+    if (!Array.isArray(participantIds)) {
+        throw new Error('Invalid argument; participantIds must be an array.');
+    }
+
+    this.rtc.selectEndpoints(participantIds);
 };
 
 /**

modules/RTC/BridgeChannel.js

     }
 
     /**
-     * Sends a "selected endpoint changed" message via the channel.
-     * @param {string} endpointId The id of the selected endpoint.
+     * Sends a "selected endpoints changed" message via the channel.
+     *
+     * @param {Array<string>} endpointIds - The ids of the selected endpoints.
      * @throws NetworkError or InvalidStateError from RTCDataChannel#send (@see
      * {@link https://developer.mozilla.org/docs/Web/API/RTCDataChannel/send})
      * or from WebSocket#send or Error with "No opened channel" message.
      */
-    sendSelectedEndpointMessage(endpointId) {
+    sendSelectedEndpointsMessage(endpointIds) {
         logger.log(
-            'sending selected changed notification to the bridge for endpoint ',
-            endpointId);
+            'sending selected changed notification to the bridge for endpoints',
+            endpointIds);
 
         this._send({
-            colibriClass: 'SelectedEndpointChangedEvent',
-            selectedEndpoint: endpointId || null
+            colibriClass: 'SelectedEndpointsChangedEvent',
+            selectedEndpoints: endpointIds
         });
     }
 

modules/RTC/RTC.js

         this._pinnedEndpoint = null;
 
         /**
-         * The endpoint ID of currently selected participant or <tt>null</tt> if
-         * no user is selected.
-         * @type {string|null}
+         * The endpoint IDs of currently selected participants.
+         *
+         * @type {Array}
          * @private
          */
-        this._selectedEndpoint = null;
+        this._selectedEndpoints = [];
 
         // The last N change listener.
         this._lastNChangeListener = this._onLastNChanged.bind(this);
             try {
                 this._channel.sendPinnedEndpointMessage(
                     this._pinnedEndpoint);
-                this._channel.sendSelectedEndpointMessage(
-                    this._selectedEndpoint);
+                this._channel.sendSelectedEndpointsMessage(
+                    this._selectedEndpoints);
 
                 if (typeof this._maxFrameHeight !== 'undefined') {
                     this._channel.sendReceiverVideoConstraintMessage(
     }
 
     /**
-     * Elects the participant with the given id to be the selected participant
-     * in order to always receive video for this participant (even when last n
-     * is enabled).
-     * If there is no channel we store it and send it through the channel once
-     * it is created.
-     * @param {string} id The user id.
+     * Elects the participants with the given ids to be the selected
+     * participants in order to always receive video for this participant (even
+     * when last n is enabled). If there is no channel we store it and send it
+     * through the channel once it is created.
+     *
+     * @param {Array<string>} ids - The user ids.
      * @throws NetworkError or InvalidStateError or Error if the operation
      * fails.
+     * @returns {void}
      */
-    selectEndpoint(id) {
-        // Cache the value if channel is missing, till we open it.
-        this._selectedEndpoint = id;
+    selectEndpoints(ids) {
+        this._selectedEndpoints = ids;
+
         if (this._channel && this._channelOpen) {
-            this._channel.sendSelectedEndpointMessage(id);
+            this._channel.sendSelectedEndpointsMessage(ids);
         }
     }