File: source/room-connection.js

/**
 * Function that starts the Room session.
 * @method joinRoom
 * @param {String} [room] The Room name.
 * - When not provided or is provided as an empty string, its value is the <code>options.defaultRoom</code>
 *   provided in the <a href="#method_init"><code>init()</code> method</a>.
 *   <small>Note that if you are using credentials based authentication, you cannot switch the Room
 *   that is not the same as the <code>options.defaultRoom</code> defined in the
 *   <a href="#method_init"><code>init()</code> method</a>.</small>
 * @param {JSON} [options] The Room session configuration options.
 * @param {JSON|String} [options.userData] The User custom data.
 *   <small>This can be set after Room session has started using the
 *   <a href="#method_setUserData"><code>setUserData()</code> method</a>.</small>
 * @param {Boolean} [options.useExactConstraints] The <a href="#method_getUserMedia"><code>getUserMedia()</code>
 *   method</a> <code>options.useExactConstraints</code> parameter settings.
 *   <small>See the <code>options.useExactConstraints</code> parameter in the
 *   <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a> for more information.</small>
 * @param {Boolean|JSON} [options.audio] The <a href="#method_getUserMedia"><code>getUserMedia()</code>
 *   method</a> <code>options.audio</code> parameter settings.
 *   <small>When value is defined as <code>true</code> or an object, <a href="#method_getUserMedia">
 *   <code>getUserMedia()</code> method</a> to be invoked to retrieve new Stream. If
 *   <code>options.video</code> is not defined, it will be defined as <code>false</code>.</small>
 *   <small>Object signature matches the <code>options.audio</code> parameter in the
 *   <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>.</small>
 * @param {Boolean|JSON} [options.video] The <a href="#method_getUserMedia"><code>getUserMedia()</code>
 *   method</a> <code>options.video</code> parameter settings.
 *   <small>When value is defined as <code>true</code> or an object, <a href="#method_getUserMedia">
 *   <code>getUserMedia()</code> method</a> to be invoked to retrieve new Stream. If
 *   <code>options.audio</code> is not defined, it will be defined as <code>false</code>.</small>
 *   <small>Object signature matches the <code>options.video</code> parameter in the
 *   <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>.</small>
 * @param {Boolean} [options.voiceActivityDetection=true] The flag if voice activity detection should be enabled.
 *   <small>This can only be toggled if User is and for the offerer, which is determined if User's
 *   <code>peerInfo.config.priorityWeight</code> is higher than Peer's.</small>
 *   <blockquote class="details">
 *   This works hand-in-hand with the <code>options.disableComfortNoiseCodec</code> flag in the
 *   <a href="#method_init"><code>init()</code> method</a> and the <code>options.audio.usedtx</code> setting in
 *   <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>. VAD (voice activity detection)
 *   detects if there is an active voice in the Stream, and if there is no active voice in the Stream, the
 *   <code>options.audio.usedtx</code> (if enabled) would prevent sending these empty bits. To prevent huge differences
 *   when there is a silence and an active voice later, the CN codec would produce an empty voice to
 *   make it sound better.</blockquote>
 * @param {JSON} [options.bandwidth] <blockquote class="info">Note that this is currently not supported
 *   with Firefox browsers versions 48 and below as noted in an existing
 *   <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=976521#c21">bugzilla ticket here</a>.</blockquote>
 *   The configuration to set the maximum streaming bandwidth to send to Peers. You can also use the preconfigured 
 *   constant <a href="#attr_VIDEO_QUALITY"><code>VIDEO_QUALITY</code></a> for recommended values.
 * @param {Number} [options.bandwidth.audio] The maximum audio streaming bandwidth sent to Peers in kbps.
 *   <small>Recommended values are <code>50</code> to <code>200</code>. <code>50</code> is sufficient enough for
 *   an audio call. The higher you go if you want clearer audio and to be able to hear music streaming.</small>
 * @param {Number} [options.bandwidth.video] The maximum video streaming bandwidth sent to Peers.
 *   <small>Recommended values are <code>256</code>-<code>500</code> for 180p quality,
 *   <code>500</code>-<code>1024</code> for 360p quality, <code>1024</code>-<code>2048</code> for 720p quality
 *   and <code>2048</code>-<code>4096</code> for 1080p quality.</small>
 * @param {Number} [options.bandwidth.data] The maximum data streaming bandwidth sent to Peers.
 *   <small>This affects the P2P messaging in <a href="#method_sendP2PMessage"><code>sendP2PMessage()</code> method</a>,
 *   and data transfers in <a href="#method_sendBlobData"><code>sendBlobData()</code> method</a> and
 *   <a href="#method_sendURLData"><code>sendURLData()</code> method</a>.</small>
 * @param {JSON} [options.googleXBandwidth] <blockquote class="info">Note that this is an experimental configuration
 *   and may cause disruptions in connections or connectivity issues when toggled, or may not work depending on
 *   browser supports. Currently, this only toggles the video codec bandwidth configuration.</blockquote>
 *   The configuration to set the experimental google video streaming bandwidth sent to Peers.
 *   <small>Note that Peers may override the "receive from" streaming bandwidth depending on the Peers configuration.</small>
 * @param {Number} [options.googleXBandwidth.min] The minimum experimental google video streaming bandwidth sent to Peers.
 *   <small>This toggles the <code>"x-google-min-bitrate"</code> flag in the session description.</small>
 * @param {Number} [options.googleXBandwidth.max] The maximum experimental google video streaming bandwidth sent to Peers.
 *   <small>This toggles the <code>"x-google-max-bitrate"</code> flag in the session description.</small>
 * @param {Boolean} [options.manualGetUserMedia] The flag if <code>joinRoom()</code> should trigger
 *   <a href="#event_mediaAccessRequired"><code>mediaAccessRequired</code> event</a> in which the
 *   <a href="#method_getUserMedia"><code>getUserMedia()</code> Stream</a> or
 *   <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a>
 *   must be retrieved as a requirement before Room session may begin.
 *   <small>This ignores the <code>options.audio</code> and <code>options.video</code> configuration.</small>
 *   <small>After 30 seconds without any Stream retrieved, this results in the `callback(error, ..)` result.</small>
 * @param {JSON} [options.sdpSettings] <blockquote class="info">
 *   Note that this is mainly used for debugging purposes and that it is an experimental flag, so
 *   it may cause disruptions in connections or connectivity issues when toggled. Note that it might not work
 *   with MCU enabled Peer connections or break MCU enabled Peer connections.</blockquote>
 *   The configuration to set the session description settings.
 * @param {JSON} [options.sdpSettings.connection] The configuration to set the session description connection settings.
 *   <small>Note that this configuration may disable the media streaming and these settings will be enabled for
 *   MCU server Peer connection regardless of the flags configured.</small>
 * @param {Boolean} [options.sdpSettings.connection.audio=true] The configuration to enable audio session description connection.
 * @param {Boolean} [options.sdpSettings.connection.video=true] The configuration to enable video session description connection.
 * @param {Boolean} [options.sdpSettings.connection.data=true] The configuration to enable Datachannel session description connection.
 * @param {JSON} [options.sdpSettings.direction] The configuration to set the session description connection direction
 *   to enable or disable uploading and downloading audio or video media streaming.
 *   <small>Note that this configuration does not prevent RTCP packets from being sent and received.</small>
 * @param {JSON} [options.sdpSettings.direction.audio] The configuration to set the session description
 *   connection direction for audio streaming.
 * @param {Boolean} [options.sdpSettings.direction.audio.send=true] The flag if uploading audio streaming
 *   should be enabled when available.
 * @param {Boolean} [options.sdpSettings.direction.audio.receive=true] The flag if downloading audio
 *   streaming should be enabled when available.
 * @param {JSON} [options.sdpSettings.direction.video] The configuration to set the session description
 *   connection direction for video streaming.
 * @param {Boolean} [options.sdpSettings.direction.video.send=true] The flag if uploading video streaming
 *   should be enabled when available.
 * @param {Boolean} [options.sdpSettings.direction.video.receive=true] The flag if downloading video streaming
 *   should be enabled when available.
 * @param {JSON|Boolean} [options.publishOnly] <blockquote class="info">
 *   For MCU enabled Peer connections, defining this flag would make Peer not know other Peers presence in the Room.<br>
 *   For non-MCU enable Peer connections, defining this flag would cause other Peers in the Room to
 *   not to send Stream to Peer, and overrides the config
 *   <code>options.sdpSettings.direction.audio.receive</code> value to <code>false</code>,
 *   <code>options.sdpSettings.direction.video.receive</code> value to <code>false</code>,
 *   <code>options.sdpSettings.direction.video.send</code> value to <code>true</code> and
 *   <code>options.sdpSettings.direction.audio.send</code> value to <code>true</code>.<br>
 *   Note that this feature is currently is beta, and for any enquiries on enabling and its support for MCU enabled
 *   Peer connections, please  contact <a href="http://support.temasys.io">our support portal</a>.<br><br>
 *   How does the publish only functionality work? Imagine several Skylink instances like A1, B1, C1 and A1
 *   opening a new instance A2 with publish only enabled with configured A1 as parent.<br><br>
 *   <table class="table"><thead>
 *   <tr><th></th><th colspan="2">MCU enabled room</th><th colspan="2">MCU disabled room</th></tr>
 *   <tr><th></th><th>Presence</th><th>Stream</th><th>Presence</th><th>Stream</th></tr></thead><tbody>
 *   <tr><th>A1</th><td>B1, C1</td><td>B1, C1</td><td>B1, C1</td><td>B1, C1</td></tr>
 *   <tr><th>B1</th><td>A1, C1, A2</td><td>A1, C1, A2</td><td>A1, C1, A2</td><td>A1, C1, A2</td></tr>
 *   <tr><th>C1</th><td>B1, C1, A2</td><td>B1, C1, A2</td><td>B1, C1, A2</td><td>B1, C1, A2</td></tr>
 *   <tr><th>A2</th><td></td><td></td><td>B1, C1</td><td></td></tr></tbody></table>
 *   Parent and child will not receive each other presence and stream because they are related to each other in the same client page,
 *   hence no uploading or downloading is required. If A2 did not configure A1 as the parent, A1 will receive A2.</blockquote>
 *   The config if Peer would publish only.
 * @param {String} [options.publishOnly.parentId] <blockquote class="info"><b>Deprecation Warning!</b>
 *   This property has been deprecated. Use <code>options.parentId</code> instead.
 *   </blockquote> The parent Peer ID to match to when Peer is connected.
 *   <small>This is useful for identification for users connecting the Room twice simultaneously for multi-streaming.</small>
 *   <small>If User Peer ID matches the parent Peer ID provided from Peer, User will not be connected to Peer.
 *   Parent will not be connected to (or receive the presence of) child, so will child will not be connected to
 *   (or receive the presence of) parent.</small>
 * @param {String} [options.parentId] The parent Peer ID to match to when Peer is connected.
 *   <small>Note that configuring this value overrides the <code>options.publishOnly.parentId</code> value.</small>
 *   <small>This is useful for identification for users connecting the Room twice simultaneously for multi-streaming.</small>
 *   <small>If User Peer ID matches the parent Peer ID provided from Peer, User will not be connected to Peer.
 *   Parent will not be connected to (or receive the presence of) child, so will child will not be connected to
 *   (or receive the presence of) parent.</small>
 * @param {JSON} [options.peerConnection] <blockquote class="info">
 *   Note that this is mainly used for debugging purposes, so it may cause disruptions in connections or
 *   connectivity issues when configured. </blockquote> The Peer connection constraints settings.
 * @param {String} [options.peerConnection.bundlePolicy] The Peer connection media bundle policy.
 * - When not provided, its value is <code>BALANCED</code>.
 *   [Rel: Skylink.BUNDLE_POLICY]
 * @param {String} [options.peerConnection.rtcpMuxPolicy] The Peer connection RTP and RTCP ICE candidates mux policy.
 * - When not provided, its value is <code>REQUIRE</code>.
 *   [Rel: Skylink.RTCP_MUX_POLICY]
 * @param {Number} [options.peerConnection.iceCandidatePoolSize=0] The number of ICE candidates to gather before
 *   gathering it when setting local offer / answer session description.
 * @param {String} [options.peerConnection.certificate] The type of certificate that Peer connection should
 *   generate and use when available.
 * - When not provided, its value is <code>AUTO</code>.
 *   [Rel: Skylink.PEER_CERTIFICATE]
 * @param {String} [options.peerConnection.disableBundle=false] The flag if for each Peer connection instead of bundling all
 *   media connections into 1 connection, should have all of them negotiated as different separate media connections.
 * @param {Boolean|JSON} [options.autoBandwidthAdjustment=false] <blockquote class="info">
 *   Note that this is an experimental feature which may be removed or changed in the future releases.
 *   This feature is also only available for non-MCU enabled Peer connections and Edge Peer connections.
 *   </blockquote> The flag if Peer connections uploading and downloading bandwidth should be automatically adjusted
 *   each time based on a specified interval.
 *   <small>Note this would cause <a href="#event_peerRestart"><code>peerRestart</code> event</a> to be triggered
 *   for each specified interval.</small>
 * @param {Number} [options.autoBandwidthAdjustment.interval=10] The interval each time to adjust bandwidth
 *   connections in seconds.
 *   <small>Note that the minimum value is <code>10</code>.</small>
 * @param {Number} [options.autoBandwidthAdjustment.limitAtPercentage=100] The percentage of the average bandwidth to adjust to.
 *   <small>E.g. <code>avgBandwidth * (limitPercentage / 100)</code>.</small>
 * @param {Boolean} [options.autoBandwidthAdjustment.useUploadBwOnly=false] The flag if average bandwidth computation
 *   should only consist of the upload bandwidth.
 * @param {Function} [callback] The callback function fired when request has completed.
 *   <small>Function parameters signature is <code>function (error, success)</code></small>
 *   <small>Function request completion is determined by the <a href="#event_peerJoined">
 *   <code>peerJoined</code> event</a> triggering <code>isSelf</code> parameter payload value as <code>true</code>
 *   for request success.</small>
 * @param {JSON} callback.error The error result in request.
 *   <small>Defined as <code>null</code> when there are no errors in request</small>
 * @param {Error} callback.error.error The error received when starting Room session has failed.
 * @param {Number} [callback.error.errorCode] The current <a href="#method_init"><code>init()</code> method</a> ready state.
 *   <small>Defined as <code>null</code> when no <a href="#method_init"><code>init()</code> method</a>
 *   has not been called due to invalid configuration.</small>
 *   [Rel: Skylink.READY_STATE_CHANGE]
 * @param {String} callback.error.room The Room name.
 * @param {JSON} callback.success The success result in request.
 *   <small>Defined as <code>null</code> when there are errors in request</small>
 * @param {String} callback.success.room The Room name.
 * @param {String} callback.success.peerId The User's Room session Peer ID.
 * @param {JSON} callback.success.peerInfo The User's current Room session information.
 *   <small>Object signature matches the <code>peerInfo</code> parameter payload received in the
 *   <a href="#event_peerJoined"><code>peerJoined</code> event</a>.</small>
 * @example
 *   // Example 1: Connecting to the default Room without Stream
 *   skylinkDemo.joinRoom(function (error, success) {
 *     if (error) return;
 *     console.log("User connected.");
 *   });
 *
 *   // Example 2: Connecting to Room "testxx" with Stream
 *   skylinkDemo.joinRoom("testxx", {
 *     audio: true,
 *     video: true
 *   }, function (error, success) {
 *     if (error) return;
 *     console.log("User connected with getUserMedia() Stream.")
 *   });
 *
 *   // Example 3: Connecting to default Room with Stream retrieved earlier
 *   skylinkDemo.getUserMedia(function (gUMError, gUMSuccess) {
 *     if (gUMError) return;
 *     skylinkDemo.joinRoom(function (error, success) {
 *       if (error) return;
 *       console.log("User connected with getUserMedia() Stream.");
 *     });
 *   });
 *
 *   // Example 4: Connecting to "testxx" Room with shareScreen() Stream retrieved manually
 *   skylinkDemo.on("mediaAccessRequired", function () {
 *     skylinkDemo.shareScreen(function (sSError, sSSuccess) {
 *       if (sSError) return;
 *     });
 *   });
 *
 *   skylinkDemo.joinRoom("testxx", {
 *     manualGetUserMedia: true
 *   }, function (error, success) {
 *     if (error) return;
 *     console.log("User connected with shareScreen() Stream.");
 *   });
 *
 *   // Example 5: Connecting to "testxx" Room with User custom data
 *   var data = { username: "myusername" };
 *   skylinkDemo.joinRoom("testxx", {
 *     userData: data
 *   }, function (error, success) {
 *     if (error) return;
 *     console.log("User connected with correct user data?", success.peerInfo.userData.username === data.username);
 *   });
 * 
 *   // Example 6: Connecting to "testxx" Room with a pre-configured bandwidth set
 *   skylinkDemo.joinRoom("testxx", {
 *     bandwidth: skylinkDemo.VIDEO_QUALITY.HD
 *   }, function (error, success) {
 *     if (error) return;
 *     console.log("User connected with bandwidth quality HD");
 *   });
 * @trigger <ol class="desc-seq">
 *   <li>If User is in a Room: <ol>
 *   <li>Invoke <a href="#method_leaveRoom"><code>leaveRoom()</code> method</a>
 *   to end current Room connection. <small>Invoked <a href="#method_leaveRoom"><code>leaveRoom()</code>
 *   method</a> <code>stopMediaOptions</code> parameter value will be <code>false</code>.</small>
 *   <small>Regardless of request errors, <code>joinRoom()</code> will still proceed.</small></li></ol></li>
 *   <li>Check if Room name provided matches the Room name of the currently retrieved Room session token. <ol>
 *   <li>If Room name does not matches: <ol>
 *   <li>Invoke <a href="#method_init"><code>init()</code> method</a> to retrieve new Room session token. <ol>
 *   <li>If request has errors: <ol><li><b>ABORT</b> and return error.</li></ol></li></ol></li></ol></li></ol></li>
 *   <li>Open a new socket connection to Signaling server. <ol><li>If Socket connection fails: <ol>
 *   <li><a href="#event_socketError"><code>socketError</code> event</a> triggers parameter payload
 *   <code>errorCode</code> as <code>CONNECTION_FAILED</code>. <ol>
 *   <li>Checks if there are fallback ports and transports to use. <ol>
 *   <li>If there are still fallback ports and transports: <ol>
 *   <li>Attempts to retry socket connection to Signaling server. <ol>
 *   <li><a href="#event_channelRetry"><code>channelRetry</code> event</a> triggers.</li>
 *   <li><a href="#event_socketError"><code>socketError</code> event</a> triggers parameter
 *   payload <code>errorCode</code> as <code>RECONNECTION_ATTEMPT</code>.</li>
 *   <li>If attempt to retry socket connection to Signaling server has failed: <ol>
 *   <li><a href="#event_socketError"><code>socketError</code> event</a> triggers parameter payload
 *   <code>errorCode</code> as <code>RECONNECTION_FAILED</code>.</li>
 *   <li>Checks if there are still any more fallback ports and transports to use. <ol>
 *   <li>If there are is no more fallback ports and transports to use: <ol>
 *   <li><a href="#event_socketError"><code>socketError</code> event</a> triggers
 *   parameter payload <code>errorCode</code> as <code>RECONNECTION_ABORTED</code>.</li>
 *   <li><b>ABORT</b> and return error.</li></ol></li><li>Else: <ol><li><b>REPEAT</b> attempt to retry socket connection
 *   to Signaling server step.</li></ol></li></ol></li></ol></li></ol></li></ol></li><li>Else: <ol>
 *   <li><a href="#event_socketError"><code>socketError</code> event</a> triggers
 *   parameter payload <code>errorCode</code> as <code>CONNECTION_ABORTED</code>.</li>
 *   <li><b>ABORT</b> and return error.</li></ol></li></ol></li></ol></li></ol></li>
 *   <li>If socket connection to Signaling server has opened: <ol>
 *   <li><a href="#event_channelOpen"><code>channelOpen</code> event</a> triggers.</li></ol></li></ol></li>
 *   <li>Checks if there is <code>options.manualGetUserMedia</code> requested <ol><li>If it is requested: <ol>
 *   <li><a href="#event_mediaAccessRequired"><code>mediaAccessRequired</code> event</a> triggers.</li>
 *   <li>If more than 30 seconds has passed and no <a href="#method_getUserMedia"><code>getUserMedia()</code> Stream</a>
 *   or <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a>
 *   has been retrieved: <ol><li><b>ABORT</b> and return error.</li></ol></li></ol></li><li>Else: <ol>
 *   <li>If there is <code>options.audio</code> or <code>options.video</code> requested: <ol>
 *   <li>Invoke <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>. <ol>
 *   <li>If request has errors: <ol><li><b>ABORT</b> and return error.</li></ol></li></ol></li></ol></li></ol></li>
 *   </ol></li><li>Starts the Room session <ol><li>If Room session has started successfully: <ol>
 *   <li><a href="#event_peerJoined"><code>peerJoined</code> event</a> triggers parameter payload
 *   <code>isSelf</code> value as <code>true</code>.</li>
 *   <li>If MCU is enabled for the App Key provided in <a href="#method_init"><code>init()</code>
 *   method</a> and connected: <ol><li><a href="#event_serverPeerJoined"><code>serverPeerJoined</code>
 *   event</a> triggers <code>serverPeerType</code> as <code>MCU</code>. <small>MCU has
 *   to be present in the Room in order for Peer connections to commence.</small></li>
 *   <li>Checks for any available Stream <ol>
 *   <li>If <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a> is available: <ol>
 *   <li><a href="#event_incomingStream"><code>incomingStream</code> event</a>
 *   triggers parameter payload <code>isSelf</code> value as <code>true</code> and <code>stream</code>
 *   as <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a>.
 *   <small>User will be sending <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a>
 *   to Peers.</small></li></ol></li>
 *   <li>Else if <a href="#method_getUserMedia"><code>getUserMedia()</code> Stream</a> is available: <ol>
 *   <li><a href="#event_incomingStream"><code>incomingStream</code> event</a> triggers parameter
 *   payload <code>isSelf</code> value as <code>true</code> and <code>stream</code> as
 *   <a href="#method_getUserMedia"><code>getUserMedia()</code> Stream</a>.
 *   <small>User will be sending <code>getUserMedia()</code> Stream to Peers.</small></li></ol></li><li>Else: <ol>
 *   <li>No Stream will be sent.</li></ol></li></ol></li></ol></li></ol></li><li>Else: <ol>
 *   <li><a href="#event_systemAction"><code>systemAction</code> event</a> triggers
 *   parameter payload <code>action</code> as <code>REJECT</code>.</li>
 *   <li><b>ABORT</b> and return error.</li></ol></li></ol></li></ol>
 * @for Skylink
 * @since 0.5.5
 */

