Skip to content

Latest commit

 

History

History
117 lines (78 loc) · 4.57 KB

easyrtc_rooms.md

File metadata and controls

117 lines (78 loc) · 4.57 KB
Raw

EasyRTC: Rooms

EasyRTC Room Features

  • Clients can connect to one or more rooms
  • Clients can see all other clients in the same room
  • Server can restrict who gains access to rooms
  • Server can define room fields (variables) which are shared to all clients in a room

Default Room Behavior

  • If no room is specified the client will join a default room named "default"
  • Requested rooms will automatically be created if they don't currently exist
  • Clients see all other authenticated clients within the same room

Server Options which Effect Rooms

Room Options

  • roomAutoCreateEnable
    • Enables the creation of rooms from the API. Occurs when client joins a nonexistent room.
    • Defaults to: true
  • roomDefaultEnable
    • Enables connections joining a default room if it is not initially specified. If false, than a connection initially may be in no room.
    • Defaults to: true
  • roomDefaultFieldObj
    • Default fields which are set when a room is created. In form of {"fieldName":{fieldValue:, fieldOption:{isShared:}}[, ...]}
    • Defaults to: null
  • roomDefaultName
    • The default room a connection joins if it is not initially specified.
    • Defaults to: "default"

JavaScript Client API - Joining a room

easyrtc.joinRoom()

Joining a room is handled using the joinRoom function. This can be run before or after easyrtc.connect() or easyrtc.easyApp(). 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.

Format

easyrtc.joinRoom(roomName, roomParameters, successCB, failureCB)

Parameters

  • roomName - String. Unique room name
  • roomParameters - Can be null. Parameters set here are sent to the server and seen in the roomJoin event.
  • successCB - Success callback which expects a function(roomName). May be null. Is only called if client is already connected to the server.
  • failureCB - Failure callback which expects a function(errorCode, errorText, roomName). May be null. Is only called if client is already connected to the server.

JavaScript Client API - Leaving a room

easyrtc.leaveRoom()

Leaving a room is handled using the leaveRoom function, or through disconnecting.

Format

easyrtc.leaveRoom(roomName, successCB, failureCB)

Parameters

  • roomName - String. Unique room name
  • successCB - Success callback which expects a function(roomName). May be null. Is only called if client is already connected to the server.
  • failureCB - Failure callback which expects a function(errorCode, errorText, roomName). May be null. Is only called if client is already connected to the server.

Server - "roomCreate" Event

When a client has requested to create a room, the "roomCreate" event is fired. By setting a new listener for the "roomCreate" event, the default behavior can be overruled.

Note: The roomCreate event will be fired when a client requests to join a room which doesn't exist and the "roomAutoCreateEnable" option is set to true. Upon successful callback.

Common Uses:

  • Authenticate who is permitted to create rooms
  • Set roomField's
  • Perform application logic, where rooms may be matched to a database entry

Server - "roomJoin" Event

Controlling who can join an existing room, and what occurs when joining is controlled by a listener for the "roomJoin" event. By setting a new listener for the "roomJoin" event, the default behavior can be overruled.

Common Uses:

  • Authenticate who is permitted to join rooms
  • Set roomField's
  • Control which other clients receive an update that a client joined the room
  • Perform application logic, where rooms may be matched to a database entry

Server - "roomLeave" Event

When a client has requested to leave a room, the "roomLeave" event is fired. By setting a new listener for the "roomLeave" event, the default behavior can be overruled.

Common Uses:

  • Prevent a client from leaving a room
  • Set roomField's
  • Control which other clients receive an update that a client left the room
  • Perform application logic, where rooms may be matched to a database entry

If You Run Into Problems

Please feel free to post on our discussion forum: