/**
* Stores the list of <code>on()</code> event handlers.
* @attribute _EVENTS
* @param {Array} <#event> The list of event handlers associated with the event.
* @param {Function} <#event>.<#index> The event handler function.
* @type JSON
* @private
* @for Skylink
* @since 0.5.2
*/
Skylink.prototype._EVENTS = {
/**
* Event triggered when socket connection to Signaling server has opened.
* @event channelOpen
* @for Skylink
* @since 0.1.0
*/
channelOpen: [],
/**
* Event triggered when socket connection to Signaling server has closed.
* @event channelClose
* @for Skylink
* @since 0.1.0
*/
channelClose: [],
/**
* <blockquote class="info">
* Note that this is used only for SDK developer purposes.
* </blockquote>
* Event triggered when receiving socket message from the Signaling server.
* @event channelMessage
* @param {JSON} message The socket message object.
* @for Skylink
* @since 0.1.0
*/
channelMessage: [],
/**
* <blockquote class="info">
* This may be caused by Javascript errors in the event listener when subscribing to events.<br>
* It may be resolved by checking for code errors in your Web App in the event subscribing listener.<br>
* <code>skylinkDemo.on("eventName", function () { // Errors here });</code>
* </blockquote>
* Event triggered when socket connection encountered exception.
* @event channelError
* @param {Error|String} error The error object.
* @for Skylink
* @since 0.1.0
*/
channelError: [],
/**
* Event triggered when attempting to establish socket connection to Signaling server when failed.
* @event channelRetry
* @param {String} fallbackType The current fallback state.
* [Rel: Skylink.SOCKET_FALLBACK]
* @param {Number} currentAttempt The current reconnection attempt.
* @for Skylink
* @since 0.5.6
*/
channelRetry: [],
/**
* Event triggered when attempt to establish socket connection to Signaling server has failed.
* @event socketError
* @param {String} errorCode The socket connection error code.
* [Rel: Skylink.SOCKET_ERROR]
* @param {Error|String|Number} error The error object.
* @param {String} type The fallback state of the socket connection attempt.
* [Rel: Skylink.SOCKET_FALLBACK]
* @for Skylink
* @since 0.5.5
*/
socketError: [],
/**
* Event triggered when <a href="#method_init"><code>init()</code> method</a> ready state changes.
* @event readyStateChange
* @param {String} readyState The current <code>init()</code> ready state.
* [Rel: Skylink.READY_STATE_CHANGE]
* @param {JSON} [error] The error result.
* <small>Defined only when <code>state</code> is <code>ERROR</code>.</small>
* @param {Number} error.status The HTTP status code when failed.
* @param {Number} error.errorCode The ready state change failure code.
* [Rel: Skylink.READY_STATE_CHANGE_ERROR]
* @param {Error} error.content The error object.
* @param {String} room The Room to The Room to retrieve session token for.
* @for Skylink
* @since 0.4.0
*/
readyStateChange: [],
/**
* Event triggered when a Peer connection establishment state has changed.
* @event handshakeProgress
* @param {String} state The current Peer connection establishment state.
* [Rel: Skylink.HANDSHAKE_PROGRESS]
* @param {String} peerId The Peer ID.
* @param {Error|String} [error] The error object.
* <small>Defined only when <code>state</code> is <code>ERROR</code>.</small>
* @for Skylink
* @since 0.3.0
*/
handshakeProgress: [],
/**
* Event triggered when a Peer connection ICE gathering state has changed.
* @event candidateGenerationState
* @param {String} state The current Peer connection ICE gathering state.
* [Rel: Skylink.CANDIDATE_GENERATION_STATE]
* @param {String} peerId The Peer ID.
* @for Skylink
* @since 0.1.0
*/
candidateGenerationState: [],
/**
* Event triggered when a Peer connection session description exchanging state has changed.
* @event peerConnectionState
* @param {String} state The current Peer connection session description exchanging state.
* [Rel: Skylink.PEER_CONNECTION_STATE]
* @param {String} peerId The Peer ID.
* @for Skylink
* @since 0.1.0
*/
peerConnectionState: [],
/**
* Event triggered when a Peer connection ICE connection state has changed.
* @event iceConnectionState
* @param {String} state The current Peer connection ICE connection state.
* [Rel: Skylink.ICE_CONNECTION_STATE]
* @param {String} peerId The Peer ID.
* @for Skylink
* @since 0.1.0
*/
iceConnectionState: [],
/**
* Event triggered when retrieval of Stream failed.
* @event mediaAccessError
* @param {Error|String} error The error object.
* @param {Boolean} isScreensharing The flag if event occurred during
* <a href="#method_shareScreen"><code>shareScreen()</code> method</a> and not
* <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>.
* @param {Boolean} isAudioFallbackError The flag if event occurred during
* retrieval of audio tracks only when <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>
* had failed to retrieve both audio and video tracks.
* @for Skylink
* @since 0.1.0
*/
mediaAccessError: [],
/**
* Event triggered when Stream retrieval fallback state has changed.
* @event mediaAccessFallback
* @param {JSON} error The error result.
* @param {Error|String} error.error The error object.
* @param {JSON} [error.diff=null] The list of excepted but received audio and video tracks in Stream.
* <small>Defined only when <code>state</code> payload is <code>FALLBACKED</code>.</small>
* @param {JSON} error.diff.video The expected and received video tracks.
* @param {Number} error.diff.video.expected The expected video tracks.
* @param {Number} error.diff.video.received The received video tracks.
* @param {JSON} error.diff.audio The expected and received audio tracks.
* @param {Number} error.diff.audio.expected The expected audio tracks.
* @param {Number} error.diff.audio.received The received audio tracks.
* @param {Number} state The fallback state.
* [Rel: Skylink.MEDIA_ACCESS_FALLBACK_STATE]
* @param {Boolean} isScreensharing The flag if event occurred during
* <a href="#method_shareScreen"><code>shareScreen()</code> method</a> and not
* <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>.
* @param {Boolean} isAudioFallback The flag if event occurred during
* retrieval of audio tracks only when <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>
* had failed to retrieve both audio and video tracks.
* @for Skylink
* @since 0.6.3
*/
mediaAccessFallback: [],
/**
* Event triggered when retrieval of Stream is successful.
* @event mediaAccessSuccess
* @param {MediaStream} stream The Stream object.
* <small>To attach it to an element: <code>attachMediaStream(videoElement, stream);</code>.</small>
* @param {Boolean} isScreensharing The flag if event occurred during
* <a href="#method_shareScreen"><code>shareScreen()</code> method</a> and not
* <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>.
* @for Skylink
* @since 0.1.0
*/
mediaAccessSuccess: [],
/**
* Event triggered when retrieval of Stream is required to complete <a href="#method_joinRoom">
* <code>joinRoom()</code> method</a> request.
* @event mediaAccessRequired
* @for Skylink
* @since 0.5.5
*/
mediaAccessRequired: [],
/**
* Event triggered when Stream has stopped streaming.
* @event mediaAccessStopped
* @param {Boolean} isScreensharing The flag if event occurred during
* <a href="#method_shareScreen"><code>shareScreen()</code> method</a> and not
* <a href="#method_getUserMedia"><code>getUserMedia()</code> method</a>.
* @for Skylink
* @since 0.5.6
*/
mediaAccessStopped: [],
/**
* Event triggered when a Peer joins the room.
* @event peerJoined
* @param {String} peerId The Peer ID.
* @param {JSON} peerInfo The Peer session information.
* @param {JSON|String} peerInfo.userData The Peer current custom data.
* @param {JSON} peerInfo.settings The Peer sending Stream settings.
* @param {Boolean|JSON} peerInfo.settings.audio The Peer Stream audio settings.
* <small>When defined as <code>false</code>, it means there is no audio being sent from Peer.</small>
* @param {Boolean} [peerInfo.settings.audio.stereo] The flag if stereo band is configured
* when encoding audio codec is <a href="#attr_AUDIO_CODEC"><code>OPUS</code></a> for receiving audio data.
* @param {Boolean|JSON} peerInfo.settings.video The Peer Stream video settings.
* <small>When defined as <code>false</code>, it means there is no video being sent from Peer.</small>
* @param {JSON} peerInfo.settings.video.resolution The Peer Stream video resolution.
* [Rel: Skylink.VIDEO_RESOLUTION]
* @param {Number} [peerInfo.settings.video.resolution.width] The Peer Stream video resolution width.
* @param {Number} [peerInfo.settings.video.resolution.height] The Peer Stream video resolution height.
* @param {Number} [peerInfo.settings.video.frameRate] The Peer Stream video
* <a href="https://en.wikipedia.org/wiki/Frame_rate">frameRate</a> per second (fps).
* @param {Boolean} [peerInfo.settings.video.screenshare] The flag if Peer Stream is a screensharing Stream.
* @param {JSON} [peerInfo.settings.bandwidth] The maximum streaming bandwidth sent from Peer.
* @param {Number} [peerInfo.settings.bandwidth.audio] The maximum audio streaming bandwidth sent from Peer.
* @param {Number} [peerInfo.settings.bandwidth.video] The maximum video streaming bandwidth sent from Peer.
* @param {Number} [peerInfo.settings.bandwidth.data] The maximum data streaming bandwidth sent from Peer.
* @param {JSON} peerInfo.mediaStatus The Peer Stream muted settings.
* @param {Boolean} peerInfo.mediaStatus.audioMuted The flag if Peer Stream audio tracks is muted or not.
* <small>If Peer <code>peerInfo.settings.audio</code> is false, this will be defined as <code>true</code>.</small>
* @param {Boolean} peerInfo.mediaStatus.videoMuted The flag if Peer Stream audio tracks is muted or not.
* <small>If Peer <code>peerInfo.settings.video</code> is false, this will be defined as <code>true</code>.</small>
* @param {JSON} peerInfo.agent The Peer agent information.
* @param {String} peerInfo.agent.name The Peer agent name.
* <small>Data may be accessing browser or non-Web SDK name.</small>
* @param {Number} peerInfo.agent.version The Peer agent version.
* <small>Data may be accessing browser or non-Web SDK version.</small>
* @param {String} [peerInfo.agent.os] The Peer platform name.
* <small>Data may be accessing OS platform version from Web SDK.</small>
* @param {String} peerInfo.room The Room Peer is from.
* @param {Boolean} isSelf The flag if Peer is User.
* @for Skylink
* @since 0.5.2
*/
peerJoined: [],
/**
* Event triggered when a Peer connection has been refreshed.
* @event peerRestart
* @param {String} peerId The Peer ID.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelfInitiateRestart The flag if User is initiating the Peer connection refresh.
* @for Skylink
* @since 0.5.5
*/
peerRestart: [],
/**
* Event triggered when a Peer session information has been updated.
* @event peerUpdated
* @param {String} peerId The Peer ID.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelf The flag if Peer is User.
* @for Skylink
* @since 0.5.2
*/
peerUpdated: [],
/**
* Event triggered when a Peer leaves the room.
* @event peerLeft
* @param {String} peerId The Peer ID.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelf The flag if Peer is User.
* @for Skylink
* @since 0.5.2
*/
peerLeft: [],
/**
* Event triggered when Room session has ended abruptly due to network disconnections.
* @event sessionDisconnect
* @param {String} peerId The User's Room session Peer ID.
* @param {JSON} peerInfo The User's 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>
* @for Skylink
* @since 0.6.10
*/
sessionDisconnect: [],
/**
* Event triggered when receiving Peer Stream.
* @event incomingStream
* @param {String} peerId The Peer ID.
* @param {MediaStream} stream The Stream object.
* <small>To attach it to an element: <code>attachMediaStream(videoElement, stream);</code>.</small>
* @param {Boolean} isSelf The flag if Peer is User.
* @param {JSON} peerInfo The Peer 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>
* @for Skylink
* @since 0.5.5
*/
incomingStream: [],
/**
* Event triggered when receiving message from Peer.
* @event incomingMessage
* @param {JSON} message The message result.
* @param {JSON|String} message.content The message object.
* @param {String} message.senderPeerId The sender Peer ID.
* @param {String|Array} [message.targetPeerId=null] The value of the <code>targetPeerId</code>
* defined in <a href="#method_sendP2PMessage"><code>sendP2PMessage()</code> method</a> or
* <a href="#method_sendMessage"><code>sendMessage()</code> method</a>.
* @param {Boolean} message.isPrivate The flag if message is targeted or not, basing
* off the <code>targetPeerId</code> parameter being defined in
* <a href="#method_sendP2PMessage"><code>sendP2PMessage()</code> method</a> or
* <a href="#method_sendMessage"><code>sendMessage()</code> method</a>.
* @param {Boolean} message.isDataChannel The flag if message is sent from
* <a href="#method_sendP2PMessage"><code>sendP2PMessage()</code> method</a>.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelf The flag if Peer is User.
* @for Skylink
* @since 0.5.2
*/
incomingMessage: [],
/**
* Event triggered when receiving completed data transfer from Peer.
* @event incomingData
* @param {Blob|String} data The data.
* @param {String} transferId The data transfer ID.
* @param {String} peerId The Peer ID.
* @param {JSON} transferInfo The data transfer information.
* <small>Object signature matches the <code>transferInfo</code> parameter payload received in the
* <a href="#event_dataTransferState"><code>dataTransferState</code> event</a>.</small>
* @param {Boolean} isSelf The flag if Peer is User.
* @for Skylink
* @since 0.6.1
*/
incomingData: [],
/**
* Event triggered when receiving upload data transfer from Peer.
* @event incomingDataRequest
* @param {String} transferId The transfer ID.
* @param {String} peerId The Peer ID.
* @param {String} transferInfo The data transfer information.
* <small>Object signature matches the <code>transferInfo</code> parameter payload received in the
* <a href="#event_dataTransferState"><code>dataTransferState</code> event</a>.</small>
* @param {Boolean} isSelf The flag if Peer is User.
* @for Skylink
* @since 0.6.1
*/
incomingDataRequest: [],
/**
* Event triggered when Room locked status has changed.
* @event roomLock
* @param {Boolean} isLocked The flag if Room is locked.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelf The flag if User changed the Room locked status.
* @for Skylink
* @since 0.5.2
*/
roomLock: [],
/**
* Event triggered when a Datachannel connection state has changed.
* @event dataChannelState
* @param {String} state The current Datachannel connection state.
* [Rel: Skylink.DATA_CHANNEL_STATE]
* @param {String} peerId The Peer ID.
* @param {Error} [error] The error object.
* <small>Defined only when <code>state</code> payload is <code>ERROR</code>.</small>
* @param {String} channelName The DataChannel ID.
* @param {String} channelType The DataChannel type.
* [Rel: Skylink.DATA_CHANNEL_TYPE]
* @for Skylink
* @since 0.1.0
*/
dataChannelState: [],
/**
* Event triggered when a data transfer state has changed.
* @event dataTransferState
* @param {String} state The current data transfer state.
* [Rel: Skylink.DATA_TRANSFER_STATE]
* @param {String} transferId The data transfer ID.
* @param {String} peerId The Peer ID.
* @param {JSON} transferInfo The data transfer information.
* @param {Blob|String} [transferInfo.data] The data object.
* <small>Defined only when <code>state</code> payload is <code>UPLOAD_STARTED</code> or
* <code>DOWNLOAD_COMPLETED</code>.</small>
* @param {String} transferInfo.name The data transfer name.
* @param {Number} transferInfo.size The data transfer data object original size.
* @param {String} transferInfo.dataType The data transfer session type.
* [Rel: Skylink.DATA_TRANSFER_SESSION_TYPE]
* @param {Number} transferInfo.timeout The flag if message is targeted or not, basing
* off the <code>targetPeerId</code> parameter being defined in
* <a href="#method_sendURLData"><code>sendURLData()</code> method</a> or
* <a href="#method_sendBlobData"><code>sendBlobData()</code> method</a>.
* @param {Boolean} transferInfo.isPrivate The flag if data transfer
* @param {JSON} [error] The error result.
* <small>Defined only when <code>state</code> payload is <code>ERROR</code> or <code>CANCEL</code>.</small>
* @param {Error|String} error.message The error object.
* @param {String} error.transferType The data transfer direction from where the error occurred.
* [Rel: Skylink.DATA_TRANSFER_TYPE]
* @for Skylink
* @since 0.4.1
*/
dataTransferState: [],
/**
* Event triggered when Signaling server reaction state has changed.
* @event systemAction
* @param {String} action The current Signaling server reaction state.
* [Rel: Skylink.SYSTEM_ACTION]
* @param {String} message The message.
* @param {String} reason The Signaling server reaction state reason of action code.
* [Rel: Skylink.SYSTEM_ACTION_REASON]
* @for Skylink
* @since 0.5.1
*/
systemAction: [],
/**
* Event triggered when a server Peer joins the room.
* @event serverPeerJoined
* @param {String} peerId The Peer ID.
* @param {String} serverPeerType The server Peer type
* [Rel: Skylink.SERVER_PEER_TYPE]
* @for Skylink
* @since 0.6.1
*/
serverPeerJoined: [],
/**
* Event triggered when a server Peer leaves the room.
* @event serverPeerLeft
* @param {String} peerId The Peer ID.
* @param {String} serverPeerType The server Peer type
* [Rel: Skylink.SERVER_PEER_TYPE]
* @for Skylink
* @since 0.6.1
*/
serverPeerLeft: [],
/**
* Event triggered when a server Peer connection has been refreshed.
* @event serverPeerRestart
* @param {String} peerId The Peer ID.
* @param {String} serverPeerType The server Peer type
* [Rel: Skylink.SERVER_PEER_TYPE]
* @for Skylink
* @since 0.6.1
*/
serverPeerRestart: [],
/**
* Event triggered when Peer Stream streaming has stopped.
* @event streamEnded
* @param {String} peerId The Peer ID.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelf The flag if Peer is User.
* @param {Boolean} isScreensharing The flag if Peer Stream is a screensharing Stream.
* @for Skylink
* @since 0.5.10
*/
streamEnded: [],
/**
* Event triggered when Peer Stream audio or video tracks has been muted.
* @event streamMuted
* @param {String} peerId The Peer ID.
* @param {JSON} peerInfo The Peer 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>
* @param {Boolean} isSelf The flag if Peer is User.
* @param {Boolean} isScreensharing The flag if Peer Stream is a screensharing Stream.
* @for Skylink
* @since 0.6.1
*/
streamMuted: [],
/**
* Event triggered when <a href="#method_getPeers"><code>getPeers()</code> method</a> retrieval state changes.
* @event getPeersStateChange
* @param {String} state The current <code>getPeers()</code> retrieval state.
* [Rel: Skylink.GET_PEERS_STATE]
* @param {String} privilegedPeerId The User's privileged Peer ID.
* @param {JSON} peerList The list of Peer IDs Rooms within the same App space.
* @param {Array} peerList.#room The list of Peer IDs associated with the Room defined in <code>#room</code> property.
* @for Skylink
* @since 0.6.1
*/
getPeersStateChange: [],
/**
* Event triggered when <a href="#method_introducePeer"><code>introducePeer()</code> method</a>
* introduction request state changes.
* @event introduceStateChange
* @param {String} state The current <code>introducePeer()</code> introduction request state.
* [Rel: Skylink.INTRODUCE_STATE]
* @param {String} privilegedPeerId The User's privileged Peer ID.
* @param {String} sendingPeerId The Peer ID to be connected with <code>receivingPeerId</code>.
* @param {String} receivingPeerId The Peer ID to be connected with <code>sendingPeerId</code>.
* @param {String} [reason] The error object.
* <small>Defined only when <code>state</code> payload is <code>ERROR</code>.</small>
* @for Skylink
* @since 0.6.1
*/
introduceStateChange: [],
/**
* Event triggered when <a href="#method_getConnectionStatus"><code>getConnectionStatus()</code> method</a>
* retrieval state changes.
* @event getConnectionStatusStateChange
* @param {Number} state The current <code>getConnectionStatus()</code> retrieval state.
* [Rel: Skylink.GET_CONNECTION_STATUS_STATE]
* @param {String} peerId The Peer ID.
* @param {JSON} [stats] The Peer connection current stats.
* <small>Defined only when <code>state</code> payload is <code>RETRIEVE_SUCCESS</code>.</small>
* @param {JSON} stats.raw The Peer connection raw stats before parsing.
* @param {JSON} stats.audio The Peer connection audio streaming stats.
* @param {JSON} stats.audio.sending The Peer connection sending audio streaming stats.
* @param {Number} stats.audio.sending.bytes The Peer connection sending audio streaming bytes.
* @param {Number} stats.audio.sending.packets The Peer connection sending audio streaming packets.
* @param {Number} stats.audio.sending.packetsLost The Peer connection sending audio streaming packets lost.
* @param {Number} stats.audio.sending.ssrc The Peer connection sending audio streaming RTP packets SSRC.
* @param {Number} stats.audio.sending.rtt The Peer connection sending audio streaming RTT (Round-trip delay time).
* <small>Defined as <code>0</code> if it's not present in original raw stats before parsing.</small>
* @param {JSON} stats.audio.receiving The Peer connection receiving audio streaming stats.
* @param {Number} stats.audio.receiving.bytes The Peer connection sending audio streaming bytes.
* @param {Number} stats.audio.receiving.packets The Peer connection receiving audio streaming packets.
* @param {Number} stats.audio.receiving.packetsLost The Peer connection receiving audio streaming packets lost.
* @param {Number} stats.audio.receiving.ssrc The Peer connection receiving audio streaming RTP packets SSRC.
* @param {JSON} stats.video The Peer connection video streaming stats.
* @param {JSON} stats.video.sending The Peer connection sending video streaming stats.
* @param {Number} stats.video.sending.bytes The Peer connection sending video streaming bytes.
* @param {Number} stats.video.sending.packets The Peer connection sending video streaming packets.
* @param {Number} stats.video.sending.packetsLost The Peer connection sending video streaming packets lost.
* @param {JSON} stats.video.sending.ssrc The Peer connection sending video streaming RTP packets SSRC.
* @param {Number} stats.video.sending.rtt The Peer connection sending video streaming RTT (Round-trip delay time).
* <small>Defined as <code>0</code> if it's not present in original raw stats before parsing.</small>
* @param {JSON} stats.video.receiving The Peer connection receiving video streaming stats.
* @param {Number} stats.video.receiving.bytes The Peer connection receiving video streaming bytes.
* @param {Number} stats.video.receiving.packets The Peer connection receiving video streaming packets.
* @param {Number} stats.video.receiving.packetsLost The Peer connection receiving video streaming packets lost.
* @param {Number} stats.video.receiving.ssrc The Peer connection receiving video streaming RTP packets SSRC.
* @param {JSON} stats.selectedCandidate The Peer connection selected ICE candidate pair stats.
* @param {JSON} stats.selectedCandidate.local The Peer connection selected local ICE candidate.
* @param {String} stats.selectedCandidate.local.ipAddress The Peer connection selected
* local ICE candidate IP address.
* @param {Number} stats.selectedCandidate.local.portNumber The Peer connection selected
* local ICE candidate port number.
* @param {String} stats.selectedCandidate.local.transport The Peer connection selected
* local ICE candidate IP transport type.
* @param {String} stats.selectedCandidate.local.candidateType The Peer connection selected
* local ICE candidate type.
* @param {JSON} stats.selectedCandidate.remote The Peer connection selected remote ICE candidate.
* @param {String} stats.selectedCandidate.remote.ipAddress The Peer connection selected
* remote ICE candidate IP address.
* @param {Number} stats.selectedCandidate.remote.portNumber The Peer connection selected
* remote ICE candidate port number.
* @param {String} stats.selectedCandidate.remote.transport The Peer connection selected
* remote ICE candidate IP transport type.
* @param {String} stats.selectedCandidate.remote.candidateType The Peer connection selected
* remote ICE candidate type.
* @param {JSON} stats.connection The Peer connection object stats.
* @param {String} stats.connection.iceConnectionState The Peer connection ICE connection state.
* @param {String} stats.connection.iceGatheringState The Peer connection ICE gathering state.
* @param {String} stats.connection.signalingState The Peer connection signaling state.
* @param {JSON} stats.connection.localDescription The Peer connection local session description.
* @param {String} stats.connection.localDescription.type The Peer connection local session description type.
* @param {String} stats.connection.localDescription.sdp The Peer connection local session description SDP.
* @param {JSON} stats.connection.remoteDescription The Peer connection remote session description.
* @param {String} stats.connection.remoteDescription.type The Peer connection remote session description type.
* @param {String} stats.connection.remoteDescription.sdp The Peer connection remote session description sdp.
* @param {JSON} stats.connection.candidates The Peer connection list of ICE candidates sent or received.
* @param {JSON} stats.connection.candidates.sending The Peer connection list of local ICE candidates sent.
* @param {Array} stats.connection.candidates.sending.host The Peer connection list of local
* <code>"host"</code> ICE candidates sent.
* @param {Array} stats.connection.candidates.sending.srflx The Peer connection list of local
* <code>"srflx"</code> ICE candidates sent.
* @param {Array} stats.connection.candidates.sending.relay The Peer connection list of local
* <code>"relay"</code> candidates sent.
* @param {JSON} stats.connection.candidates.receiving The Peer connection list of remote ICE candidates received.
* @param {Array} stats.connection.candidates.receiving.host The Peer connection list of remote
* <code>"host"</code> ICE candidates received.
* @param {Array} stats.connection.candidates.receiving.srflx The Peer connection list of remote
* <code>"srflx"</code> ICE candidates received.
* @param {Array} stats.connection.candidates.receiving.relay The Peer connection list of remote
* <code>"relay"</code> ICE candidates received.
* @param {Error} error The error object received.
* <small>Defined only when <code>state</code> payload is <code>RETRIEVE_ERROR</code>.</small>
* @for Skylink
* @since 0.6.14
*/
getConnectionStatusStateChange: []
};
/**
* Stores the list of <code>once()</code> event handlers.
* These events are only triggered once.
* @attribute _onceEvents
* @param {Array} <#event> The list of event handlers associated with the event.
* @param {Array} <#event>.<#index> The array of event handler function and its condition function.
* @type JSON
* @private
* @for Skylink
* @since 0.5.4
*/
Skylink.prototype._onceEvents = {};
/**
* Stores the timestamps data used for throttling.
* @attribute _timestamp
* @type JSON
* @private
* @for Skylink
* @since 0.5.8
*/
Skylink.prototype._timestamp = {
now: Date.now() || function() { return +new Date(); },
screen: false
};
/**
* Function that subscribes a listener to an event.
* @method on
* @param {String} eventName The event.
* @param {Function} callback The listener.
* <small>This will be invoked when event is triggered.</small>
* @example
* // Example 1: Subscribing to "peerJoined" event
* skylinkDemo.on("peerJoined", function (peerId, peerInfo, isSelf) {
* console.info("peerJoined event has been triggered with:", peerId, peerInfo, isSelf);
* });
* @for Skylink
* @since 0.1.0
*/
Skylink.prototype.on = function(eventName, callback) {
if ('function' === typeof callback) {
this._EVENTS[eventName] = this._EVENTS[eventName] || [];
this._EVENTS[eventName].push(callback);
log.log([null, 'Event', eventName, 'Event is subscribed']);
} else {
log.error([null, 'Event', eventName, 'Provided parameter is not a function']);
}
};
/**
* Function that subscribes a listener to an event once.
* @method once
* @param {String} eventName The event.
* @param {Function} callback The listener.
* <small>This will be invoked once when event is triggered and conditional function is satisfied.</small>
* @param {Function} [condition] The conditional function that will be invoked when event is triggered.
* <small>Return <code>true</code> when invoked to satisfy condition.</small>
* <small>When not provided, the conditional function will always return <code>true</code>.</small>
* @param {Boolean} [fireAlways=false] The flag that indicates if <code>once()</code> should act like
* <code>on()</code> but only invoke listener only when conditional function is satisfied.
* @example
* // Example 1: Subscribing to "peerJoined" event that triggers without condition
* skylinkDemo.once("peerJoined", function (peerId, peerInfo, isSelf) {
* console.info("peerJoined event has been triggered once with:", peerId, peerInfo, isSelf);
* });
*
* // Example 2: Subscribing to "incomingStream" event that triggers with condition
* skylinkDemo.once("incomingStream", function (peerId, stream, isSelf, peerInfo) {
* console.info("incomingStream event has been triggered with User stream:", stream);
* }, function (peerId, peerInfo, isSelf) {
* return isSelf;
* });
*
* // Example 3: Subscribing to "dataTransferState" event that triggers always only when condition is satisfied
* skylinkDemo.once("dataTransferState", function (state, transferId, peerId, transferInfo) {
* console.info("Received data transfer from Peer:", transferInfo.data);
* }, function (state, transferId, peerId) {
* if (state === skylinkDemo.DATA_TRANSFER_STATE.UPLOAD_REQUEST) {
* skylinkDemo.acceptDataTransfer(peerId, transferId);
* }
* return state === skylinkDemo.DATA_TRANSFER_STATE.DOWNLOAD_COMPLETED;
* }, true);
* @for Skylink
* @since 0.5.4
*/
Skylink.prototype.once = function(eventName, callback, condition, fireAlways) {
if (typeof condition === 'boolean') {
fireAlways = condition;
condition = null;
}
fireAlways = (typeof fireAlways === 'undefined' ? false : fireAlways);
condition = (typeof condition !== 'function') ? function () {
return true;
} : condition;
if (typeof callback === 'function') {
this._EVENTS[eventName] = this._EVENTS[eventName] || [];
// prevent undefined error
this._onceEvents[eventName] = this._onceEvents[eventName] || [];
this._onceEvents[eventName].push([callback, condition, fireAlways]);
log.log([null, 'Event', eventName, 'Event is subscribed on condition']);
} else {
log.error([null, 'Event', eventName, 'Provided callback is not a function']);
}
};
/**
* Function that unsubscribes listeners from an event.
* @method off
* @param {String} eventName The event.
* @param {Function} [callback] The listener to unsubscribe.
* - When not provided, all listeners associated to the event will be unsubscribed.
* @example
* // Example 1: Unsubscribe all "peerJoined" event
* skylinkDemo.off("peerJoined");
*
* // Example 2: Unsubscribe only one listener from "peerJoined event"
* var pJListener = function (peerId, peerInfo, isSelf) {
* console.info("peerJoined event has been triggered with:", peerId, peerInfo, isSelf);
* };
*
* skylinkDemo.off("peerJoined", pJListener);
* @for Skylink
* @since 0.5.5
*/
Skylink.prototype.off = function(eventName, callback) {
if (callback === undefined) {
this._EVENTS[eventName] = [];
this._onceEvents[eventName] = [];
log.log([null, 'Event', eventName, 'All events are unsubscribed']);
return;
}
var arr = this._EVENTS[eventName];
var once = this._onceEvents[eventName];
// unsubscribe events that is triggered always
for (var i = 0; i < arr.length; i++) {
if (arr[i] === callback) {
log.log([null, 'Event', eventName, 'Event is unsubscribed']);
arr.splice(i, 1);
break;
}
}
// unsubscribe events fired only once
if(once !== undefined) {
for (var j = 0; j < once.length; j++) {
if (once[j][0] === callback) {
log.log([null, 'Event', eventName, 'One-time Event is unsubscribed']);
once.splice(j, 1);
break;
}
}
}
};
/**
* Function that triggers an event.
* The rest of the parameters after the <code>eventName</code> parameter is considered as the event parameter payloads.
* @method _trigger
* @private
* @for Skylink
* @since 0.1.0
*/
Skylink.prototype._trigger = function(eventName) {
//convert the arguments into an array
var args = Array.prototype.slice.call(arguments);
var arr = this._EVENTS[eventName];
var once = this._onceEvents[eventName] || null;
args.shift(); //Omit the first argument since it's the event name
if (arr) {
// for events subscribed forever
for (var i = 0; i < arr.length; i++) {
try {
log.log([null, 'Event', eventName, 'Event is fired']);
if(arr[i].apply(this, args) === false) {
break;
}
} catch(error) {
log.error([null, 'Event', eventName, 'Exception occurred in event:'], error);
throw error;
}
}
}
if (once){
// for events subscribed on once
for (var j = 0; j < once.length; j++) {
if (once[j][1].apply(this, args) === true) {
log.log([null, 'Event', eventName, 'Condition is met. Firing event']);
if(once[j][0].apply(this, args) === false) {
break;
}
if (!once[j][2]) {
log.log([null, 'Event', eventName, 'Removing event after firing once']);
once.splice(j, 1);
//After removing current element, the next element should be element of the same index
j--;
}
} else {
log.log([null, 'Event', eventName, 'Condition is still not met. ' +
'Holding event from being fired']);
}
}
}
log.log([null, 'Event', eventName, 'Event is triggered']);
};
/**
* Function that checks if the current state condition is met before subscribing
* event handler to wait for condition to be fulfilled.
* @method _condition
* @private
* @for Skylink
* @since 0.5.5
*/
Skylink.prototype._condition = function(eventName, callback, checkFirst, condition, fireAlways) {
if (typeof condition === 'boolean') {
fireAlways = condition;
condition = null;
}
if (typeof callback === 'function' && typeof checkFirst === 'function') {
if (checkFirst()) {
log.log([null, 'Event', eventName, 'First condition is met. Firing callback']);
callback();
return;
}
log.log([null, 'Event', eventName, 'First condition is not met. Subscribing to event']);
this.once(eventName, callback, condition, fireAlways);
} else {
log.error([null, 'Event', eventName, 'Provided callback or checkFirst is not a function']);
}
};
/**
* Function that starts an interval check to wait for a condition to be resolved.
* @method _wait
* @private
* @for Skylink
* @since 0.5.5
*/
Skylink.prototype._wait = function(callback, condition, intervalTime, fireAlways) {
fireAlways = (typeof fireAlways === 'undefined' ? false : fireAlways);
if (typeof callback === 'function' && typeof condition === 'function') {
if (condition()) {
log.log([null, 'Event', null, 'Condition is met. Firing callback']);
callback();
return;
}
log.log([null, 'Event', null, 'Condition is not met. Doing a check.']);
intervalTime = (typeof intervalTime === 'number') ? intervalTime : 50;
var doWait = setInterval(function () {
if (condition()) {
log.log([null, 'Event', null, 'Condition is met after waiting. Firing callback']);
if (!fireAlways){
clearInterval(doWait);
}
callback();
}
}, intervalTime);
} else {
if (typeof callback !== 'function'){
log.error([null, 'Event', null, 'Provided callback is not a function']);
}
if (typeof condition !== 'function'){
log.error([null, 'Event', null, 'Provided condition is not a function']);
}
}
};
/**
* Function that throttles a method function to prevent multiple invokes over a specified amount of time.
* Returns a function to be invoked <code>._throttle(fn, 1000)()</code> to make throttling functionality work.
* @method _throttle
* @private
* @for Skylink
* @since 0.5.8
*/
Skylink.prototype._throttle = function(func, wait){
var self = this;
return function () {
if (!self._timestamp.func){
//First time run, need to force timestamp to skip condition
self._timestamp.func = self._timestamp.now - wait;
}
var now = Date.now();
if (now - self._timestamp.func < wait) {
return;
}
func.apply(self, arguments);
self._timestamp.func = now;
};
};