Open-EasyRTC — Class: Easyrtc

new Easyrtc() → {Easyrtc}

Returns:

the new easyrtc instance.

Type: Easyrtc

Members

ackMessage

Most basic message acknowledgment object

BECOMING_CONNECTED

Value returned by easyrtc.getConnectStatus if the other user is in the process of getting connected

closeLocalStream

Alias for closeLocalMediaStream

cookieId

Default cookieId name

errCodes :Object

Error codes that the EasyRTC will use in the errorCode field of error object passed to error handler set by easyrtc.setOnError. The error codes are short printable strings.

Type:

Object

IS_CONNECTED

Value returned by easyrtc.getConnectStatus if the other user is connected to us.

loggingOut

Flag to indicate that user is currently logging out

maxP2PMessageLength

This constant determines how long (in bytes) a message can be before being split in chunks of that size. This is because there is a limitation of the length of the message you can send on the data channel between browsers.

myEasyrtcid

Your easyrtcid

nativeVideoHeight

The height of the local media stream video in pixels. This field is set an indeterminate period of time after easyrtc.initMediaSource succeeds. Note: in actuality, the dimensions of a video stream change dynamically in response to external factors, you should check the videoWidth and videoHeight attributes of your video objects before you use them for pixel specific operations.

nativeVideoWidth

The width of the local media stream video in pixels. This field is set an indeterminate period of time after easyrtc.initMediaSource succeeds. Note: in actuality, the dimensions of a video stream change dynamically in response to external factors, you should check the videoWidth and videoHeight attributes of your video objects before you use them for pixel specific operations.

NOT_CONNECTED

Value returned by easyrtc.getConnectStatus if the other user isn't connected to us.

roomJoin

The rooms the user is in. This only applies to room oriented applications and is set at the same time a token is received.

standardStatsFilter

This is a basic statistics filter that keesp just the generally useful information.

usernameRegExp

Regular expression pattern for user ids. This will need modification to support non US character sets

Methods

addEventListener(eventName, eventListener) → {void}

Adds an event listener for a particular type of event. Currently the only eventName supported is "roomOccupant".

Parameters:

Name	Type	Description
`eventName`	String	the type of the event
`eventListener`	function	the function that expects the event. The eventListener gets called with the eventName as it's first argument, and the event data as it's second argument.

Returns:

Type: void

addStreamToCall(easyrtcId, streamName, receiptHandler)

Add a named local stream to a call.

Parameters:

Name	Type	Description
`easyrtcId`	String	The id of client receiving the stream.
`streamName`	String	The name of the stream.
`receiptHandler`	function	is a function that gets called when the other side sends a message that the stream has been received. The receiptHandler gets called with an easyrtcid and a stream name. This argument is optional.

buildLocalMediaStream(streamName, audioTracks, videoTracks) → {MediaStream}

This function builds a new named local media stream from a set of existing audio and video tracks from other media streams.

Parameters:

Name	Type	Description
`streamName`	String	is the name of the new media stream.
`audioTracks`	Array	is an array of MediaStreamTracks
`videoTracks`	Array	is an array of MediaStreamTracks

Returns:

the track created.

Type: MediaStream

Example

easyrtc.buildLocalMediaStream("myComposedStream",
            easyrtc.getLocalStream("camera1").getVideoTracks(),
            easyrtc.getLocalStream("camera2").getAudioTracks());

call(otherUser, callSuccessCB, callFailureCB, wasAcceptedCB, streamNames)

Initiates a call to another user. If it succeeds, the streamAcceptor callback will be called.

Parameters:

Name	Type	Description
`otherUser`	String	the easyrtcid of the peer being called.
`callSuccessCB`	function	(otherCaller, mediaType) - is called when the datachannel is established or the MediaStream is established. mediaType will have a value of "audiovideo" or "datachannel"
`callFailureCB`	function	(errorCode, errMessage) - is called if there was a system error interfering with the call.
`wasAcceptedCB`	function	(wasAccepted:boolean,otherUser:string) - is called when a call is accepted or rejected by another party. It can be left null.
`streamNames`	Array	optional array of streamNames.

Example

easyrtc.call( otherEasyrtcid,
       function(easyrtcid, mediaType){
          console.log("Got mediaType " + mediaType + " from " + easyrtc.idToName(easyrtcid));
       },
       function(errorCode, errMessage){
          console.log("call to  " + easyrtc.idToName(otherEasyrtcid) + " failed:" + errMessage);
       },
       function(wasAccepted, easyrtcid){
           if( wasAccepted ){
              console.log("call accepted by " + easyrtc.idToName(easyrtcid));
           }
           else{
               console.log("call rejected" + easyrtc.idToName(easyrtcid));
           }
       });

cleanId(idString) → {String}

A convenience function to ensure that a string doesn't have symbols that will be interpreted by HTML.

Parameters:

Name	Type	Description
`idString`	String

Returns:

The cleaned string.

Type: String

Example

console.log( easyrtc.cleanId('&hello'));

clearMediaStream(element)

Clears the media stream on a video object.

Parameters:

Name	Type	Description
`element`	Object	the video object.

Example

easyrtc.clearMediaStream( document.getElementById('selfVideo'));

closeLocalMediaStream(streamName)

Close the local media stream. You usually need to close the existing media stream of a camera before reacquiring it at a different resolution.

Parameters:

Name	Type	Description
`streamName`	String	an option stream name.

connect(applicationName, successCallback, errorCallback)

Connects to the EasyRTC signaling server. You must connect before trying to call other users.

Parameters:

