Open-EasyRTC — Class: pub

new pub()

The public object which is returned by the EasyRTC listen() function. Contains all public methods for interacting with EasyRTC server.

Classes

events
util

Members

<static> events.defaultListeners

Map of EasyRTC event listener names to their default functions. This map can be used to run a default function manually.

<static> events.emit

Expose event listener's emit function.

<static> util.ApplicationError

Custom Error Object for EasyRTC Application Errors.

<static> util.ApplicationWarning

Custom Error Object for EasyRTC Application Warnings.

Methods

<static> app(appName, callback)

Contains the methods for interfacing with an EasyRTC application. The callback will receive an application object upon successful retrieval of application. The callback may receive an Error object if unsuccessful. Depending on the severity, known errors have an "instanceof" ApplicationWarning or ApplicationError. The function does return an application object which is useful for chaining, however the callback approach is safer and provides additional information in the event of an error.

Parameters:

Name	Type	Argument	Description
`appName`	string	<nullable>	Application name which uniquely identifies it on the server. Uses default application if null.
`callback`	appCallback	<optional>	Callback with error and application object

<static> createApp(appName, options, callback)

Creates a new EasyRTC application with default values. If a callback is provided, it will receive the new application object. The callback may receive an Error object if unsuccessful. Depending on the severity, known errors have an "instanceof" ApplicationWarning or ApplicationError.

Parameters:

Name	Type	Argument	Description
`appName`	string		Application name which uniquely identifies it on the server.
`options`	object	<nullable>	Options object with options to apply to the application. May be null.
`callback`	appCallback	<optional>	Callback with error and application object

<static> events.emitDefault(eventName, eventParam)

Runs the default EasyRTC listener for a given event.

Parameters:

Name	Type	Argument	Description
`eventName`	string		EasyRTC event name.
`eventParam`	*	<repeatable>	The event parameters

<static> events.on(eventName, listener)

Sets listener for a given EasyRTC event. Only one listener is allowed per event. Any other listeners for an event are removed before adding the new one. See the events documentation for expected listener parameters.

Parameters:

Name	Type	Description
`eventName`	string	Listener name.
`listener`	function	Function to be called when listener is fired

<static> events.removeAllListeners(eventName)

Removes all listeners for an event. If there is a default EasyRTC listener, it will be added. If eventName is `null`, all events will be removed than the defaults will be restored.

Parameters:

Name	Type	Argument	Description
`eventName`	string	<nullable>	Listener name. If `null`, then all events will be removed.

<static> events.setDefaultListener(eventName)

Resets the listener for a given event to the default listener. Removes other listeners.

Parameters:

Name	Type	Description
`eventName`	string	EasyRTC event name.

<static> events.setDefaultListeners()

Resets the listener for all EasyRTC events to the default listeners. Removes all other listeners.

<static> getAppNames(callback)

Sends an array of all application names to a callback.

Parameters:

Name	Type	Description
`callback`	function	Callback with error and array containing all application names.

<static> getAppWithEasyrtcid(easyrtcid, callback)

Gets app object for application which has an authenticated client with a given easyrtcid

Parameters:

Name	Type	Description
`easyrtcid`	String	Unique identifier for an EasyRTC connection.
`callback`	function	Callback with error and application object

<static> getConnectionCount(callback)

Sends the count of the number of connections to the server to a provided callback.

Parameters:

Name	Type	Description
`callback`	function	Callback with error and array containing all easyrtcids.

<static> getConnectionCountSync() → {Number}

Sends the count of the number of connections to the server to a provided callback.

Returns:

The current number of connections in a room.

Type: Number

<static> getConnectionWithEasyrtcid(easyrtcid, callback)

Gets connection object for connection which has an authenticated client with a given easyrtcid

Parameters:

Name	Type	Description
`easyrtcid`	string	EasyRTC unique identifier for a socket connection.
`callback`	function	Callback with error and connection object

<static> getOption(optionName) → {*}

Gets individual option value. The option value returned is for the server level. Note that some options can be set at the application or room level. If an option has not been set at the room level, it will check to see if it has been set at the application level, if not it will revert to the server level.

Parameters:

Name	Type	Description
`optionName`	String	Option name

Returns:

Option value (can be any JSON type)

Type: *

<static> getVersion() → {string}

Gets EasyRTC Version. The format is in a major.minor.patch format with an optional letter following denoting alpha or beta status. The version is retrieved from the package.json file located in the EasyRTC project root folder.

Returns:

EasyRTC Version

Type: string

<static> isApp(appName, callback)

Determine if a given application name has been defined.

Parameters:

Name	Type	Description
`appName`	string	Application name which uniquely identifies it on the server.
`callback`	function	Callback with error and boolean of whether application is defined.

<static> setOption(optionName, optionValue) → {Boolean}

Sets individual option. The option value set is for the server level. Note that some options can be set at the application or room level. If an option has not been set at the room level, it will check to see if it has been set at the application level, if not it will revert to the server level.

Parameters:

Name	Type	Description
`optionName`	Object	Option name
`optionValue`	Object	Option value

Returns:

true on success, false on failure

Type: Boolean

<static> util.ConnectionError(msg) → {Error}

Custom Error Object for EasyRTC C Errors.

Parameters:

Name	Type	Description
`msg`	string	Text message describing the error.

Returns:

Type: Error

<static> util.ConnectionWarning(msg) → {Error}

Custom Error Object for EasyRTC Connection Warnings.

Parameters:

Name	Type	Description
`msg`	string	Text message describing the error.

Returns:

Type: Error