Skylink.prototype.joinRoom = function(room, options, callback) {
  var self = this;
  var selectedRoom = self._initOptions.defaultRoom;
  var previousRoom = self._selectedRoom;
  var mediaOptions = {};
  var timestamp = (new Date()).getTime() + Math.floor(Math.random() * 10000);
  self._joinRoomManager.timestamp = timestamp;

  if (room && typeof room === 'string') {
    selectedRoom = room;
  } else if (room && typeof room === 'object') {
    mediaOptions = room;
  } else if (typeof room === 'function') {
    callback = room;
  }

  if (options && typeof options === 'object') {
    mediaOptions = options;
  } else if (typeof options === 'function') {
    callback = options;
  }

  var resolveAsErrorFn = function (error, tryRoom, readyState) {
    log.error(error);

    if (typeof callback === 'function') {
      callback({
        room: tryRoom,
        errorCode: readyState || null,
        error: error instanceof Error ? error : new Error(JSON.stringify(error))
      });
    }
  };

  var resolveAsWarningFn = function(error, tryRoom) {
    log.warn(error + ' ' + 'room: ' + tryRoom);
  };

  var joinRoomFn = function () {
    // If room has been stopped but does not matches timestamp skip.
    if (self._joinRoomManager.timestamp !== timestamp) {
      resolveAsWarningFn('joinRoom() process did not complete', selectedRoom);
      return;
    }

    self._initSelectedRoom(selectedRoom, function(initError, initSuccess) {
      if (initError) {
        resolveAsErrorFn(initError.error, self._selectedRoom, self._readyState);
        return;
      // If details has been initialised but does not matches timestamp skip.
      } else if (self._joinRoomManager.timestamp !== timestamp) {
        resolveAsWarningFn('joinRoom() process did not complete', selectedRoom);
        return;
      }

      self._waitForOpenChannel(mediaOptions || {}, timestamp, function (error, success) {
        if (error) {
          resolveAsErrorFn(error, self._selectedRoom, self._readyState);
          return;
        // If socket and stream has been retrieved but socket connection does not matches timestamp skip.
        } else if (self._joinRoomManager.timestamp !== timestamp) {
          resolveAsWarningFn('joinRoom() process did not complete', selectedRoom);
          return;
        }

        if (AdapterJS.webrtcDetectedType === 'AppleWebKit') {
          var checkStream = self._streams.screenshare && self._streams.screenshare.stream ?
            self._streams.screenshare.stream : (self._streams.userMedia && self._streams.userMedia.stream ?
              self._streams.userMedia.stream : null);

          if (checkStream ? checkStream.getTracks().length === 0 : true) {
            log.warn('Note that receiving audio and video streams may fail as safari 11 needs stream with audio and video tracks');
          } else if (checkStream.getAudioTracks().length === 0) {
            log.warn('Note that receiving audio streams may fail as safari 11 needs stream ' +
              'with audio and video tracks and not just with video tracks');
          } else if (checkStream.getVideoTracks().length === 0) {
            log.warn('Note that receiving video streams may fail as safari 11 needs stream ' +
              'with audio and video tracks and not just with audio tracks');
          }
        }

        if (typeof callback === 'function') {
          var peerOnJoin = function(peerId, peerInfo, isSelf) {
            self.off('systemAction', peerFailedJoin);
            self.off('channelClose', peerSocketFailedJoin);
            log.info([null, 'Room', selectedRoom, 'Connected to Room ->'], peerInfo);
            callback(null, {
              room: self._selectedRoom,
              peerId: peerId,
              peerInfo: peerInfo
            });
          };

          var peerFailedJoin = function (action, message) {
            self.off('peerJoined', peerOnJoin);
            self.off('channelClose', peerSocketFailedJoin);
            log.error([null, 'Room', selectedRoom, 'Failed connecting to Room ->'], message);
            resolveAsErrorFn(new Error(message), self._selectedRoom, self._readyState);
          };

          var peerSocketFailedJoin = function () {
            self.off('systemAction', peerFailedJoin);
            self.off('peerJoined', peerOnJoin);
            log.error([null, 'Room', selectedRoom, 'Failed connecting to Room due to abrupt disconnection.']);
            resolveAsErrorFn(new Error('Channel closed abruptly before session was established'), self._selectedRoom, self._readyState);
          };

          self.once('peerJoined', peerOnJoin, function(peerId, peerInfo, isSelf) {
            return peerInfo.room === selectedRoom && isSelf;
          });

          self.once('systemAction', peerFailedJoin, function (action) {
            return action === self.SYSTEM_ACTION.REJECT;
          });

          self.once('channelClose', peerSocketFailedJoin);
        }

        var joinRoomMsg = {
          type: self._SIG_MESSAGE_TYPE.JOIN_ROOM,
          uid: self._user.uid,
          cid: self._key,
          rid: self._room.id,
          userCred: self._user.token,
          timeStamp: self._user.timeStamp,
          apiOwner: self._appKeyOwner,
          roomCred: self._room.token,
          start: self._room.startDateTime,
          len: self._room.duration,
          isPrivileged: self._isPrivileged === true, // Default to false if undefined
          autoIntroduce: self._autoIntroduce !== false, // Default to true if undefined
          key: self._initOptions.appKey
        };

        self._sendChannelMessage(joinRoomMsg);
        self._handleSessionStats(joinRoomMsg);
      });
    });
  };

  if (room === null || ['number', 'boolean'].indexOf(typeof room) > -1) {
    resolveAsErrorFn('Invalid room name is provided', room);
    return;
  }

  if (options === null || ['number', 'boolean'].indexOf(typeof options) > -1) {
    resolveAsErrorFn('Invalid mediaOptions is provided', selectedRoom);
    return;
  }

  self._joinRoomManager.socketsFn.forEach(function (fnItem) {
    fnItem(timestamp);
  });

  self._joinRoomManager.socketsFn = [];

  var stopStream = mediaOptions.audio === false && mediaOptions.video === false;

  if (self._inRoom) {
    self.leaveRoom({
      userMedia: stopStream
    }, function (lRError, lRSuccess) {
      log.debug([null, 'Room', previousRoom, 'Leave Room callback result ->'], [lRError, lRSuccess]);
      joinRoomFn();
    });
  } else {
    if (stopStream) {
      self.stopStream();
    }

    joinRoomFn();
  }
};

