• English
  • Français

Class ApideoRoom

public class ApideoRoom
An ApideoRoom is an object used to start streaming your video, view other's streams, send and receive events, track users and much more. ApideoRoom objects are created using the ApideoConnection.joinRoom function.
Defined in apideo.js

Function Summary
public void countUsers (function filter)
Returns the count of users in this room.
public void forEachUser (function callback, function filter)
This function performs a "for each" on the list of users in the room.
public void getMyUserData()
Returns the user data associated for the local user.
public string getMyUserId()
Returns the ID of the user in the current room.
public void getUserData (string userId)
Returns the user data associated with the ID of the user that is passed in parameter.
public void getUserJoinDate (string userId)
Returns the time when the user passed in parameter joined this room.
public void getUserModifyDate (string userId)
Returns the time when the user passed in parameter modified his user data for this room.
public boolean hasCamera()
Returns true if there is at least one webcam connected to this computer, false otherwise.
public boolean hasMicrophone()
Returns true if there is at least one microphone connected to this computer, false otherwise.
public void onError (Object callback)
Registers a callback function that will be called if an error occurs in the room.
public boolean onLoad (Object callback)
Registers a callback function that will be called when the Apideo room is successfully joined.
public boolean onSecurityError (Object callback)
Registers a callback function that will be called if access to the room is denied by Apideo.
public boolean onUserJoin (Object callback)
Registers a callback function that will be called when a new user joins the Apideo room.
public boolean onUserQuit (Object callback)
Registers a callback function that will be called when a user quits the Apideo room.
public boolean onUserUpdate (Object callback)
Registers a callback function that will be called when a user updates his JsonObject using the ApideoRoom.updateUser() method.
public ApideoViewer playStream (string divId, string streamId, [JsonObject config])
Starts playing a video from the Apideo server.
public void registerListener (function(JsonObject event, string senderId, boolean triggerListener) eventListener, string type, [boolean blockPropagation])
Register a listener for an event type.
public void removeAllCameras()
Stop and remove all cameras that have been started in this room.
public void removeAllStreams()
Stop and remove all streams that have been started in this room.
public void removeCamera (ApideoCamera camera)
Stop and remove the camera from the page.
public void removeStream (ApideoViewer viewer)
Stop and remove a played stream from the page
public void sendEvent (JSon event, string type, [boolean suppressEcho], [Object returnObject])
Send a message to other users.
public ApideoCamera startCamera (string divId, string streamId, [JsonObject config])
Starts broadcasting a video to the Apideo server.
public void unregisterListener (string type)
Unregister a listener for an event type.
public void unregisterOnError (Object callback)
Unregisters a callback function that is called when an error occurs in the Apideo room.
public boolean unregisterOnLoad (Object callback)
Unregisters a callback function that was called when the Apideo room was successfully joined.
public boolean unregisterOnSecurityError (Object callback)
Unregisters a callback function that is called when a security error occurs in the Apideo room.
public boolean unregisterOnUserJoin (Object callback)
Unregisters a callback function that was called when a new user joined the Apideo room.
public boolean unregisterOnUserQuit (Object callback)
Unregisters a callback function that was called when a new user joined the Apideo room.
public boolean unregisterOnUserUpdate (Object callback)
Unregisters a callback function that was called when a new user joined the Apideo room.
public void updateUserData (JsonObject userData, boolean suppressEcho)
Send an updated description of the user to the other members of the room.

Function Details

function countUsers

public void countUsers(function filter)
Returns the count of users in this room. The function accepts an optional parameter "filter".
Parameters:
filter - An optional filter function. It must return true or false.

function forEachUser

public void forEachUser(function callback, function filter)
This function performs a "for each" on the list of users in the room.

For each user, the callback function passed in parameter is called.

The callback function takes 4 parameters:

  • userId (string): this is the unique ID of the user in that room
  • userObj (JSON object): this is the JSON object that has been passed by the user when joining the room (or when calling updateUserData)
  • joinTimeStamp (Date): this is the time when the user joined the room, expressed as a Date object
  • modifyTimeStamp (Date): this is the time marking the last call to the updateUserData function for that user, expressed as a Date object. If the object was never modified, this is equal to joinTimeStamp.

