EasyRTC Client JsDocs

Members

<static> ackMessage

Most basic message acknowledgment object

<static> BECOMING_CONNECTED

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

<static> errCodes :Dictionary

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.

<static> initManaged

Deprecated:

now called easyrtc.easyApp.

<static> IS_CONNECTED

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

<static> myEasyrtcid

Your easyrtcid

<static> nativeVideoHeight

The height of the local media stream video in pixels. This field is set an indeterminate period of time after easyrtc.initMediaSource succeeds.

<static> nativeVideoWidth

The width of the local media stream video in pixels. This field is set an indeterminate period of time after easyrtc.initMediaSource succeeds.

<static> NOT_CONNECTED

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

<static> 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.

<static> usernameRegExp

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

Methods

<static> call(otherUser, callSuccessCB, callFailureCB, wasAcceptedCB)

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.

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));
           }
       });

<static> 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'));

<static> clearMediaStream(element)

Clears the media stream on a video object.

Parameters:

Name	Type	Description
`element`	DomElement	the video object.

Example

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

<static> 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.
`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("mychat_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);
                  });

<static> disconnect()

Disconnect from the EasyRTC server.

Example

   easyrtc.disconnect();

<static> 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

<static> dontAddCloseButtons()

By default, the easyApp routine sticks a "close" button on top of each caller video object that it manages. Call this function (before calling easyApp) to disable that particular feature.

Example

   easyrtc.dontAddCloseButtons();

<static> easyApp(applicationName, monitorVideoId, videoIds, onReady, onFailure)

Provides a layer on top of the easyrtc.initMediaSource and easyrtc.connect, assign the local media stream to the video object identified by monitorVideoId, assign remote video streams to the video objects identified by videoIds, and then call onReady. One of it's side effects is to add hangup buttons to the remote video objects, buttons that only appear when you hover over them with the mouse cursor. This method will also add the easyrtcMirror class to the monitor video object so that it behaves like a mirror.

Parameters:

Name	Type	Description
`applicationName`	String	name of the application.
`monitorVideoId`	String	the id of the video object used for monitoring the local stream.
`videoIds`	Array	an array of video object ids (strings)
`onReady`	Function	a callback function used on success. It is called with the easyrtcId this peer is knopwn to the server as.
`onFailure`	Function	a callbackfunction used on failure (failed to get local media or a connection of the signaling server).

Example

    easyrtc.easyApp('multiChat', 'selfVideo', ['remote1', 'remote2', 'remote3'],
             function (easyrtcId){
                 console.log("successfully connected, I am " + easyrtcId);
             },
             function(errorCode, errorText) {
                 console.log(errorText);
             );

<static> 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);

<static> enableCamera(enable)

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.

<static> 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);

<static> 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);

<static> enableMicrophone(enable)

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.

<static> 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);

<static> getApplicationFields() → {Dictionary}

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: Dictionary

<static> getConnectionCount() → {Number}

Returns the number of live peer connections the client has.

Returns:

Type: Number

Example

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

<static> getConnectionFields() → {Dictionary}

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: Dictionary

<static> getConnectStatus(otherUser) → {String}

Return true 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"); });
    }

<static> getFreshIceConfig()

Request fresh ice config information from the server. This should be done periodically by long running applications. There are no parameters or return values.

<static> 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:

Type: MediaStream

Example

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

<static> getLocalStreamAsUrl() → {URL}

Returns a URL for your local camera and microphone. It can be called only after easyrtc.initMediaSource has succeeded. It returns a url that can be used as a source by the Chrome video element or the <canvas> element.

Returns:

Type: URL

Example

     document.getElementById("myVideo").src = easyrtc.getLocalStreamAsUrl();

<static> getRoomFields(roomName) → {Dictionary}

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}}

Type: Dictionary

<static> 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} callback - 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);
        }
   );

<static> getRoomsJoined() → {Map}

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: Map

<static> 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.

<static> 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

<static> 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);

<static> hangupAll()

Hangs up on all current connections.

Example

   easyrtc.hangupAll();

<static> haveAudioTrack(easyrtcid) → {Boolean}

Determines if a particular peer2peer connection has an audio track.

Parameters:

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

Returns:

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

Type: Boolean

<static> haveVideoTrack(easyrtcid) → {Boolean}

Determines if a particular peer2peer connection has a video track.

Parameters:

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

Returns:

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

Type: Boolean

<static> 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));

<static> initMediaSource(successCallback, errorCallback)

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 when the media source is ready.
`errorCallback`	Function	is called with a message string if the attempt to get media failed.

Example

      easyrtc.initMediaSource(
         function (){
             easyrtc.setVideoObjectSrc( document.getElementById("mirrorVideo"), easyrtc.getLocalStream());
         },
         function (){
              easyrtc.showError("no-media", "Unable to get local media");
         });

<static> 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");
   }

<static> 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
`roomParameters`	String	: 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.

<static> 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() { console.log("left the room")},
                      function(errorCode, errroText) { console.log("left the room")});

<static> 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.

<static> sendData(destUser, msgType, msgData, ackHandler)

Sends data to another user. This method uses datachannels 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	an object which can be JSON'ed.
`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);
   );