/**
 * <blockquote class="info">
 *   Note that this method will close any existing socket channel connection despite not being in the Room.
 * </blockquote>
 * Function that stops Room session.
 * @method leaveRoom
 * @param {Boolean|JSON} [stopMediaOptions=true] The flag if <code>leaveRoom()</code>
 *   should stop both <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a>
 *   and <a href="#method_getUserMedia"><code>getUserMedia()</code> Stream</a>.
 * - When provided as a boolean, this sets both <code>stopMediaOptions.userMedia</code>
 *   and <code>stopMediaOptions.screenshare</code> to its boolean value.
 * @param {Boolean} [stopMediaOptions.userMedia=true] The flag if <code>leaveRoom()</code>
 *   should stop <a href="#method_getUserMedia"><code>getUserMedia()</code> Stream</a>.
 *   <small>This invokes <a href="#method_stopStream"><code>stopStream()</code> method</a>.</small>
 * @param {Boolean} [stopMediaOptions.screenshare=true] The flag if <code>leaveRoom()</code>
 *   should stop <a href="#method_shareScreen"><code>shareScreen()</code> Stream</a>.
 *   <small>This invokes <a href="#method_stopScreen"><code>stopScreen()</code> method</a>.</small>
 * @param {Function} [callback] The callback function fired when request has completed.
 *   <small>Function parameters signature is <code>function (error, success)</code></small>
 *   <small>Function request completion is determined by the <a href="#event_peerLeft">
 *   <code>peerLeft</code> event</a> triggering <code>isSelf</code> parameter payload value as <code>true</code>
 *   for request success.</small>
 * @param {Error|String} callback.error The error result in request.
 *   <small>Defined as <code>null</code> when there are no errors in request</small>
 *   <small>Object signature is the <code>leaveRoom()</code> error when stopping Room session.</small>
 * @param {JSON} callback.success The success result in request.
 *   <small>Defined as <code>null</code> when there are errors in request</small>
 * @param {String} callback.success.peerId The User's Room session Peer ID.
 * @param {String} callback.success.previousRoom The Room name.
 * @trigger <ol class="desc-seq">
 *   <li>If Socket connection is opened: <ol><li><a href="#event_channelClose"><code>channelClose</code> event</a> triggers.</li></ol></li>
 *   <li>Checks if User is in Room. <ol><li>If User is not in a Room: <ol><li><b>ABORT</b> and return error.</li>
 *   </ol></li><li>Else: <ol><li>If parameter <code>stopMediaOptions.userMedia</code> value is <code>true</code>: <ol>
 *   <li>Invoke <a href="#method_stopStream"><code>stopStream()</code> method</a>.
 *   <small>Regardless of request errors, <code>leaveRoom()</code> will still proceed.</small></li></ol></li>
 *   <li>If parameter <code>stopMediaOptions.screenshare</code> value is <code>true</code>: <ol>
 *   <li>Invoke <a href="#method_stopScreen"><code>stopScreen()</code> method</a>.
 *   <small>Regardless of request errors, <code>leaveRoom()</code> will still proceed.</small></li></ol></li>
 *   <li><a href="#event_peerLeft"><code>peerLeft</code> event</a> triggers for User and all connected Peers in Room.</li>
 *   <li>If MCU is enabled for the App Key provided in <a href="#method_init"><code>init()</code> method</a>
 *   and connected: <ol><li><a href="#event_serverPeerLeft"><code>serverPeerLeft</code> event</a>
 *   triggers parameter payload <code>serverPeerType</code> as <code>MCU</code>.</li></ol></li></ol></li></ol></li></ol>
 * @for Skylink
 * @since 0.5.5
 */