Name	Type	Description
`applicationName`	String	is a string that identifies the application so that different applications can have different lists of users. Note that the server configuration specifies a regular expression that is used to check application names for validity. The default pattern is that of an identifier, spaces are not allowed.
`successCallback`	function	(easyrtcId, roomOwner) - is called on successful connect. easyrtcId is the unique name that the client is known to the server by. A client usually only needs it's own easyrtcId for debugging purposes. roomOwner is true if the user is the owner of a room. It's value is random if the user is in multiple rooms.
`errorCallback`	function	(errorCode, errorText) - is called on unsuccessful connect. if null, an alert is called instead. The errorCode takes it's value from easyrtc.errCodes.

Example

easyrtc.connect("my_chat_app",
                  function(easyrtcid, roomOwner){
                      if( roomOwner){ console.log("I'm the room owner"); }
                      console.log("my id is " + easyrtcid);
                  },
                  function(errorText){
                      console.log("failed to connect ", erFrText);
                  });

disconnect()

Disconnect from the EasyRTC server.

Example

easyrtc.disconnect();

doesDataChannelWork(otherUser) → {Boolean}

Checks to see if data channels work between two peers.

Parameters:

Name	Type	Description
`otherUser`	String	the other peer.

Returns:

true if data channels work and are ready to be used between the two peers.

Type: Boolean

emitEvent(eventName, eventData)

Emits an event, or in other words, calls all the eventListeners for a particular event.

Parameters:

Name	Type	Description
`eventName`	String
`eventData`	Object

enableAudio(enabled)

Sets whether audio is transmitted by the local user in any subsequent calls.

Parameters:

Name	Type	Description
`enabled`	Boolean	true to include audio, false to exclude audio. The default is true.

Example

easyrtc.enableAudio(false);

enableAudioReceive(value)

Control whether the client requests audio from a peer during a call. Must be called before the call to have an effect.

Parameters:

Name	Type	Description
`value`		true to receive audio, false otherwise. The default is true.

enableCamera(enable, streamName)

This function is used to enable and disable the local camera. If you disable the camera, video objects display it will "freeze" until the camera is re-enabled. * By default, a camera is enabled.

Parameters:

Name	Type	Description
`enable`	Boolean	true to enable the camera, false to disable it.
`streamName`	String	the name of the stream, optional.

enableDataChannels(enabled)

Sets whether WebRTC data channels are used to send inter-client messages. This is only the messages that applications explicitly send to other applications, not the WebRTC signaling messages.

Parameters:

Name	Type	Description
`enabled`	Boolean	true to use data channels, false otherwise. The default is false.

Example

easyrtc.enableDataChannels(true);

enableDebug(enable)

Enable or disable logging to the console. Note: if you want to control the printing of debug messages, override the easyrtc.debugPrinter variable with a function that takes a message string as it's argument. This is exactly what easyrtc.enableDebug does when it's enable argument is true.

Parameters:

Name	Type	Description
`enable`	Boolean	true to turn on debugging, false to turn off debugging. Default is false.

Example

easyrtc.enableDebug(true);

enableMicrophone(enable, streamName)

This function is used to enable and disable the local microphone. If you disable the microphone, sounds stops being transmitted to your peers. By default, the microphone is enabled.

Parameters:

Name	Type	Description
`enable`	Boolean	true to enable the microphone, false to disable it.
`streamName`	String	an optional streamName.

enableVideo(enabled)

Sets whether video is transmitted by the local user in any subsequent calls.

Parameters:

Name	Type	Description
`enabled`	Boolean	true to include video, false to exclude video. The default is true.

Example

easyrtc.enableVideo(false);

enableVideoReceive(value)

Control whether the client requests video from a peer during a call. Must be called before the call to have an effect.

Parameters:

Name	Type	Description
`value`		true to receive video, false otherwise. The default is true.

format(format, arg1, arg2, arg3) → {String}

This function performs a printf like formatting. It actually takes an unlimited number of arguments, the declared arguments arg1, arg2, arg3 are present just for documentation purposes.

Parameters:

Name	Type	Description
`format`	String	A string like "abcd{1}efg{2}hij{1}."
`arg1`	String	The value that replaces {1}
`arg2`	String	The value that replaces {2}
`arg3`	String	The value that replaces {3}

Returns:

the formatted string.

Type: String

getApplicationFields() → {Object}

Get server defined fields associated with the current application. Only valid after a connection has been made.

Returns:

A dictionary containing entries of the form {key:{'fieldName':key, 'fieldValue':value1}}

Type: Object

getAudioSinkList(callback)

Gets a list of the available audio sinks (ie, speakers)

Parameters:

Name	Type	Description
`callback`	function	receives list of {deviceId:String, groupId:String, label:String, kind:"audio"}

Example

easyrtc.getAudioSinkList( function(list) {
              var i;
              for( i = 0; i < list.length; i++ ) {
                  console.log("label=" + list[i].label + ", id= " + list[i].deviceId);
              }
         });

getAudioSourceList(callback)

Gets a list of the available audio sources (ie, microphones)

Parameters:

Name	Type	Description
`callback`	function	receives list of {deviceId:String, groupId:String, label:String, kind:"audio"}

Example

easyrtc.getAudioSourceList( function(list) {
              var i;
              for( i = 0; i < list.length; i++ ) {
                  console.log("label=" + list[i].label + ", id= " + list[i].deviceId);
              }
         });

getConnectionCount() → {Number}

Returns the number of live peer connections the client has.

Returns:

Type: Number

Example

("You have " + easyrtc.getConnectionCount() + " peer connections");

getConnectionFields() → {Object}

Get server defined fields associated with the connection. Only valid after a connection has been made.

Returns:

A dictionary containing entries of the form {key:{'fieldName':key, 'fieldValue':value1}}

Type: Object

getConnectStatus(otherUser) → {String}

Check if the client has a peer-2-peer connection to another user. The return values are text strings so you can use them in debugging output.

Parameters:

Name	Type	Description
`otherUser`	String	the easyrtcid of the other user.

