Merge pull request #189 from jitsi/dc_send_throw

Changes methods that use RTCDatachanel#send to throw exception on fail

JitsiConference.js

 };
 
 /**
- * Elects the participant with the given id to be the selected participant or the speaker.
- * @param id the identifier of the participant
+ * Elects the participant with the given id to be the selected participant in
+ * order to receive higher video quality (if simulcast is enabled).
+ * @param participantId the identifier of the participant
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
  */
 JitsiConference.prototype.selectParticipant = function(participantId) {
-    if (this.rtc) {
-        this.rtc.selectEndpoint(participantId);
-    }
+    this.rtc.selectEndpoint(participantId);
 };
 
 /**
- *
- * @param id the identifier of the participant
+ * Elects the participant with the given id to be the pinned participant in
+ * order to always receive video for this participant (even when last n is
+ * enabled).
+ * @param participantId the identifier of the participant
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
  */
 JitsiConference.prototype.pinParticipant = function(participantId) {
-    if (this.rtc) {
-        this.rtc.pinEndpoint(participantId);
-    }
+    this.rtc.pinEndpoint(participantId);
 };
 
 /**
  * @param to {string} the id of the endpoint that should receive the message.
  * If "" the message will be sent to all participants.
  * @param payload {object} the payload of the message.
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
  */
 JitsiConference.prototype.sendEndpointMessage = function (to, payload) {
-    if(this.rtc) {
-        this.rtc.sendDataChannelMessage(to, payload);
-    }
+    this.rtc.sendDataChannelMessage(to, payload);
 }
 
 /**
  * Sends broadcast message via the datachannels.
  * @param payload {object} the payload of the message.
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
  */
 JitsiConference.prototype.broadcastEndpointMessage = function (payload) {
     this.sendEndpointMessage("", payload);

doc/API.md

     - to - the id of the endpoint that should receive the message. If "" the message will be sent to all participants.
     - payload - JSON object - the payload of the message.
 
+Throws NetworkError or InvalidStateError or Error if the operation fails.
+
 32. broadcastEndpointMessage(payload) - Sends broadcast message via the datachannels.
     - payload - JSON object - the payload of the message.
 
+Throws NetworkError or InvalidStateError or Error if the operation fails.
+
+33. selectParticipant(participantId) - Elects the participant with the given id to be the selected participant in order to receive higher video quality (if simulcast is enabled).
+    - participantId - the identifier of the participant
+
+Throws NetworkError or InvalidStateError or Error if the operation fails.
+
+34. pinParticipant(participantId) - Elects the participant with the given id to be the pinned participant in order to always receive video for this participant (even when last n is enabled).
+    - participantId - the identifier of the participant
+
+Throws NetworkError or InvalidStateError or Error if the operation fails.
+
 JitsiTrack
 ======
 The object represents single track - video or audio. They can be remote tracks ( from the other participants in the call) or local tracks (from the devices of the local participant).

modules/RTC/DataChannels.js

         // we want the notification to trigger even if userJid is undefined,
         // or null.
         // XXX why do we not do the same for pinned endpoints?
-        self.sendSelectedEndpointMessage(self.selectedEndpoint);
+        try {
+            self.sendSelectedEndpointMessage(self.selectedEndpoint);
+        } catch (error) {
+            GlobalOnErrorHandler.callErrorHandler(error);
+            logger.error("Cannot sendSelectedEndpointMessage ",
+                self.selectedEndpoint, ". Error: ", error);
+        }
     };
 
     dataChannel.onerror = function (error) {
 
 /**
  * Sends a "selected endpoint changed" message via the data channel.
+ * @param endpointId {string} the id of the selected endpoint
+ * @throws NetworkError or InvalidStateError from RTCDataChannel#send (@see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send})
+ * or Error with "No opened data channels found!" message.
  */
 DataChannels.prototype.sendSelectedEndpointMessage = function (endpointId) {
     this.selectedEndpoint = endpointId;
 
 /**
  * Sends a "pinned endpoint changed" message via the data channel.
+ * @param endpointId {string} the id of the pinned endpoint
+ * @throws NetworkError or InvalidStateError from RTCDataChannel#send (@see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send})
+ * or Error with "No opened data channels found!" message.
  */
 DataChannels.prototype.sendPinnedEndpointMessage = function (endpointId) {
     this._onXXXEndpointChanged("pinnned", endpointId);
  * @param xxx the name of the endpoint-related property whose value changed
  * @param userResource the new value of the endpoint-related property after the
  * change
+ * @throws NetworkError or InvalidStateError from RTCDataChannel#send (@see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send})
+ * or Error with "No opened data channels found!" message.
  */
 DataChannels.prototype._onXXXEndpointChanged = function (xxx, userResource) {
     // Derive the correct words from xxx such as selected and Selected, pinned
 
     // Notify Videobridge about the specified endpoint change.
     logger.log(lower + ' endpoint changed: ', userResource);
-
 };
 
 DataChannels.prototype._some = function (callback, thisArg) {
 /**
  * Sends passed object via the first found open datachannel
  * @param jsonObject {object} the object that will be sent
+ * @throws NetworkError or InvalidStateError from RTCDataChannel#send (@see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send})
+ * or Error with "No opened data channels found!" message.
  */
 DataChannels.prototype.send = function (jsonObject) {
-    this._some(function (dataChannel) {
+    if(!this._some(function (dataChannel) {
         if (dataChannel.readyState == 'open') {
-            try {
-                // Can throw NetworkError and InvalidStateError. We
-                // shouldn't be experiencing InvalidStateError. But NetworkError
-                // is easily reproducable when start leaving the conference.
-                // I cannot reproduce it in any other use cases and for this one
-                // we can safely ignore the error and just report it to the
-                // global error handler. If we notice this error during the
-                // conference maybe it's better to throw it to the user of the
-                // library in order to notify the caller of the method for
-                // the failure.
                 dataChannel.send(JSON.stringify(jsonObject));
-            } catch (error) {
-                GlobalOnErrorHandler.callErrorHandler(error);
-                logger.error("Cannot send ", jsonObject, ". Error: ", error);
-            }
             return true;
         }
-    });
+    })) {
+        throw new Error("No opened data channels found!");
+    }
 }
 
 /**
  * @param to {string} the id of the endpoint that should receive the message.
  * If "" the message will be sent to all participants.
  * @param payload {object} the payload of the message.
+ * @throws NetworkError or InvalidStateError from RTCDataChannel#send (@see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel/send})
+ * or Error with "No opened data channels found!" message.
  */
 DataChannels.prototype.sendDataChannelMessage = function (to, payload) {
     this.send({

modules/RTC/RTC.js

             this.eventEmitter);
 };
 
+/**
+ * Elects the participant with the given id to be the pinned participant in
+ * order to always receive video for this participant (even when last n is
+ * enabled).
+ * @param id {string} the user id.
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
+*/
 RTC.prototype.selectEndpoint = function (id) {
-    if(this.dataChannels)
+    if(this.dataChannels) {
         this.dataChannels.sendSelectedEndpointMessage(id);
+    } else {
+        throw new Error("Data channels support is disabled!");
+    }
 };
 
+/**
+ * Elects the participant with the given id to be the pinned participant in
+ * order to always receive video for this participant (even when last n is
+ * enabled).
+ * @param id {string} the user id
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
+ */
 RTC.prototype.pinEndpoint = function (id) {
-    if(this.dataChannels)
+    if(this.dataChannels) {
         this.dataChannels.sendPinnedEndpointMessage(id);
+    } else {
+        throw new Error("Data channels support is disabled!");
+    }
 };
 
 RTC.prototype.addListener = function (type, listener) {
  * @param to {string} the id of the endpoint that should receive the message.
  * If "" the message will be sent to all participants.
  * @param payload {object} the payload of the message.
+ * @throws NetworkError or InvalidStateError or Error if the operation fails.
  */
 RTC.prototype.sendDataChannelMessage = function (to, payload) {
     if(this.dataChannels) {
         this.dataChannels.sendDataChannelMessage(to, payload);
+    } else {
+        throw new Error("Data channels support is disabled!");
     }
 }