Skylink.prototype.leaveRoom = function(stopMediaOptions, callback) {
  var self = this;
  var stopUserMedia = true;
  var stopScreenshare = true;
  var previousRoom = self._selectedRoom;
  var previousUserPeerId = self._user ? self._user.sid : null;
  var peersThatLeft = [];
  var isNotInRoom = !self._inRoom;

  if (typeof stopMediaOptions === 'boolean') {
    if (stopMediaOptions === false) {
      stopUserMedia = false;
      stopScreenshare = false;
    }
  } else if (stopMediaOptions && typeof stopMediaOptions === 'object') {
    stopUserMedia = stopMediaOptions.userMedia !== false;
    stopScreenshare = stopMediaOptions.screenshare !== false;
  } else if (typeof stopMediaOptions === 'function') {
    callback = stopMediaOptions;
  }

  for (var infoPeerId in self._peerInformations) {
    if (self._peerInformations.hasOwnProperty(infoPeerId) && self._peerInformations[infoPeerId]) {
      peersThatLeft.push(infoPeerId);
      self._removePeer(infoPeerId);
    }
  }

  for (var connPeerId in self._peerConnections) {
    if (self._peerConnections.hasOwnProperty(connPeerId) && self._peerConnections[connPeerId]) {
      if (peersThatLeft.indexOf(connPeerId) === -1) {
        peersThatLeft.push(connPeerId);
        self._removePeer(connPeerId);
      }
    }
  }

  self._inRoom = false;
  self._closeChannel();

  if (isNotInRoom) {
    var notInRoomError = 'Unable to leave room as user is not in any room';
    log.error([null, 'Room', previousRoom, notInRoomError]);

    if (typeof callback === 'function') {
      callback(new Error(notInRoomError), null);
    }
    return;
  }

  self._stopStreams({
    userMedia: stopUserMedia,
    screenshare: stopScreenshare
  });

  self._wait(function () {
    log.log([null, 'Room', previousRoom, 'User left the room']);

    self._trigger('peerLeft', previousUserPeerId, self.getPeerInfo(), true);

    if (typeof callback === 'function') {
      callback(null, {
        peerId: previousUserPeerId,
        previousRoom: previousRoom
      });
    }
  }, function () {
    return !self._channelOpen;
  });
};