Returns:

one of the following values: easyrtc.NOT_CONNECTED, easyrtc.BECOMING_CONNECTED, easyrtc.IS_CONNECTED

Type: String

Example

if( easyrtc.getConnectStatus(otherEasyrtcid) == easyrtc.NOT_CONNECTED ){
        easyrtc.call(otherEasyrtcid,
                 function(){ console.log("success"); },
                 function(){ console.log("failure"); });
    }

getFreshIceConfig(callback)

Request fresh ice config information from the server. This should be done periodically by long running applications.

Parameters:

Name	Type	Description
`callback`	function	is called with a value of true on success, false on failure.

getLocalMediaIds() → {Array}

Returns the user assigned id's of currently active local media streams.

Returns:

Type: Array

getLocalStream() → {MediaStream}

Returns a media stream for your local camera and microphone. It can be called only after easyrtc.initMediaSource has succeeded. It returns a stream that can be used as an argument to easyrtc.setVideoObjectSrc. Returns null if there is no local media stream acquired yet.

Returns:

Type: MediaStream

Example

easyrtc.setVideoObjectSrc( document.getElementById("myVideo"), easyrtc.getLocalStream());

getPeerConnectionByUserId(easyrtcid, for)

This function gets the raw RTCPeerConnection for a given easyrtcid

Parameters:

Name	Type	Description
`easyrtcid`	String
`for`	RTCPeerConnection	that easyrtcid, or null if no connection exists Submitted by Fabian Bernhard.

getPeerStatistics(easyrtcid, callback, filter)

This function gets the statistics for a particular peer connection.

Parameters:

Name	Type	Description
`easyrtcid`	String
`callback`	function	gets the easyrtcid for the peer and a map of {userDefinedKey: value}. If there is no peer connection to easyrtcid, then the map will have a value of {connected:false}.
`filter`	Object	depends on whether Chrome or Firefox is used. See the default filters for guidance. It is still experimental.

getRemoteStream(easyrtcid, remoteStreamName) → {Object}

Return the media stream shared by a particular peer. This is needed when you add a stream in the middle of a call.

Parameters:

Name	Type	Description
`easyrtcid`	String	the peer.
`remoteStreamName`	String	an optional argument supplying the streamName.

Returns:

A mediaStream.

Type: Object

getRoomApiField(roomName, easyrtcid, fieldName) → {Object}

Returns another peers API field, if it exists.

Parameters:

Name	Type	Description
`roomName`	type
`easyrtcid`	type
`fieldName`	type

Returns:

Undefined if the attribute does not exist, its value otherwise.

Type: Object

getRoomField(roomName, fieldName) → {Object}

Gets a data field associated with a room.

Parameters:

Name	Type	Description
`roomName`	String	the name of the room.
`fieldName`	String	the name of the field.

Returns:

dataValue - the value of the field if present, undefined if not present.

Type: Object

getRoomFields(roomName) → {Object}

Get server defined fields associated with a particular room. Only valid after a connection has been made.

Parameters:

Name	Type	Description
`roomName`	String	the name of the room you want the fields for.

Returns:

A dictionary containing entries of the form {key:{'fieldName':key, 'fieldValue':value1}} or undefined if you are not connected to the room.

Type: Object

getRoomList(callback, errorCallback)

Sends the server a request for the list of rooms the user can see. You must have already be connected to use this function.

Parameters:

Name	Type	Description
`callback`	function	on success, this function is called with a map of the form { roomName:{"roomName":String, "numberClients": Number}}. The roomName appears as both the key to the map, and as the value of the "roomName" field.
`errorCallback`	function	is called on failure. It gets an errorCode and errorText as it's too arguments.

Example

easyrtc.getRoomList(
       function(roomList){
          for(roomName in roomList){
             console.log("saw room " + roomName);
          }
        },
        function(errorCode, errorText){
           easyrtc.showError(errorCode, errorText);
        }
   );

getRoomOccupantsAsArray(roomName) → {Array}

Returns an array of easyrtcid's of peers in a particular room.

Parameters:

Name	Type	Description
`roomName`

Returns:

of easyrtcids or null if the client is not in the room.

Type: Array

Example

var occupants = easyrtc.getRoomOccupants("default");
    var i;
    for( i = 0; i < occupants.length; i++ ) {
        console.log( occupants[i] + " is in the room");
    }

getRoomOccupantsAsMap(roomName) → {Object}

Returns a map of easyrtcid's of peers in a particular room. You should only test elements in the map to see if they are null; their actual values are not guaranteed to be the same in different releases.

Parameters:

Name	Type	Description
`roomName`

Returns:

of easyrtcids or null if the client is not in the room.

Type: Object

Example

if( easyrtc.getRoomOccupantsAsMap("default")[some_easyrtcid]) {
         console.log("yep, " + some_easyrtcid + " is in the room");
     }

getRoomsJoined() → {Object}

Get a list of the rooms you are in. You must be connected to call this function.

Returns:

A map whose keys are the room names

Type: Object

getServerIce() → {Object}

Returns the last ice config supplied by the EasyRTC server. This function is not normally used, it is provided for people who want to try filtering ice server configuration on the client.

Returns:

which has the form {iceServers:[ice_server_entry, ice_server_entry, ...]}

Type: Object

getSessionField(name)

Fetch the value of a session field by name.

Parameters:

Name	Type	Description
`name`	String	name of the session field to be fetched.

Returns:

the field value (which can be anything). Returns undefined if the field does not exist.

getSessionFields() → {Object}

Fetch the collection of session fields as a map. The map has the structure: {key1: {"fieldName": key1, "fieldValue": value1}, ..., key2: {"fieldName": key2, "fieldValue": value2} }

Returns:

Type: Object

getVideoSourceList(callback)