For instance:

 room.forEachUser(function(userId, userObj, joinTimeStamp, modifyTimeStamp) {
 		// Put code that must be applied for each user here
 });

The second parameter is optional. It is a filter function. For each user, this function will be called before the callback. The callback will be called only if the filter returns true.

The filter function has the same signature as the callback function, so it takes 4 parameters:

  • userId (string): this is the unique ID of the user in that room
  • userObj (JSON object): this is the JSON object that has been passed by the user when joining the room (or when calling updateUserData)
  • joinTimeStamp (Date): this is the time when the user joined the room, expressed as a Date object
  • modifyTimeStamp (Date): this is the time marking the last call to the updateUserData function for that user, expressed as a Date object. If the object was never modified, this is equal to joinTimeStamp.

For instance:

 room.forEachUser(function(userId, userObj, joinTimeStamp, modifyTimeStamp) {
 		// Put code that must be applied for each user here
 }, function(userId, userObj, joinTimeStamp, modifyTimeStamp) {
 		if (userObj.type=="visitor") {
 			return true;
 		} else {
 			return false;
 		}
 });

In this example, the callback will be called only for users whose "type" is visitor. The "type" is part of the user profile sent when the user joined the room.

Parameters:
callback - The function that will be called for each user.
filter - An optional filter function. It must return true or false.

function getMyUserData

public void getMyUserData()
Returns the user data associated for the local user.

The user data is the object passed in parameter by the user when he connects to the room (see the joinRoom method). The user data can also be updated by the user if he calls the userUpdateData method.

This function is a shortcut for:

 room.getUserData(room.getMyUserId());
Returns:
{JSON} The user data. *

function getMyUserId

public string getMyUserId()
Returns the ID of the user in the current room.

The ID is generated by the Apideo servers when the room is first joined.

You cannot recover the ID before the ApideoRoom.onLoad event is called. Any attempt to get the ID before the ApideoRoom.onLoad event is called will result in undefined behaviour.

The ID is a string.

Returns:
{string} The ID of the current user.

function getUserData

public void getUserData(string userId)
Returns the user data associated with the ID of the user that is passed in parameter.

The user data is the object passed in parameter by the user when he connects to the room (see the joinRoom method). The user data can also be updated by the user if he calls the userUpdateData method.

Parameters:
userId - The ID of the user
Returns:
{JSON} The user data.

function getUserJoinDate

public void getUserJoinDate(string userId)
Returns the time when the user passed in parameter joined this room.

The join date corresponds to a server time, not a browser time. Therefore, you can trust it as being secure. A hacker cannot modify this timestamp. You should rely on this timestamp in use case where you want to order users in a list by arrival date for instance.

Parameters:
userId - The ID of the user
Returns:
{Date} The date.

function getUserModifyDate

public void getUserModifyDate(string userId)
Returns the time when the user passed in parameter modified his user data for this room.

If the user data was never modified, the join date is returned.

The modify date corresponds to a server time, not a browser time. Therefore, you can trust it as being secure. A hacker cannot modify this timestamp. You should rely on this timestamp in use case where you want to order users in a list by arrival date for instance.

Parameters:
userId - The ID of the user
Returns:
{Date} The date.

function hasCamera

public boolean hasCamera()
Returns true if there is at least one webcam connected to this computer, false otherwise.

This function returns true if a webcam is available on the user's computer.

In order to call this function, the room must have been joined. Therefore, you should never call this function without first testing for room load.

Typically, some code to detect the availability of a camera should look like this:

 conn = Apideo.connect("XXXXXXXXXXXXXXXXXX")
 room = conn.joinRoom("myroom")
 room.onLoad(function() {
 	if (!room.hasCamera()) {
 		alert("Sorry, no webcam detected");
  }
 });
Returns:
{boolean} True if the user has at least one webcam connected to its computer. False otherwise.

function hasMicrophone

public boolean hasMicrophone()
Returns true if there is at least one microphone connected to this computer, false otherwise.