/**
 * <blockquote class="info">
 *   Note that broadcasted events from <a href="#method_muteStream"><code>muteStream()</code> method</a>,
 *   <a href="#method_stopStream"><code>stopStream()</code> method</a>,
 *   <a href="#method_stopScreen"><code>stopScreen()</code> method</a>,
 *   <a href="#method_sendMessage"><code>sendMessage()</code> method</a>,
 *   <a href="#method_unlockRoom"><code>unlockRoom()</code> method</a> and
 *   <a href="#method_lockRoom"><code>lockRoom()</code> method</a> may be queued when
 *   sent within less than an interval.
 * </blockquote>
 * Function that locks the current Room when in session to prevent other Peers from joining the Room.
 * @method lockRoom
 * @trigger <ol class="desc-seq">
 *   <li>Requests to Signaling server to lock Room <ol>
 *   <li><a href="#event_roomLock"><code>roomLock</code> event</a> triggers parameter payload
 *   <code>isLocked</code> value as <code>true</code>.</li></ol></li></ol>
 * @for Skylink
 * @since 0.5.0
 */
Skylink.prototype.lockRoom = function() {
  if (!(this._user && this._user.sid)) {
    return;
  }
  log.log('Update to isRoomLocked status ->', true);
  this._sendChannelMessage({
    type: this._SIG_MESSAGE_TYPE.ROOM_LOCK,
    mid: this._user.sid,
    rid: this._room.id,
    lock: true
  });
  this._roomLocked = true;
  this._trigger('roomLock', true, this._user.sid, this.getPeerInfo(), true);
};