<static> 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 datatypes you can send, and how large a datatype depends on your browser.

Parameters:

Name	Type	Description
`destUser`	String	(an easyrtcid)
`msgType`	String	the type of message being sent (application specific).
`msgData`	Object	an object which can be JSON'ed.

Example

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

<static> 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	an object which can be JSON'ed.
`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(ackmessage){
         console.log("saw the following acknowledgment " + JSON.stringify(ackmessage));
     }
   );

<static> 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(msgType, msgData)	a callback function with results from the server.
`failureCB`	Function(errorCode, errorText)	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);
            });

<static> 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(msgType, msgData)	a callback function with results from the server.
`failureCB`	Function(errorCode, errorText)	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);
            });

<static> setAcceptChecker(acceptCheck)

easyrtc.setAcceptChecker sets the callback used to decide whether to accept or reject an incoming call.

Parameters:

Name	Type	Description
`acceptCheck`	Function	takes the arguments (callerEasyrtcid, function ():boolean ){} The acceptCheck callback is passed (as it's second argument) a function that should be called with either a true value (accept the call) or false value( reject the call).

Example

     easyrtc.setAcceptChecker( function(easyrtcid, acceptor) {
          if( easyrtc.idToName(easyrtcid) === 'Fred' ){
             acceptor(true);
          }
          else if( easyrtc.idToName(easyrtcid) === 'Barney' ){
             setTimeout( function (){  acceptor(true)}, 10000);
          }
          else {
             acceptor(false);
          }
     });

<static> 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');

<static> 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));
        }
    });

<static> 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

<static> setCredential(credential)

Set the authentication credential if needed.

Parameters:

Name	Type	Description
`credential`	Object	a JSONifiable object.

<static> 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));
   });

<static> 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");
   });

<static> 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");
   });

<static> setGotConnection(gotConnectionCB)

Sets an event handler that gets called when a connection to the signaling server has or has not been made. Can only be called after calling easyrtc.easyApp.

Parameters:

Name	Type	Description
`gotConnectionCB`	Function	has the signature (gotConnection, errorText)

Example

   easyrtc.setGotConnection( function(gotConnection, errorText) {
       if( gotConnection ){
           console.log("Successfully connected to signaling server");
       }
       else {
           console.log("Failed to connect to signaling server because: " + errorText);
       }
   });

<static> setGotMedia(gotMediaCB)

Sets an event handler that gets called when the local media stream is created or not. Can only be called after calling easyrtc.easyApp.

Parameters:

Name	Type	Description
`gotMediaCB`	Function	has the signature function(gotMedia, errorText)

Example

    easyrtc.setGotMedia( function(gotMediaCB, errorText) {
        if( gotMedia ){
            console.log("Got the requested user media");
        }
        else {
            console.log("Failed to get media because: " +  errorText);
        }
    });

<static> setOnCall(cb)

Sets an event handler that gets called when a call is established. It's only purpose (so far) is to support transitions on video elements. This function is only defined after easyrtc.easyApp is called. The slot argument is the index into the array of video ids.

Parameters:

Name	Type	Description
`cb`	Function	has the signature function(easyrtcid, slot) {}

Example

  easyrtc.setOnCall( function(easyrtcid, slot) {
     console.log("call with " + easyrtcid + "established");
  });

<static> setOnError(errListener)

Sets the easyrtc.onError field to a user specified function.

Parameters:

Name	Type	Description
`errListener`	Function	takes an object of the form { errorCode: String, errorText: String}

Example

   easyrtc.setOnError( function(errorObject) {
       document.getElementById("errMessageDiv").innerHTML += errorObject.errorText;
   });

<static> setOnHangup(cb)

Sets an event handler that gets called when a call is ended. it's only purpose (so far) is to support transitions on video elements. x * this function is only defined after easyrtc.easyApp is called. The slot is parameter is the index into the array of video ids. Note: if you call easyrtc.getConnectionCount() from inside your callback it's count will reflect the number of connections before the hangup started.

Parameters:

Name	Type	Description
`cb`	Function	has the signature function(easyrtcid, slot) {}

Example

  easyrtc.setOnHangup( function(easyrtcid, slot) {
     console.log("call with " + easyrtcid + "ended");
  });

<static> 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.

Example

    easyrtc.setOnStreamClosed( function(easyrtcid) {
        easyrtc.setVideoObjectSrc( document.getElementById("callerVideo"), "");
        ( easyrtc.idToName(easyrtcid) + " went away");
    });

<static> 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) {
        ("From " + easyrtc.idToName(easyrtcid) +
            " sent the following data " + JSON.stringify(msgData));
    });
    easyrtc.setPeerListener( function(easyrtcid, msgType, msgData, targeting) {
        ("From " + easyrtc.idToName(easyrtcid) +
            " sent the following data " + JSON.stringify(msgData));
    }, 'food', 'dkdjdekj44--');
    easyrtc.setPeerListener( function(easyrtcid, msgType, msgData, targeting) {
        ("From " + easyrtcid +
            " sent the following data " + JSON.stringify(msgData));
    }, 'drink');

<static> 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`
`fieldName`		the name of the field.
`fieldValue`	Object	the value of the field.