Gets a list of the available video sources (ie, cameras)

Parameters:

Name	Type	Description
`callback`	function	receives list of {deviceId:String, groupId:String, label:String, kind:"video"}

Example

easyrtc.getVideoSourceList( function(list) {
              var i;
              for( i = 0; i < list.length; i++ ) {
                  console.log("label=" + list[i].label + ", id= " + list[i].deviceId);
              }
         });

hangup(otherUser)

Hang up on a particular user or all users.

Parameters:

Name	Type	Description
`otherUser`	String	the easyrtcid of the person to hang up on.

Example

easyrtc.hangup(someEasyrtcid);

hangupAll()

Hangs up on all current connections.

Example

easyrtc.hangupAll();

haveAudioTrack(easyrtcid, streamName) → {Boolean}

Determines if a particular peer2peer connection has an audio track.

Parameters:

Name	Type	Description
`easyrtcid`	String	the id of the other caller in the connection. If easyrtcid is not supplied, checks the local media.
`streamName`	String	an optional stream id.

Returns:

true if there is an audio track or the browser can't tell us.

Type: Boolean

haveVideoTrack(easyrtcid, streamName) → {Boolean}

Determines if a particular peer2peer connection has a video track.

Parameters:

Name	Type	Description
`easyrtcid`	String	the id of the other caller in the connection. If easyrtcid is not supplied, checks the local media.
`streamName`	String	an optional stream id. *

Returns:

true if there is an video track or the browser can't tell us.

Type: Boolean

idToName(easyrtcid) → {String}

Convert an easyrtcid to a user name. This is useful for labeling buttons and messages regarding peers.

Parameters:

Name	Type	Description
`easyrtcid`	String

Returns:

the username associated with the easyrtcid, or the easyrtcid if there is no associated username.

Type: String

Example

console.log(easyrtcid + " is actually " + easyrtc.idToName(easyrtcid));

initMediaSource(successCallback, errorCallback, streamName)

Initializes your access to a local camera and microphone. Failure could be caused a browser that didn't support WebRTC, or by the user not granting permission. If you are going to call easyrtc.enableAudio or easyrtc.enableVideo, you need to do it before calling easyrtc.initMediaSource.

Parameters:

Name	Type	Description
`successCallback`	function	will be called with localmedia stream on success.
`errorCallback`	function	is called with an error code and error description.
`streamName`	String	an optional name for the media source so you can use multiple cameras and screen share simultaneously.

Example

easyrtc.initMediaSource(
         function(mediastream){
             easyrtc.setVideoObjectSrc( document.getElementById("mirrorVideo"), mediastream);
         },
         function(errorCode, errorText){
              easyrtc.showError(errorCode, errorText);
         });

isNameValid(name) → {Boolean}

Checks if the supplied string is a valid user name (standard identifier rules)

Parameters:

Name	Type	Description
`name`	String

Returns:

true for a valid user name

Type: Boolean

Example

var name = document.getElementById('nameField').value;
   if( !easyrtc.isNameValid(name)){
       console.error("Bad user name");
   }

isPeerInAnyRoom(easyrtcid)

Checks to see if a particular peer is present in any room. If it isn't, we assume it's logged out.

Parameters:

Name	Type	Description
`easyrtcid`	string	the easyrtcId of the peer.

isStunServer(ipAddress) → {boolean}

Returns true if the ipAddress parameter was the address of a stun server. This is done by checking against information collected during peer to peer calls. Don't expect it to work before the first call, or to identify turn servers that aren't in the ice config.

Parameters:

Name	Type	Description
`ipAddress`	string

Returns:

true if ip address is known to be that of a stun server, false otherwise.

Type: boolean

isTurnServer(ipAddress) → {boolean}

Returns true if the ipAddress parameter was the address of a turn server. This is done by checking against information collected during peer to peer calls. Don't expect it to work before the first call, or to identify turn servers that aren't in the ice config.

Parameters:

Name	Type	Description
`ipAddress`

Returns:

true if ip address is known to be that of a turn server, false otherwise.

Type: boolean

joinRoom(roomName, roomParameters, successCB, failureCB)

This method allows you to join a single room. It may be called multiple times to be in multiple rooms simultaneously. It may be called before or after connecting to the server. Note: the successCB and failureDB will only be called if you are already connected to the server.

Parameters:

Name	Type	Description
`roomName`	String	the room to be joined.
`roomParameters`	Object	application specific parameters, can be null.
`successCB`	function	called once, with a roomName as it's argument, once the room is joined.
`failureCB`	function	called if the room can not be joined. The arguments of failureCB are errorCode, errorText, roomName.

leaveRoom(roomName, successCallback, failureCallback)

This function allows you to leave a single room. Note: the successCB and failureDB arguments are optional and will only be called if you are already connected to the server.

Parameters:

Name	Type	Description
`roomName`	String
`successCallback`	function	A function which expects a roomName.
`failureCallback`	function	A function which expects the following arguments: errorCode, errorText, roomName.

Example

easyrtc.leaveRoom("freds_room");
   easyrtc.leaveRoom("freds_room", function(roomName){ console.log("left the room")},
                      function(errorCode, errorText, roomName){ console.log("left the room")});

loadStylesheet()

Load Easyrtc Stylesheet. Easyrtc Stylesheet define easyrtcMirror class and some basic css class for using easyrtc.js. That way, developers can override it or use it's own css file minified css or package.

Example

easyrtc.loadStylesheet();

makeLocalStreamFromRemoteStream(easyrtcid, remoteStreamName, localStreamName)

Assign a local streamName to a remote stream so that it can be forwarded to other callers.

Parameters:

Name	Type	Description
`easyrtcid`	String	the peer supplying the remote stream
`remoteStreamName`	String	the streamName supplied by the peer.
`localStreamName`	String	streamName used when passing the stream to other peers.