/**
 * <blockquote class="info">
 *   Note that broadcasted events from <a href="#method_muteStream"><code>muteStream()</code> method</a>,
 *   <a href="#method_stopStream"><code>stopStream()</code> method</a>,
 *   <a href="#method_stopScreen"><code>stopScreen()</code> method</a>,
 *   <a href="#method_sendMessage"><code>sendMessage()</code> method</a>,
 *   <a href="#method_unlockRoom"><code>unlockRoom()</code> method</a> and
 *   <a href="#method_lockRoom"><code>lockRoom()</code> method</a> may be queued when
 *   sent within less than an interval.
 * </blockquote>
 * Function that unlocks the current Room when in session to allow other Peers to join the Room.
 * @method unlockRoom
 * @trigger <ol class="desc-seq">
 *   <li>Requests to Signaling server to unlock Room <ol>
 *   <li><a href="#event_roomLock"><code>roomLock</code> event</a> triggers parameter payload
 *   <code>isLocked</code> value as <code>false</code>.</li></ol></li></ol>
 * @for Skylink
 * @since 0.5.0
 */
Skylink.prototype.unlockRoom = function() {
  if (!(this._user && this._user.sid)) {
    return;
  }
  log.log('Update to isRoomLocked status ->', false);
  this._sendChannelMessage({
    type: this._SIG_MESSAGE_TYPE.ROOM_LOCK,
    mid: this._user.sid,
    rid: this._room.id,
    lock: false
  });
  this._roomLocked = false;
  this._trigger('roomLock', false, this._user.sid, this.getPeerInfo(), true);
};