This function returns true if a microphone is available on the user's computer.

In order to call this function, the room must have been joined. Therefore, you should never call this function without first testing for room load.

Typically, some code to detect the availability of a camera should look like this:

 conn = Apideo.connect("XXXXXXXXXXXXXXXXXX")
 room = conn.joinRoom("myroom")
 room.onLoad(function() {
 	if (!room.hasMicrophone()) {
 		alert("Sorry, no microphone detected");
  }
 });
Returns:
{boolean} True if the user has at least one microphone connected to its computer. False otherwise.

function onError

public void onError(Object callback)
Registers a callback function that will be called if an error occurs in the room.

Please note that if there is no event handler defined for the room, Apideo will provide a default one: a simple alert box will be displayed. As soon as you define one event handler, the default event handler is discarded.

Example usage:

 room.onError(function(category, type, msg) {
 		... your code goes here ...
 });

The scope of the function is the current room, so "this" in the function refers to the ApideoRoom the connection has been established to.

The parameters passed to the callback function are:

  • category {string} - The category of the error.
  • type {string} - The technical type of the error.
  • msg {string} - The message of the error.

The most important parameter is the category. It can be one of:

  • connect - An error occured while connecting to the room.
  • disconnect - An connection error occured: the room has been disconnected.
  • error - An internal error occured.
  • server - An error occured on the server-side.
  • camera - An error occured with a camera started in this room. This kind of error is thrown only if no event handler is attached to the camera.
  • viewer - An error occured with a stream viewed in this room. This kind of error is thrown only if no event handler is attached to the stream played.
Parameters:
callback

function onLoad

public boolean onLoad(Object callback)
Registers a callback function that will be called when the Apideo room is successfully joined.

Once this event has been called, you can access the room list using the userList attribute.

Example usage:

 room.onLoad(function() {
 		... your code goes here ...
 });

The scope of the function is the current room, so "this" in the function refers to the ApideoRoom the connection has been established to.

Parameters:
callback

function onSecurityError

public boolean onSecurityError(Object callback)
Registers a callback function that will be called if access to the room is denied by Apideo.

Access to a room can be rejected if it is requested from a wrong URL (see URL-based security) or if the token settings prevent access to the room (see Token-based security).

Please note that if there is no security event handler defined for the room, the default event handler for the room will be called.

Example usage:

 room.onSecurityError(function(category, type, msg) {
 		... your code goes here ...
 });

The scope of the function is the current room, so "this" in the function refers to the ApideoRoom the connection has been established to.

The parameters passed to the callback function are:

  • category {string} - The category of the error.
  • type {string} - The technical type of the error.
  • msg {string} - The message of the error.
Parameters:
callback

function onUserJoin

public boolean onUserJoin(Object callback)
Registers a callback function that will be called when a new user joins the Apideo room.

Example usage:

 room.onUserJoin(function(userId, userObj, userJoinDate) {
 		... your code goes here ...
 });

The scope of the function is the current room, so "this" in the function refers to the ApideoRoom the connection has been established to.

The parameters passed to the callback function are:

  • userId {string} - The unique ID of the new user.
  • userObj {JsonObject} - The Json object describing the new user.
  • userJoinDate {Date} - The date the user joined the room (this is "now" expressed by the server time).
Parameters:
callback

function onUserQuit

public boolean onUserQuit(Object callback)
Registers a callback function that will be called when a user quits the Apideo room.

Example usage:

 room.onUserQuit(function(userId, userObj, timestamp) {
 		... your code goes here ...
 });

The scope of the function is the current room, so "this" in the function refers to the ApideoRoom the connection has been established to.

The parameters passed to the callback function are:

  • userId {string} - The unique ID of the new user.
  • userObj {JsonObject} - The Json object describing the user.
  • timestamp {Date} - The time the user was removed from the room.
Parameters:
callback

function onUserUpdate

public boolean onUserUpdate(Object callback)
Registers a callback function that will be called when a user updates his JsonObject using the ApideoRoom.updateUser() method.