Example

easyrtc.makeLocalStreamFromRemoteStream(sourcePeer, "default", "forwardedStream");
   easyrtc.call(nextPeer, callSuccessCB, callFailureCB, wasAcceptedCB, ["forwardedStream"]);

muteVideoObject(videoObjectName, mute)

Mute a video object.

Parameters:

Name	Type	Description
`videoObjectName`	String	A DOMObject or the id of the DOMObject.
`mute`	Boolean	true to mute the video object, false to unmute it.

register3rdPartyLocalMediaStream(stream, streamName)

Allow an externally created mediastream (ie, created by another library) to be used within easyrtc. Tracking when it closes must be done by the supplying party.

Parameters:

Name	Type	Description
`stream`	MediaStream	the MediaStream to register.
`streamName`	String	the streamName of the new registered MediaStream.

removeEventListener(eventName, eventListener)

Removes an event listener.

Parameters:

Name	Type	Description
`eventName`	String
`eventListener`	function

removeStreamFromCall(easyrtcId, streamName)

Removes a mediastream from a peer connection.

Parameters:

Name	Type	Description
`easyrtcId`
`streamName`

renegotiate(otherUser)

This method is used to trigger renegotiation, which is how you you update change the properties of an existing connection (such as the the bandwidth used. Before calling it, you modify your sdp filters to reflect the desired changes.

Parameters:

Name	Type	Description
`otherUser`		the easyrtcid of the peer corresponding to the connection being updated.

sendData(destUser, msgType, msgData, ackHandler)

Sends data to another user. This method uses data channels if one has been set up, or websockets otherwise.

Parameters:

Name	Type	Description
`destUser`	String	a string containing the easyrtcId of the other user. Specifying multiple fields restricts the scope of the destination (operates as a logical AND, not a logical OR).
`msgType`	String	the type of message being sent (application specific).
`msgData`	Object	a JSONable object.
`ackHandler`	function	a function which receives acknowledgments. May only be invoked in the websocket case.

Example

easyrtc.sendData(someEasyrtcid, "roomData",  {room:499, bldgNum:'asd'},
      function ackHandler(msgType, msgData);
   );

sendDataP2P(destUser, msgType, msgData)

Sends data to another user using previously established data channel. This method will fail if no data channel has been established yet. Unlike the easyrtc.sendWS method, you can't send a dictionary, convert dictionaries to strings using JSON.stringify first. What data types you can send, and how large a data type depends on your browser.

Parameters:

Name	Type	Description
`destUser`	String	(an easyrtcid)
`msgType`	String	the type of message being sent (application specific).
`msgData`	Object	a JSONable object.

Example

easyrtc.sendDataP2P(someEasyrtcid, "roomData", {room:499, bldgNum:'asd'});

sendDataWS(destination, msgType, msgData, ackhandler)

Sends data to another user using websockets. The easyrtc.sendServerMessage or easyrtc.sendPeerMessage methods are wrappers for this method; application code should use them instead.

Parameters:

Name	Type	Description
`destination`	String	either a string containing the easyrtcId of the other user, or an object containing some subset of the following fields: targetEasyrtcid, targetGroup, targetRoom. Specifying multiple fields restricts the scope of the destination (operates as a logical AND, not a logical OR).
`msgType`	String	the type of message being sent (application specific).
`msgData`	Object	a JSONable object.
`ackhandler`	function	by default, the ackhandler handles acknowledgments from the server that your message was delivered to it's destination. However, application logic in the server can over-ride this. If you leave this null, a stub ackHandler will be used. The ackHandler gets passed a message with the same msgType as your outgoing message, or a message type of "error" in which case msgData will contain a errorCode and errorText fields.

Example

easyrtc.sendDataWS(someEasyrtcid, "setPostalAddress", {room:499, bldgNum:'asd'},
     function(ackMsg){
         console.log("saw the following acknowledgment " + JSON.stringify(ackMsg));
     }
   );

sendPeerMessage(destination, msgType, msgData, successCB, failureCB)

Sends a message to another peer on the easyrtcMsg channel.

Parameters:

Name	Type	Description
`destination`	String	either a string containing the easyrtcId of the other user, or an object containing some subset of the following fields: targetEasyrtcid, targetGroup, targetRoom. Specifying multiple fields restricts the scope of the destination (operates as a logical AND, not a logical OR).
`msgType`	String	the type of message being sent (application specific).
`msgData`	Object	a JSONable object with the message contents.
`successCB`	function	a callback function with results from the server.
`failureCB`	function	a callback function to handle errors.

Example

easyrtc.sendPeerMessage(otherUser, 'offer_candy', {candy_name:'mars'},
            function(msgType, msgBody ){
               console.log("message was sent");
            },
            function(errorCode, errorText){
               console.log("error was " + errorText);
            });

sendServerMessage(msgType, msgData, successCB, failureCB)

Sends a message to the application code in the server (ie, on the easyrtcMsg channel).

Parameters:

Name	Type	Description
`msgType`	String	the type of message being sent (application specific).
`msgData`	Object	a JSONable object with the message contents.
`successCB`	function	a callback function with results from the server.
`failureCB`	function	a callback function to handle errors.

Example

easyrtc.sendServerMessage('get_candy', {candy_name:'mars'},
            function(msgType, msgData ){
               console.log("got candy count of " + msgData.barCount);
            },
            function(errorCode, errorText){
               console.log("error was " + errorText);
            });

setAcceptChecker(acceptCheck)

Sets the callback used to decide whether to accept or reject an incoming call.

Parameters:

Name	Type	Description
`acceptCheck`	function	takes the arguments (callerEasyrtcid, acceptor). The acceptCheck callback is passed an easyrtcid and an acceptor function. The acceptor function should be called with either a true value (accept the call) or false value( reject the call) as it's first argument, and optionally, an array of local media streamNames as a second argument.

Example

easyrtc.setAcceptChecker( function(easyrtcid, acceptor){
          if( easyrtc.idToName(easyrtcid) === 'Fred' ){
             acceptor(true);
          }
          else if( easyrtc.idToName(easyrtcid) === 'Barney' ){
             setTimeout( function(){
     acceptor(true, ['myOtherCam']); // myOtherCam presumed to a streamName
     }, 10000);
          }
          else{
             acceptor(false);
          }
     });

setApplicationName(name)

Set the application name. Applications can only communicate with other applications that share the same API Key and application name. There is no predefined set of application names. Maximum length is

Parameters:

Name	Type	Description
`name`	String

Example

easyrtc.setApplicationName('simpleAudioVideo');

setAudioOutput(element, sinkId)

Sets the audio output device of a Video object. That is to say, this controls what speakers get the sound. In theory, this works on Chrome but probably doesn't work anywhere else yet. This code was cribbed from https://webrtc.github.io/samples/src/content/devices/multi/.

Parameters:

Name	Type	Description
`element`	Object	an HTML5 video element
`sinkId`	String	a deviceid from getAudioSinkList

setAudioSource(audioSrcId)

Specify particular video source. Call this before you call easyrtc.initMediaSource().

Parameters:

Name	Type	Description
`audioSrcId`	String	is a id value from one of the entries fetched by getAudioSourceList. null for default.

Example

easyrtc.setAudioSource( audioSrcId);

setAutoInitUserMedia(flag)

Controls whether a default local media stream should be acquired automatically during calls and accepts if a list of streamNames is not supplied. The default is true, which mimics the behaviour of earlier releases that didn't support multiple streams. This function should be called before easyrtc.call or before entering an accept callback.

Parameters:

Name	Type	Description
`flag`	Boolean	true to allocate a default local media stream.

setCallCancelled(callCancelled)

Sets the callCancelled callback. This will be called when a remote user initiates a call to you, but does a "hangup" before you have a chance to get his video stream.

Parameters:

Name	Type	Description
`callCancelled`	function	takes an easyrtcid as an argument and a boolean that indicates whether the call was explicitly cancelled remotely (true), or actually accepted by the user attempting a call to the same party.

Example

easyrtc.setCallCancelled( function(easyrtcid, explicitlyCancelled){
       if( explicitlyCancelled ){
           console.log(easyrtc.idToName(easyrtcid) + " stopped trying to reach you");
        }
        else{
           console.log("Implicitly called "  + easyrtc.idToName(easyrtcid));
        }
    });

setCookieId(cookieId)

This function sets the name of the cookie that client side library will look for and transmit back to the server as it's easyrtcsid in the first message.

Parameters:

Name	Type	Description
`cookieId`	String

setCredential(credentialParm, successCallback, failureCallback)

Set the authentication credential if needed.

Parameters:

Name	Type	Description
`credentialParm`	Object	a JSONable object.
`successCallback`	function	A function which expects a boolean.
`failureCallback`	function	A function which expects the following arguments: errorCode, errorText, roomName.

setDataChannelCloseListener(listener)

Sets a callback that is called when a previously open data channel closes. The callback will be called with an easyrtcid as it's sole argument.

Parameters:

Name	Type	Description
`listener`	function

Example

easyrtc.setDataChannelCloseListener( function(easyrtcid){
           ("No longer connected to " + easyrtc.idToName(easyrtcid));
   });

setDataChannelOpenListener(listener)

Sets a callback that is called when a data channel is open and ready to send data. The callback will be called with an easyrtcid as it's sole argument.

Parameters:

Name	Type	Description
`listener`	function

Example

easyrtc.setDataChannelOpenListener( function(easyrtcid){
        easyrtc.sendDataP2P(easyrtcid, "greeting", "hello");
   });

setDisconnectListener(disconnectListener)

Sets the listener for socket disconnection by external (to the API) reasons.

Parameters:

Name	Type	Description
`disconnectListener`	function	takes no arguments and is not called as a result of calling easyrtc.disconnect.

Example

easyrtc.setDisconnectListener(function(){
       easyrtc.showError("SYSTEM-ERROR", "Lost our connection to the socket server");
   });

setErrorListener(handler)

Override the default open-easyrtc error handler. The default handler shows a popup error dialog.

Parameters:

Name	Type	Description
`handler`	function	Error handler function with one param, an object with keys 'errorCode' and 'errorText'

Examples

easyrtc.setErrorListener(({errorCode, errorText}) => {
   alert(`${errorCode} error:\n${errorText}`);
});

// Removing previously set handler:
easyrtc.setErrorListener(undefined);

setIceCandidateFilter(filter)

Sets a function which filters IceCandidate records being sent or received. Candidate records can be received while they are being generated locally (before being sent to a peer), and after they are received by the peer. The filter receives two arguments, the candidate record and a boolean flag that is true for a candidate being received from another peer, and false for a candidate that was generated locally. The candidate record has the form: {type: 'candidate', label: sdpMLineIndex, id: sdpMid, candidate: candidateString} The function should return one of the following: the input candidate record, a modified candidate record, or null (indicating that the candidate should be discarded).

Parameters:

Name	Type	Description
`filter`	function

setIceConnectionStateChangeListener(listener)

Sets a function that listens on IceConnectionStateChange events. During ICE negotiation the peer connection fires the iceconnectionstatechange event. It is sometimes useful for the application to learn about these changes, especially if the ICE connection fails. The function should accept three parameters: the easyrtc id of the peer, the iceconnectionstatechange event target and the iceconnectionstate.

Parameters:

Name	Type	Description
`listener`	function

setIceUsedInCalls(ice)

Sets the ice server configuration that will be used in subsequent calls. You only need this function if you are filtering the ice server configuration on the client or if you are using TURN certificates that have a very short lifespan.

Parameters:

Name	Type	Description
`ice`	Object	An object with iceServers element containing an array of ice server entries.

Example

easyrtc.setIceUsedInCalls( {"iceServers": [
     {
        "url": "stun:stun.sipgate.net"
     },
     {
        "url": "stun:217.10.68.152"
     },
     {
        "url": "stun:stun.sipgate.net:10000"
     }
     ]});
     easyrtc.call(...);

setMaxP2PMessageLength(maxLength)

Sets the maximum length in bytes of P2P messages that can be sent.

Parameters:

Name	Type	Description
`maxLength`	Number	maximum length to set

Example

easyrtc.setMaxP2PMessageLength(10000);

setOnStreamClosed(onStreamClosed)

Sets a callback to receive notification of a media stream closing. The usual use of this is to clear the source of your video object so you aren't left with the last frame of the video displayed on it.

Parameters:

Name	Type	Description
`onStreamClosed`	function	takes an easyrtcid as it's first parameter, the stream as it's second argument, and name of the video stream as it's third.

Example

easyrtc.setOnStreamClosed( function(easyrtcid, stream, streamName){
        easyrtc.setVideoObjectSrc( document.getElementById("callerVideo"), "");
        ( easyrtc.idToName(easyrtcid) + " closed stream " + stream.id + " " + streamName);
    });

setPeerClosedListener(handler:)

Sets a function to warn about the peer connection closing.

Parameters:

Name	Type	Description
`handler:`	function	a function that gets an easyrtcid as an argument.

setPeerConnectionConfig()

Sets the peer connection configuration that will be used in subsequent calls.

setPeerFailingListener(failingHandler:, recoveredHandler:)

Sets a function to receive warnings about the peer connection failing. The peer connection may recover by itself.

Parameters:

Name	Type	Description
`failingHandler:`	function	a function that gets an easyrtcid as an argument.
`recoveredHandler:`	function	a function that gets an easyrtcid as an argument.

setPeerListener(listener, msgType, source)

Sets a listener for data sent from another client (either peer to peer or via websockets). If no msgType or source is provided, the listener applies to all events that aren't otherwise handled. If a msgType but no source is provided, the listener applies to all messages of that msgType that aren't otherwise handled. If a msgType and a source is provided, the listener applies to only message of the specified type coming from the specified peer. The most specific case takes priority over the more general.

Parameters:

Name	Type	Description
`listener`	function	has the signature (easyrtcid, msgType, msgData, targeting). msgType is a string. targeting is null if the message was received using WebRTC data channels, otherwise it is an object that contains one or more of the following string valued elements {targetEasyrtcid, targetGroup, targetRoom}.
`msgType`	String	a string, optional.
`source`	String	the sender's easyrtcid, optional.

Example

easyrtc.setPeerListener( function(easyrtcid, msgType, msgData, targeting){
        console.log("From " + easyrtc.idToName(easyrtcid) +
            " sent the following data " + JSON.stringify(msgData));
    });
    easyrtc.setPeerListener( function(easyrtcid, msgType, msgData, targeting){
        console.log("From " + easyrtc.idToName(easyrtcid) +
            " sent the following data " + JSON.stringify(msgData));
    }, 'food', 'dkdjdekj44--');
    easyrtc.setPeerListener( function(easyrtcid, msgType, msgData, targeting){
        console.log("From " + easyrtcid +
            " sent the following data " + JSON.stringify(msgData));
    }, 'drink');

setPeerOpenListener(handler:)

Sets a function to warn about the peer connection open.

Parameters:

Name	Type	Description
`handler:`	function	a function that gets an easyrtcid as an argument.

setRoomApiField(roomName, fieldName, fieldValue)

Provide a set of application defined fields that will be part of this instances configuration information. This data will get sent to other peers via the websocket path.

Parameters:

Name	Type	Description
`roomName`	String	the room the field is attached to.
`fieldName`	String	the name of the field.
`fieldValue`	Object	the value of the field.

Example

easyrtc.setRoomApiField("trekkieRoom",  "favorite_alien", "Mr Spock");
  easyrtc.setRoomOccupantListener( function(roomName, list){
     for( var i in list ){
        console.log("easyrtcid=" + i + " favorite alien is " + list[i].apiFields.favorite_alien);
     }
  });

setScreenCapture(enableScreenCapture, mediaSourceId)

This function requests that screen capturing be used to provide the local media source rather than a webcam. If you have multiple screens, they are composited side by side. Note: this functionality is not supported by Firefox, has to be called before calling initMediaSource (or easyApp), we don't currently supply a way to turn it off (once it's on), only works if the website is hosted SSL (https), and the image quality is rather poor going across a network because it tries to transmit so much data. In short, screen sharing through WebRTC isn't worth using at this point, but it is provided here so people can try it out.