Example

  easyrtc.setRoomApiFields("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);
     }
  });

<static> setRoomEntryListener(handler)

Set a callback that will be invoked when the application enters or leaves a room.

Parameters:

Name	Type	Description
`handler`	Function	the first parameter is true for entering a room, false for leaving a room. The second parameter is the room name.

Example

  easyrtc.setRoomEntryListener(function(entry, roomName) {
      if( entry ){
          console.log("entering room " + roomName);
      }
      else {
          console.log("leaving room " + roomName);
      }
  });

<static> setRoomOccupantListener(listener)

Set the callback that will be invoked when the list of people logged in changes. The callback expects to receive a room name argument, and a map whose ideas are easyrtcids and whose values are in turn maps supplying user specific information. The inner maps have the following keys: username, applicationName, browserFamily, browserMajor, osFamily, osMajor, deviceFamily. The third argument is the listener is the innerMap for the connections own data (not needed by most applications).

Parameters:

Name	Type	Description
`listener`	Function

Example

  easyrtc.setRoomOccupantListener( function(roomName, list, selfInfo) {
     for( var i in list ){
        ("easyrtcid=" + i + " belongs to user " + list[i].username);
     }
  });

<static> setScreenCapture()

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.

Example

   easyrtc.setScreenCapture();

<static> 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));
    });

<static> setSocketUrl(socketUrl)

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 webserver, but the EasyRTC library can still reach the socket server.

Parameters:

Name	Type	Description
`socketUrl`	DOMString

Example

    easyrtc.setSocketUrl(":8080");

<static> 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)

Example

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

<static> 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);

<static> setVideoBandwidth(kbitsPerSecond)

Sets the bandwidth for sending video data. Setting the rate too low will cause connection attempts to fail. 40 is probably good lower limit. The default is 50. A value of zero will remove bandwidth limits.

Parameters:

Name	Type	Description
`kbitsPerSecond`	Number	is rate in kilobits per second.

Example

   easyrtc.setVideoBandwidth( 40);

<static> setVideoDims(width, height)

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 default to 720p dimensions.

Parameters:

Name	Type	Description
`width`	Number	in pixels
`height`	Number	in pixels

Examples

   easyrtc.setVideoDims(1280,720);

   easyrtc.setVideoDims();

<static> setVideoObjectSrc(videoObject, 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 easyrtc.css, which is automatically added when you add the easyrtc.js file to an HTML file.

Parameters:

Name	Type	Description
`videoObject`	DOMObject	an HTML5 video object
`stream`	MediaStream	a media stream as returned by easyrtc.getLocalStream or your stream acceptor.

Example

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

<static> 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");

<static> 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

<static> supportsGetUserMedia() → {Boolean}

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

Returns:

True getUserMedia is supported.

Type: Boolean

<static> 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

<static> 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');

<static> usernameToIds(username, room)

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}.

Client API - Class easyrtc

Members

<static> ackMessage

<static> BECOMING_CONNECTED

<static> errCodes :Dictionary

<static> initManaged

<static> IS_CONNECTED

<static> myEasyrtcid

<static> nativeVideoHeight

<static> nativeVideoWidth

<static> NOT_CONNECTED

<static> roomJoin

<static> usernameRegExp

Methods

<static> call(otherUser, callSuccessCB, callFailureCB, wasAcceptedCB)

Parameters:

Example

<static> cleanId(idString) → {String}

Parameters:

Returns:

Example

<static> clearMediaStream(element)

Parameters:

Example

<static> connect(applicationName, successCallback, errorCallback)

Parameters:

Example

<static> disconnect()

Example

<static> doesDataChannelWork(otherUser) → {Boolean}

Parameters:

Returns:

<static> dontAddCloseButtons()

Example

<static> easyApp(applicationName, monitorVideoId, videoIds, onReady, onFailure)

Parameters:

Example

<static> enableAudio(enabled)

Parameters:

Example

<static> enableCamera(enable)

Parameters:

<static> enableDataChannels(enabled)

Parameters:

Example

<static> enableDebug(enable)

Parameters:

Example

<static> enableMicrophone(enable)

Parameters:

<static> enableVideo(enabled)

Parameters:

Example

<static> getApplicationFields() → {Dictionary}

Returns:

<static> getConnectionCount() → {Number}

Returns:

Example

<static> getConnectionFields() → {Dictionary}

Returns:

<static> getConnectStatus(otherUser) → {String}

Parameters:

Returns:

Example

<static> getFreshIceConfig()

<static> getLocalStream() → {MediaStream}

Returns:

Example

<static> getLocalStreamAsUrl() → {URL}

Returns:

Example

<static> getRoomFields(roomName) → {Dictionary}

Parameters:

Returns:

<static> getRoomList(callback, errorCallback)

Parameters:

Example

<static> getRoomsJoined() → {Map}

Returns:

<static> getSessionField(name)