Example usage:

 room.onUserUpdate(function(userid, userobj, userJoinDate, userUpdateDate, oldUserObj) {
 		... your code goes here ...
 });

The scope of the function is the current room, so "this" in the function refers to the ApideoRoom the connection has been established to.

The parameters passed to the callback function are:

  • userId {string} - The unique ID of the new user.
  • userObj {JsonObject} - The Json object describing the user.
  • userJoinDate {Date} - The date the user joined the room.
  • userUpdateDate {Date} - The last date the user updated its profile (this is "now" expressed by the server time).
  • oldUserObj {JsonObject} - The Json object describing the old object user that will be replaced.
Parameters:
callback

function playStream

public ApideoViewer playStream(string divId, string streamId, [JsonObject config])
Starts playing a video from the Apideo server.

This function will start playing a stream from the Apideo server.

The stream whose id is "streamId" will be played in the current webpage, inside the <div> element whose id is "divId".

If no stream "streamId" is published, no error will be triggered. Instead, the player will wait for such a stream to start.

The third parameter is the configuration of the stream played.

 config = {
 	width: [width],
 	height: [height],
 	}
  • config.width (integer) - the width of the video in the browser in pixels. Default value is 320.
  • config.height (integer) - the height of the video in the browser in pixels. Default value is 240.
  • config.logo.showLogo (boolean) - whether a logo should be displayed on top of the recorder or not. This parameter is only available to subscribers. For free accounts this defaults to true.
  • config.logo.logoUrl (string) - The logo's image URL. This parameter is only available to subscribers. For free accounts this defaults to the Apideo logo.
  • config.logo.onClickUrl (string) - The URL the user will be redirected to if he/she clicks on the logo. This parameter is only available to subscribers. For free accounts this defaults to the Apideo main page. If set to null, no redirection will happen when the logo is clicked.
  • config.logo.logoPosition (string) - The place the logo should be displayed. It can be one of: "topleft", "topright", "bottomleft", "bottomright". This parameter is only available to subscribers. For free accounts this defaults to "bottomright".

For optimal quality, you should set the width and height of the stream to the width and height of the video captured by the sender's webcam.

Parameters:
divId - The Id of the <div> element that will receive the stream image.
streamId - The stream ID
[config] - The config of the stream
Returns:
{ApideoViewer} The ApideoCamera object representing the camera.

function registerListener

public void registerListener(function(JsonObject event, string senderId, boolean triggerListener) eventListener, string type, [boolean blockPropagation])
Register a listener for an event type.

This function tells Apideo to execute the "eventListener" function each time an event whose type is "type" is received.

This means that if a message is sent to the "type" event stream, the "eventListener" function will be executed.

The signature of the function receiving the call is:

 function(JsonObject event, [string senderId], [boolean triggeredListener], [Date dateStamp])
  • event - the message that has been sent by the sendEvent function.
  • senderId (optional) - the unique ID of the sender. Each user is attributed a unique ID when he/she connects to the room.
  • triggeredListener (optional) - the type of the event that has been catched by the listener.
  • dateStamp (optional) - the date the event was received by the Apideo server. The Apideo server time is used for this date.

Event listener are organized hierarchically, using the "." special character. There can be only one event listener for a given "event type". However, many listeners can listen and answer to one sent event.

For instance, if an event is sent with the event type "all.chat.send", then Apideo will first trigger the listener "all.chat.send". Then, it will trigger the listener for "all.chat" and finally, the listener for "all".

The "blockPropagation" parameter enables the developer to stop this propagation. For instance, if a message is sent with the event type "all.chat.send" and if the developer registers a listener for the type "all.chat" with "blockPropagation" set to true, then the listener for "all" will not be called.

Parameters:
eventListener - The function that will be executed when an event is received.
type - The event type that will trigger this listener. Any events with a higher type in the hierarchy will be captured by this event type. For instance, if the type registered is set to "all.chat", events having "all.chat.send" or "all.chat.join" will trigger the listener.
[blockPropagation] - If true, listeners that listen to event types "below" this event type will not be triggered.

function removeAllCameras