Parameters:

Name	Type	Description
`enableScreenCapture`	Boolean
`mediaSourceId`	String	(optional)

Example

easyrtc.setScreenCapture(true);

setSdpFilters(localFilter, remoteFilter)

Sets functions which filter sdp records before calling setLocalDescription or setRemoteDescription. This is advanced functionality which can break things, easily. See the easyrtc_rates.js file for a filter builder.

Parameters:

Name	Type	Description
`localFilter`	function	a function that takes an sdp string and returns an sdp string.
`remoteFilter`	function	a function that takes an sdp string and returns an sdp string.

setServerListener(listener)

Sets a listener for messages from the server.

Parameters:

Name	Type	Description
`listener`	function	has the signature (msgType, msgData, targeting)

Example

easyrtc.setServerListener( function(msgType, msgData, targeting){
        ("The Server sent the following message " + JSON.stringify(msgData));
    });

setSignalingStateChangeListener(listener)

Sets a function that listens on SignalingStateChange events. During ICE negotiation the peer connection fires the signalingstatechange event. The function should accept three parameters: the easyrtc id of the peer, the signalingstatechange event target and the signalingstate.

Parameters:

Name	Type	Description
`listener`	function

setSocketUrl(socketUrl, options)

Sets the url of the Socket server. The node.js server is great as a socket server, but it doesn't have all the hooks you'd like in a general web server, like PHP or Python plug-ins. By setting the serverPath your application can get it's regular pages from a regular web server, but the EasyRTC library can still reach the socket server.