<static> util.deepCopy(input) → {Object}

Performs a deep copy of an object, returning the duplicate. Do not use on objects with circular references.

Parameters:

Name	Type	Description
`input`	Object	Input variable (or object) to be copied.

Returns:

New copy of variable.

Type: Object

<static> util.getAvailableEasyrtcid() → {String}

Returns a random available easyrtcid.

Returns:

Available easyrtcid. A unique identifier for an EasyRTC connection.

Type: String

<static> util.getErrorMsg(errorCode) → {Object}

Returns an EasyRTC message error object for a specific error code. This is meant to be emitted or returned to a websocket client.

Parameters:

Name	Type	Description
`errorCode`	String	EasyRTC error code associated with an error.

Returns:

EasyRTC message error object for the specific error code.

Type: Object

<static> util.getErrorText(errorCode) → {string}

Returns human readable text for a given error code. If an unknown error code is provided, a null value will be returned.

Parameters:

Name	Type	Description
`errorCode`	String	EasyRTC error code associated with an error.

Returns:

Human readable error string

Type: string

<static> util.isError(Will) → {Boolean}

Determines if an Error object is an instance of ApplicationError, ConnectionError, or ServerError. If it is, it will return true.

Parameters:

Name	Type	Description
`Will`	* \| Error	accept any value, but will only return true for appropriate error objects.

Returns:

Type: Boolean

<static> util.isValidIncomingMessage(type, msg, appObj, callback)

Checks an incoming EasyRTC message to determine if it is syntactically valid.

Parameters:

Name	Type	Argument	Description
`type`	string		The Socket.IO message type. Expected values are (easyrtcAuth\|easyrtcCmd\|easyrtcMsg)
`msg`	Object		Message object which contains the full message from a client; this can include the standard msgType and msgData fields.
`appObj`	Object	<nullable>	EasyRTC application object. Contains methods used for identifying and managing an application.
`callback`	function		Callback with error, a boolean of whether message if valid, and a string indicating the error code if the message is invalid.

<static> util.isWarning(Will) → {Boolean}

Determines if an Error object is an instance of ApplicationWarning, ConnectionWarning, or ServerWarning. If it is, it will return true.

Parameters:

Name	Type	Description
`Will`	* \| Error	accept any value, but will only return true for appropriate error objects.

Returns:

Type: Boolean

<static> util.log(level, logText, logFields)

General logging function which emits a log event so long as the log level has a severity equal or greater than e.option.logLevel

Parameters:

Name	Type	Argument	Description
`level`	string		Log severity level. Can be ("debug"\|"info"\|"warning"\|"error")
`logText`	string		Text for log.
`logFields`	*	<optional> <nullable>	Simple JSON object which contains extra fields to be logged.

<static> util.logDebug(logText, logFields)

Convenience function for logging "debug" level items.

Parameters:

Name	Type	Argument	Description
`logText`	string		Text for log.
`logFields`	*	<optional> <nullable>	Simple JSON object which contains extra fields to be logged.

<static> util.logError(logText, logFields)

Convenience function for logging "error" level items.

Parameters:

Name	Type	Argument	Description
`logText`	string		Text for log.
`logFields`	*	<optional> <nullable>	Simple JSON object which contains extra fields to be logged.

<static> util.logInfo(logText, logFields)

Convenience function for logging "info" level items.

Parameters:

Name	Type	Argument	Description
`logText`	string		Text for log.
`logFields`	*	<optional> <nullable>	Simple JSON object which contains extra fields to be logged.

<static> util.logWarning(logText, logFields)

Convenience function for logging "warning" level items.

Parameters:

Name	Type	Argument	Description
`logText`	string		Text for log.
`logFields`	*	<optional> <nullable>	Simple JSON object which contains extra fields to be logged.

<static> util.nextToNowhere(err)

An empty dummy function, which is designed to be used as a default callback in functions when none has been provided.

Parameters:

Name	Type	Description
`err`	Error	Error object

<static> util.sendSessionCookie(req, res)

Will attempt to deliver an EasyRTC session id via a cookie. Requires that session management be enabled from within Express.

Parameters:

Name	Type	Description
`req`	Object	Http request object
`res`	Object	Http result object

<static> util.sendSocketCallbackAck(easyrtcid, socketCallback, appObj)

Sends an 'ack' socket message to a given socketCallback. Provides additional checking and logging.

Parameters:

Name	Type	Argument	Description
`easyrtcid`	string		EasyRTC unique identifier for a socket connection.
`socketCallback`	function		Socket.io callback function
`appObj`	Object	<nullable>	EasyRTC application object. Contains methods used for identifying and managing an application.

<static> util.sendSocketCallbackMsg(easyrtcid, socketCallback, msg, appObj)

Sends a complete socket message to a given socketCallback. Provides additional checking and logging.

Parameters:

Name	Type	Argument	Description
`easyrtcid`	string		EasyRTC unique identifier for a socket connection.
`socketCallback`	function		Socket.io callback function
`msg`	Object		Message object which contains the full message for a client; this can include the standard msgType and msgData fields.
`appObj`	Object	<nullable>	EasyRTC application object. Contains methods used for identifying and managing an application.

<static> util.ServerError(msg) → {Error}

Custom Error Object for EasyRTC Server Errors.

Parameters:

Name	Type	Description
`msg`	string	Text message describing the error.

Returns:

Type: Error

<static> util.ServerWarning(msg) → {Error}

Custom Error Object for EasyRTC Server Warnings.

Parameters:

Name	Type	Description
`msg`	string	Text message describing the error.

Returns:

Type: Error