public void removeAllCameras()
Stop and remove all cameras that have been started in this room.

function removeAllStreams

public void removeAllStreams()
Stop and remove all streams that have been started in this room.

function removeCamera

public void removeCamera(ApideoCamera camera)
Stop and remove the camera from the page.
Parameters:
camera - The camera object to be removed. This is the camera object instance you should have received when calling the ApideoRoom.startCamera method.

function removeStream

public void removeStream(ApideoViewer viewer)
Stop and remove a played stream from the page
Parameters:
viewer - The viewer object to be removed. This is the viewer object instance you should have received when calling the ApideoRoom.playStream method.

function sendEvent

public void sendEvent(JSon event, string type, [boolean suppressEcho], [Object returnObject])
Send a message to other users.

The "event" message can be a string, an integer, or any valid JSON object.

The message will be sent with the type "eventType" and any user that has joined the same room and that is listening to this event type or a parent event type will receive the message.

If suppressEcho = true, the message will not be sent to this connection, even if it is listening for that message.

If a "returnObject" is passed in parameter, the "onResult" method will be called when the event has been sent. There is one parameter to the "onResult" method, that contains the number of clients that received the message.

Parameters:
event - The message to be sent to other users.
type - The message type.
[suppressEcho] - If true, the user sending this message will not receive it, event it he is listening for that message.
[returnObject] - An object whose "onResult" function will be called, passing in parameters the number of users that received this message.

function startCamera

public ApideoCamera startCamera(string divId, string streamId, [JsonObject config])
Starts broadcasting a video to the Apideo server.

This function will start the computer's webcam and microphone and broadcast the signal to the Apideo server.

Furthermore, the user's video is displayed inside the browser, in the <div> element whose id is "divId".

The webcam does not start directly. The user is first prompted for authorization. In order to bypass the authorization question, each user can edit the settings of its Flash player, by visiting this url: http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager06.html

On this settings screen, the user will also have the opportunity to choose the default webcam that will be used with Apideo.

Each stream published to a room has a unique "streamId". If a stream with that id is already published, an error will be triggered.

The third parameter is the configuration of the camera.

 config = {
 	width: [width],
 	height: [height],
 	camera: {
 		startCamera: [true|false],
 		width: [width],
 		height: [height],
 		fps: [fps],
 		quality: [quality],
 		bandwidth: [bandwidth],
 		startMicrophone: [true|false],
 		micRate: [micRate],
 		autoThrottle: [true|false],
 		throttleRatio: [ratio] 
 		},
  logo: {
  	showLogo: [true|false],
  	logoUrl: [url],
  	onClickUrl: [url],
  	logoPosition: ["topleft" | "topright" | "bottomleft" | "bottomright"]
  	}
 	}
  • config.width (integer) - the width of the video in the browser in pixels. Default value is 320. Cannot be less than 215. You can also specify a value in percentage. For instance: "100%" to use all the width of the parent div.
  • config.height (integer) - the height of the video in the browser in pixels. Default value is 240. Cannot be less than 138. You can also specify a value in percentage. For instance: "100%" to use all the height of the parent div (be sure to set the height of the parent div explicitly).
  • config.camera.startCamera (boolean) - true to start the webcam, false to use only the microphone. Default value is true.
  • config.camera.width (integer) - the width of the stream captured by the webcam, in pixels. Default value is 320.
  • config.camera.height (integer) - the height of the stream captured by the webcam, in pixels. Default value is 240.
  • config.camera.fps (integer) - the number of frames per seconds captured by the camera. Default value is 30.
  • config.camera.bandwidth (integer) - the maximum bandwidth the stream will use, expressed in bytes/seconds. Default value is 30000.
  • config.camera.quality (integer) - a number between 0 and 100, setting the overall quality. Default value is 0. If set to 0, the quality will be automatically adjusted to the maximum bandwidth. 1 means the lowset quality possible (and maximum compression) 100 means full quality, no compression. 0 is the recommended value. If you set a value for the quality, the flash player will do its best to keep the quality by lowering the framerate if needed.
  • config.camera.startMicrophone (boolean) - true to start the microphone, false to use only the video only without sound. Default value is true.
  • config.camera.micRate (integer) - the microphone capture rate, in kHz. Can be one of 5, 8, 11, 22 et 44. Default value is 11.
  • config.camera.autoThrottle (boolean) - If true, Apideo will measure the available upload bandwidth before publishing the stream. If the upload bandwidth is less than the requested bandwidth (the config.camera.bandwidth parameter), the bandwidth will be automatically throttled. This ensures an optimal stream quality. Bandwidth measure takes about 1 second. Default value for this parameter is "true". We highly advice to keep this parameter to true, unless you can be sure of the available upload bandwidth.
  • config.camera.throttleRatio (double) - The ratio applied to the throttling. This is a number greater than 0 and less or equal to 1. For instance, if config.camera.bandwidth=30000, and if the measured available bandwidth is 10000 bytes/sec. If throttleRatio = 0.8, the stream will be published at 8000 bytes/sec. This will leave 2000 bytes/sec for other applications to upload data. Default value is 0.8.
  • config.logo.showLogo (boolean) - whether a logo should be displayed on top of the recorder or not. This parameter is only available to subscribers. For free accounts this defaults to true.
  • config.logo.logoUrl (string) - The logo's image URL. This parameter is only available to subscribers. For free accounts this defaults to the Apideo logo.
  • config.logo.onClickUrl (string) - The URL the user will be redirected to if he/she clicks on the logo. This parameter is only available to subscribers. For free accounts this defaults to the Apideo main page. If set to null, no redirection will happen when the logo is clicked.
  • config.logo.logoPosition (string) - The place the logo should be displayed. It can be one of: "topleft", "topright", "bottomleft", "bottomright". This parameter is only available to subscribers. For free accounts this defaults to "bottomright".