Parameters:

Name	Type	Description
`socketUrl`	String
`options`	Object	an optional dictionary of options for socket.io's connect method. The default is {'connect timeout': 10000,'force new connection': true }

Example

easyrtc.setSocketUrl(":8080", options);

setStreamAcceptor(acceptor)

easyrtc.setStreamAcceptor sets a callback to receive media streams from other peers, independent of where the call was initiated (caller or callee).

Parameters:

Name	Type	Description
`acceptor`	function	takes arguments (caller, mediaStream, mediaStreamName)

Example

easyrtc.setStreamAcceptor(function(easyrtcid, stream, streamName){
    document.getElementById('callerName').innerHTML = easyrtc.idToName(easyrtcid);
    easyrtc.setVideoObjectSrc( document.getElementById("callerVideo"), stream);
 });

setUseFreshIceEachPeerConnection(value)

Determines whether fresh ice server configuration should be requested from the server for each peer connection.

Parameters:

Name	Type	Description
`value`	Boolean	the default is false.

setUsername(username) → {Boolean}

Sets the user name associated with the connection.

Parameters:

Name	Type	Description
`username`	String	must obey standard identifier conventions.

Returns:

true if the call succeeded, false if the username was invalid.

Type: Boolean

Example

if( !easyrtc.setUsername("JohnSmith") ){
       console.error("bad user name);
   }

setVideoDims(width, height, frameRate)

This function is used to set the dimensions of the local camera, usually to get HD. If called, it must be called before calling easyrtc.initMediaSource (explicitly or implicitly). assuming it is supported. If you don't pass any parameters, it will use default camera dimensions.

Parameters:

Name	Type	Description
`width`	Number	in pixels
`height`	Number	in pixels
`frameRate`	number	is optional

Examples

easyrtc.setVideoDims(1280,720);

easyrtc.setVideoDims();

setVideoObjectSrc(element, stream)

Sets a video or audio object from a media stream. Chrome uses the src attribute and expects a URL, while firefox uses the mozSrcObject and expects a stream. This procedure hides that from you. If the media stream is from a local webcam, you may want to add the easyrtcMirror class to the video object so it looks like a proper mirror. The easyrtcMirror class is defined in this.css. Which is could be added using the same path of easyrtc.js file to an HTML file

Parameters:

Name	Type	Description
`element`	Object	an HTML5 video element
`stream`	MediaStream \| String	a media stream as returned by easyrtc.getLocalStream or your stream acceptor.

Example

easyrtc.setVideoObjectSrc( document.getElementById("myVideo"), easyrtc.getLocalStream());

setVideoSource(videoSrcId)

Specify particular video source. Call this before you call easyrtc.initMediaSource().

Parameters:

Name	Type	Description
`videoSrcId`	String	is a id value from one of the entries fetched by getVideoSourceList. null for default.

Example

easyrtc.setVideoSource( videoSrcId);

showError(messageCode, message)

Default error reporting function. The default implementation displays error messages in a programmatically created div with the id easyrtcErrorDialog. The div has title component with a class name of easyrtcErrorDialog_title. The error messages get added to a container with the id easyrtcErrorDialog_body. Each error message is a text node inside a div with a class of easyrtcErrorDialog_element. There is an "okay" button with the className of easyrtcErrorDialog_okayButton.

Parameters:

Name	Type	Description
`messageCode`	String	An error message code
`message`	String	the error message text without any markup.

Example

easyrtc.showError("BAD_NAME", "Invalid username");

supportsDataChannels() → {Boolean}

Determines whether the current browser supports the new data channels. EasyRTC will not open up connections with the old data channels.

Returns:

Type: Boolean

supportsGetUserMedia() → {Boolean}

Determines if the local browser supports WebRTC GetUserMedia (access to camera and microphone).

Returns:

True getUserMedia is supported.

Type: Boolean

supportsPeerConnections() → {Boolean}

Determines if the local browser supports WebRTC Peer connections to the extent of being able to do video chats.

Returns:

True if Peer connections are supported.

Type: Boolean

updatePresence(state, statusText)

Sets the presence state on the server.

Parameters:

Name	Type	Description
`state`	String	one of 'away','chat','dnd','xa'
`statusText`	String	User configurable status string. May be length limited.

Example

easyrtc.updatePresence('dnd', 'sleeping');

usernameToIds(username, room) → {Array}

Get an array of easyrtcids that are using a particular username

Parameters:

Name	Type	Description
`username`	String	the username of interest.
`room`	String	an optional room name argument limiting results to a particular room.

Returns:

an array of {easyrtcid:id, roomName: roomName}.

Type: Array

useThisSocketConnection(alreadyAllocatedSocketIo)

Supply a socket.io connection that will be used instead of allocating a new socket. The expected usage is that you allocate a websocket, assign options to it, call easyrtc.useThisSocketConnection, followed by easyrtc.connect or easyrtc.easyApp. Easyrtc will not attempt to close sockets that were supplied with easyrtc.useThisSocketConnection.

Parameters:

Name	Type	Description
`alreadyAllocatedSocketIo`	Object	A value allocated with the connect method of socket.io.