/**
 * Function that waits for Socket connection to Signaling to be opened.
 * @method _waitForOpenChannel
 * @private
 * @for Skylink
 * @since 0.5.5
 */
Skylink.prototype._waitForOpenChannel = function(mediaOptions, joinRoomTimestamp, callback) {
  var self = this;
  // when reopening room, it should stay as 0
  self._socketCurrentReconnectionAttempt = 0;

  // wait for ready state before opening
  self._wait(function() {
    var onChannelOpen = function () {
      self.off('socketError', onChannelError);

      // Wait for self._channelOpen flag to be defined first
      setTimeout(function () {
        mediaOptions = mediaOptions || {};

        self._userData = mediaOptions.userData || self._userData || '';
        self._streamsBandwidthSettings = {
          googleX: {},
          bAS: {}
        };
        self._publishOnly = false;
        self._sdpSettings = {
          connection: {
            audio: true,
            video: true,
            data: true
          },
          direction: {
            audio: { send: true, receive: true },
            video: { send: true, receive: true }
          }
        };
        self._voiceActivityDetection = typeof mediaOptions.voiceActivityDetection === 'boolean' ?
          mediaOptions.voiceActivityDetection : true;
        self._peerConnectionConfig = {
          bundlePolicy: self.BUNDLE_POLICY.BALANCED,
          rtcpMuxPolicy: self.RTCP_MUX_POLICY.REQUIRE,
          iceCandidatePoolSize: 0,
          certificate: self.PEER_CERTIFICATE.AUTO,
          disableBundle: false
        };
        self._bandwidthAdjuster = null;

        if (mediaOptions.bandwidth) {
          if (typeof mediaOptions.bandwidth.audio === 'number') {
            self._streamsBandwidthSettings.bAS.audio = mediaOptions.bandwidth.audio;
          }

          if (typeof mediaOptions.bandwidth.video === 'number') {
            self._streamsBandwidthSettings.bAS.video = mediaOptions.bandwidth.video;
          }

          if (typeof mediaOptions.bandwidth.data === 'number') {
            self._streamsBandwidthSettings.bAS.data = mediaOptions.bandwidth.data;
          }
        }

        if (mediaOptions.googleXBandwidth) {
          if (typeof mediaOptions.googleXBandwidth.min === 'number') {
            self._streamsBandwidthSettings.googleX.min = mediaOptions.googleXBandwidth.min;
          }

          if (typeof mediaOptions.googleXBandwidth.max === 'number') {
            self._streamsBandwidthSettings.googleX.max = mediaOptions.googleXBandwidth.max;
          }
        }

        if (mediaOptions.sdpSettings) {
          if (mediaOptions.sdpSettings.direction) {
            if (mediaOptions.sdpSettings.direction.audio) {
              self._sdpSettings.direction.audio.receive = typeof mediaOptions.sdpSettings.direction.audio.receive === 'boolean' ?
                mediaOptions.sdpSettings.direction.audio.receive : true;
              self._sdpSettings.direction.audio.send = typeof mediaOptions.sdpSettings.direction.audio.send === 'boolean' ?
                mediaOptions.sdpSettings.direction.audio.send : true;
            }

            if (mediaOptions.sdpSettings.direction.video) {
              self._sdpSettings.direction.video.receive = typeof mediaOptions.sdpSettings.direction.video.receive === 'boolean' ?
                mediaOptions.sdpSettings.direction.video.receive : true;
              self._sdpSettings.direction.video.send = typeof mediaOptions.sdpSettings.direction.video.send === 'boolean' ?
                mediaOptions.sdpSettings.direction.video.send : true;
            }
          }
          if (mediaOptions.sdpSettings.connection) {
            self._sdpSettings.connection.audio = typeof mediaOptions.sdpSettings.connection.audio === 'boolean' ?
              mediaOptions.sdpSettings.connection.audio : true;
            self._sdpSettings.connection.video = typeof mediaOptions.sdpSettings.connection.video === 'boolean' ?
              mediaOptions.sdpSettings.connection.video : true;
            self._sdpSettings.connection.data = typeof mediaOptions.sdpSettings.connection.data === 'boolean' ?
              mediaOptions.sdpSettings.connection.data : true;
          }
        }

        if (mediaOptions.publishOnly) {
          self._sdpSettings.direction.audio.send = true;
          self._sdpSettings.direction.audio.receive = false;
          self._sdpSettings.direction.video.send = true;
          self._sdpSettings.direction.video.receive = false;
          self._publishOnly = true;

          if (typeof mediaOptions.publishOnly === 'object' && mediaOptions.publishOnly.parentId &&
            typeof mediaOptions.publishOnly.parentId === 'string') {
            self._parentId = mediaOptions.publishOnly.parentId;
          }
        }

        if (mediaOptions.parentId) {
          self._parentId = mediaOptions.parentId;
        }

        if (mediaOptions.peerConnection && typeof mediaOptions.peerConnection === 'object') {
          if (typeof mediaOptions.peerConnection.bundlePolicy === 'string') {
            for (var bpProp in self.BUNDLE_POLICY) {
              if (self.BUNDLE_POLICY.hasOwnProperty(bpProp) &&
                self.BUNDLE_POLICY[bpProp] === mediaOptions.peerConnection.bundlePolicy) {
                self._peerConnectionConfig.bundlePolicy = mediaOptions.peerConnection.bundlePolicy;
              }
            }
          }
          if (typeof mediaOptions.peerConnection.rtcpMuxPolicy === 'string') {
            for (var rmpProp in self.RTCP_MUX_POLICY) {
              if (self.RTCP_MUX_POLICY.hasOwnProperty(rmpProp) &&
                self.RTCP_MUX_POLICY[rmpProp] === mediaOptions.peerConnection.rtcpMuxPolicy) {
                self._peerConnectionConfig.rtcpMuxPolicy = mediaOptions.peerConnection.rtcpMuxPolicy;
              }
            }
          }
          if (typeof mediaOptions.peerConnection.iceCandidatePoolSize === 'number' &&
            mediaOptions.peerConnection.iceCandidatePoolSize > 0) {
            self._peerConnectionConfig.iceCandidatePoolSize = mediaOptions.peerConnection.iceCandidatePoolSize;
          }
          if (typeof mediaOptions.peerConnection.certificate === 'string') {
            for (var pcProp in self.PEER_CERTIFICATE) {
              if (self.PEER_CERTIFICATE.hasOwnProperty(pcProp) &&
                self.PEER_CERTIFICATE[pcProp] === mediaOptions.peerConnection.certificate) {
                self._peerConnectionConfig.certificate = mediaOptions.peerConnection.certificate;
              }
            }
          }
          self._peerConnectionConfig.disableBundle = mediaOptions.peerConnection.disableBundle === true;
        }

        if (mediaOptions.autoBandwidthAdjustment) {
          self._bandwidthAdjuster = {
            interval: 10,
            limitAtPercentage: 100,
            useUploadBwOnly: false
          };

          if (typeof mediaOptions.autoBandwidthAdjustment === 'object') {
            if (typeof mediaOptions.autoBandwidthAdjustment.interval === 'number' &&
              mediaOptions.autoBandwidthAdjustment.interval >= 10) {
              self._bandwidthAdjuster.interval = mediaOptions.autoBandwidthAdjustment.interval;
            }
            if (typeof mediaOptions.autoBandwidthAdjustment.limitAtPercentage === 'number' &&
              (mediaOptions.autoBandwidthAdjustment.limitAtPercentage >= 0 &&
              mediaOptions.autoBandwidthAdjustment.limitAtPercentage <= 100)) {
              self._bandwidthAdjuster.limitAtPercentage = mediaOptions.autoBandwidthAdjustment.limitAtPercentage;
            }
            if (typeof mediaOptions.autoBandwidthAdjustment.useUploadBwOnly === 'boolean') {
              self._bandwidthAdjuster.useUploadBwOnly = mediaOptions.autoBandwidthAdjustment.useUploadBwOnly;
            }
          }
        }

        // get the stream
        if (mediaOptions.manualGetUserMedia === true) {
          self._trigger('mediaAccessRequired');

          var current50Block = 0;
          var mediaAccessRequiredFailure = false;
          // wait for available audio or video stream
          self._wait(function () {
            if (mediaAccessRequiredFailure === true) {
              self._onUserMediaError(new Error('Waiting for stream timeout'), false, false);
            } else {
              callback(null, self._streams.userMedia.stream);
            }
          }, function () {
            current50Block += 1;
            if (current50Block === 600) {
              mediaAccessRequiredFailure = true;
              return true;
            }

            if (self._streams.userMedia && self._streams.userMedia.stream) {
              return true;
            }
          }, 50);
          return;
        }

        if (mediaOptions.audio || mediaOptions.video) {
          self.getUserMedia({
            useExactConstraints: !!mediaOptions.useExactConstraints,
            audio: mediaOptions.audio,
            video: mediaOptions.video

          }, function (error, success) {
            if (error) {
              callback(error, null);
            } else {
              callback(null, success);
            }
          });
          return;
        }
        callback(null, null);
      }, 1);
    };
    var onChannelError = function (errorState, error) {
      self.off('channelOpen', onChannelOpen);
      callback(error);
    };

    if (!self._channelOpen) {
      self.once('channelOpen', onChannelOpen);
      self.once('socketError', onChannelError, function (errorState) {
        return errorState === self.SOCKET_ERROR.RECONNECTION_ABORTED;
      });
      self._openChannel(joinRoomTimestamp);
    } else {
      onChannelOpen();
    }
  }, function() {
    return self._readyState === self.READY_STATE_CHANGE.COMPLETED;
  });
};