Parameters:
divId - The Id of the <div> element that will receive the camera image.
streamId - The stream ID
[config] - The config of the stream and camera
Returns:
{ApideoCamera} The ApideoCamera object representing the camera.

function unregisterListener

public void unregisterListener(string type)
Unregister a listener for an event type.
Parameters:
type - The event type that the listener was listening for.

function unregisterOnError

public void unregisterOnError(Object callback)
Unregisters a callback function that is called when an error occurs in the Apideo room.
Parameters:
callback

function unregisterOnLoad

public boolean unregisterOnLoad(Object callback)
Unregisters a callback function that was called when the Apideo room was successfully joined.
Parameters:
callback

function unregisterOnSecurityError

public boolean unregisterOnSecurityError(Object callback)
Unregisters a callback function that is called when a security error occurs in the Apideo room.
Parameters:
callback

function unregisterOnUserJoin

public boolean unregisterOnUserJoin(Object callback)
Unregisters a callback function that was called when a new user joined the Apideo room.
Parameters:
callback

function unregisterOnUserQuit

public boolean unregisterOnUserQuit(Object callback)
Unregisters a callback function that was called when a new user joined the Apideo room.
Parameters:
callback

function unregisterOnUserUpdate

public boolean unregisterOnUserUpdate(Object callback)
Unregisters a callback function that was called when a new user joined the Apideo room.
Parameters:
callback

function updateUserData

public void updateUserData(JsonObject userData, boolean suppressEcho)
Send an updated description of the user to the other members of the room.

Other users can listen to updated descriptions of a user by using the onUserUpdate event handler.

The method signature for catching ApideoRoom.onUserUpdate is:

 room.onUserUpdate(function(userId, userObj, userJoinDate, userUpdateDate, oldUserObj) {
 
 });
  • userId (string): the unique ID of the updated user
  • userObj (string): the JSon object sent by updateUserData
  • userJoinDate - The date the user joined the room.
  • userUpdateDate - The last date the user updated its profile (this is "now" expressed by the server time).
  • oldUserObj - The previous state of the JSon object (before it was replaced by the new object).
Parameters:
userData - The JsonObject describing this user.
suppressEcho - If true, the user updating its description will not receive the ApideoRoom.onUserUpdate event. Default is false.